Advanced Mapping

Constellation.Foundation.ModelMapping contains Property Attribute decorators that can be added to your ViewModel’s properties to change the default mapping behaviors. ModelMapping also contains mapping classes to handle properties of complex fields that descend from Sitecore’s XmlField type.

Property Attributes

Do Not Map Attribute

If your ViewModel has properties that match Item Field Names, but should not be mapped, add the [DoNotMap] attribute to the property.

Field Renderer Params Attribute

If you are using a string or HtmlString property that will execute FieldRenderer, you may need to pass additional information to the renderer. The [FieldRendererParams()] attribute supports passing name-value pairs in querystring format. You can use this attribute to pass image size adjustments as well as CSS or HTML attributes that will be added to the outbound HTML element.

Raw Value Only Attribute

If you do not want to execute FieldRenderer (perhaps because the Field in question should not be available for Experience Editor in the given context) you can add the [RawValueOnly] attribute to your property and ModelMapper will supply the Field.Value directly and unaltered.

Render As URL Attribute

Often all you need from a field is the URL of the target Item or Image. To restrict the output of a field that would otherwise pass through FieldRenderer and produce markup, you can add the [RenderAsUrl] attribute to your string property.

The Render As URL attribute contains an additional switch for convenience. Occasionally a View will only need the URL off of a field when rendered in Normal mode, but the field needs to be editable in Page Editor. Rather than having to program complex logic into your controller, you can re-use the same property as follows: [RenderAsUrl(useFieldRenderInEditor=true)] Now, when the page is open in Experience Editor (Sitecore.Context.PageMode.IsExperienceEditorEditing) the FieldRenderer will render the field, otherewise, the field’s value will simply be a URL.

Field Types that support the Render As URL Attribute:

  • Droplink
  • DropList (and variants)
  • DropTree
  • File
  • General Link (and variants)
  • Image

Note that the URL produced will be from the context LinkManager if the Field points to an Item (Internal Link). If the URL points to an Image or File Item, the context MediaManager will be used. If the URL points to an external source, the URL as provided will be output.

Mapping XML Field Attributes to ViewModel Properties

The Image and General Link fields internally derive from Sitecore.Data.Fields.XmlField, and as such, their implementation in Sitecore is exposed through a custom Field type that offers properties to expose Attributes stored within the fields’ internal XML value.

To access these extra properties on a ViewModel, create compound-name properties that include both the Field name and the Attribute name you want to access.

Attribute Properties Available for General Link Fields

  • Anchor
  • Class
  • Target
  • TargetItem
  • Text
  • Title
  • Url

Example: For a General Link field named “More Information” you would create ViewModel properties as follows:

public class ViewModel
{
    // Use this first property for Experience Editor support
    public string MoreInformation { get; set; }

    // This property is for the Anchor tag's "name" attribute
    public string MoreInformationAnchor { get; set; }

    // This property is for the Anchor tag's "class" attribute
    public string MoreInformationClass { get; set; }

    // This property is for the Anchor tag's "target" attribute, not Sitecore's Target Item
    public string MoreInformationTarget { get; set; }

    // Maps the Internal Link's target Item to a new ViewModel
    public AnotherViewModel MoreInformationTargetItem { get; set; }

    // This property is for the Anchor tag's inner text
    public string MoreInformationText { get; set; }

    // This property is for the Anchor tag's "title" attribute
    public string MoreInformationTitle { get; set; }

    // This will either give you the external URL or call LinkManager or MediaManager to get the URL
    public string MoreInformationUrl { get; set; }
}

Attribute Properties Available for Image Fields

  • Alt
  • Height
  • Width

Example: For an Image Field named Heading Image you would create a ViewModel as follows:

public class ViewModel
{
    // Use this first property for Experience Editor support
    [RenderAsUrl(true)]
    public string HeadingImage{ get; set; }

    // This property is for the img tag's "alt" attribute
    public string HeadingImageAlt { get; set; }

    // This property is for the img tag's "height" attribute
    public string HeadingImageHeight { get; set; }

    // This property is for the img tag's "width" attribute
    public string HeadingImageWidth { get; set; }
}

Note that Image fields don’t natively support class or src attributes, but they can be added to your output using the [FieldRendererParams()] attribute if desired.