[[PageOutline(2-3)]]

= Introduction =

The Advanced Stylization system introduced with [wiki:MapGuideRfc14 MapGuide RFC 14] presents an incredibly powerful way of modelling stylization of map features.  This is an area to document this system and to share useful symbol definitions.

== Documentation ==

Here are some pointers to existing documentation resources:

 * [wiki:MapGuideRfc14 RFC 14] itself, including the attached !LineUsage.doc

 * [wiki:MapGuideRfc29 RFC 29] which introduced some changes and has more useful information and examples of stylization.

 * Autodesk's [attachment:building_symbol_libraries.pdf Building Symbol Libraries] PDF is helpful

 * You need to be able to read and understand the [source:/branches/2.1/MgDev/Common/Schema/LayerDefinition-1.3.0.xsd LayerDefinition] and [source:/branches/2.1/MgDev/Common/Schema/SymbolDefinition-1.1.0.xsd SymbolDefinition] schemas

 * XPS ([http://www.microsoft.com/whdc/xps/xpsspecdwn.mspx XML Paper Specification]) - has information about the specific geometry syntax (e.g., how to draw a line or arc); see section 4.2.3 Abbreviated Geometry Syntax to see the geometry syntax that we use.

Please add additional wiki pages here to describe advanced stylization, and port the existing documentation as appropriate.

== Sample Packages ==

These are sample packages that help to explain specific concepts in advanced stylization.  When you download these, please be aware that some browsers (Internet Explorer for sure) will try to rename them to .zip.  Once they are downloaded, please ensure they have a .mgp extension before trying to import them into !MapGuide.

 * [attachment:ImageSymbolDemo.mgp?format=raw Image Symbol Demo] - This package imports into '''!Library://SymbolDemo/''' and contains a series of symbols showing how to reference image files, including: how to include these symbols in a !LayerDefinition, how to scale using map units, and how to expose attributes such as rotation to be overridden at the layer level. Once you have imported the package, preview the Map to see how the symbols appear (try zooming in and out to see how one is in !MappingUnits and the others are in !DisplayUnits).  Then explore the Layer in XML mode to see how these are referenced, including an override of the rotation angle of one symbol and setting another to be in fixed mapping units.  Finally, explore the symbol definitions themselves to see how to expose overridable parameters and to combine rasters with vectors in a single symbol.

Feel free to upload your own examples of advanced stylization here.  Try to limit the size and complexity of these examples to a single concept per package.  The wiki has a fixed maximum upload size, and this will also make the examples easier to understand.

== [wiki:AdvancedStylization/Library Symbol Library] ==

The [wiki:AdvancedStylization/Library Symbol Library] is a place to share symbol definitions with the community so we can distribute the work of creating these items.

== Performance Tips ==

These can be split out to their own page later if necessary

=== Avoid invoking expression engine ===

Advanced stylization is incredibly powerful in allowing you to alter almost every part of a style using feature properties and expressions.  However, when this is not needed it can be an unwanted performance burden.  From Walt Welton-Lair on the mailing list:

 For color, numeric, and boolean properties you don't need quotes.  The code first tries to evaluate the property as a constant, and only if that fails does it invoke the FDO expression engine.

 For properties which are evaluated as strings, use single quotes to avoid invoking the expression engine.  Examples:

 Specifying a constant label text:
{{{
<Text>'Park'</Text>
}}}

 Specifying a constant enumerated value:
{{{
<HorizontalAlignment>'Center'</HorizontalAlignment>
}}}

 In both examples leaving out the quotes will give the same result, but it will be slower.