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.

Note – while the features described here remain available, you should also consider using the new FieldModels for GeneralLink and Image fields. The specification for these new objects follows this section.

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

  • Src
  • 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
    public string HeadingImage{ get; set; }

    // This property is for the img tag's "src" attribute
    public string HeadingImageSrc {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; }
}

The Src suffix, when added to a Model Property representing an Image Field, will return the URL of the Media Library Image Item using the currently configured MediaManager options.

The Alt suffix will return the Image Field’s “Alt” text as defined on the mapped Item or, if not set there, the Media Item’s “Alt” text if available.

The Height suffix will return the Image Field’s “Height” value as defined on the mapped Item or, if not set there, the Media Item’s “Height” value.

The Width suffix will return the Image Field’s “Width” value as defined on the mapped Item or, if not set there, the Media Item’s “Width” value.

Note that Image fields doesn’t natively support the “Class” suffix, but it can be added to your output using the [FieldRendererParams()] attribute if desired.

Special Model Classes for XML Fields

General Link and Image Fields have a large number of properties that tend to be needed as a group. While it has been demonstrated above that you can grab any of these properties on your model with the appropriate suffix, sometimes it’s easier to have a more compact object. Introducing Field Models.

GeneralLinkModel

Assign this Class to one of your ViewModel properties like so:

public GeneralLinkModel LinkFieldName {get;set;}

GeneralLinkModel exposes the following string properties:

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

These behave identically to the suffix-style syntax described above.

There is also an HtmlString property:

  • Rendered

This property produces the equivalent to FieldRenderer.Render() and ensures your ViewModel is Experience Editor compatible.

ImageModel

Assign this Class to one of your ViewModel properties like so:

public ImageModel ImageFieldName {get;set;}

The ImageModel exposes the following string properties

  • Alt
  • Src
  • Height
  • Width

These behave identically to the suffix-style syntax described above.

There is an HtmlString property:

  • Rendered

This property produces the equivalent of FieldRenderer.Rener() and ensures your ViewModel is Experience Editor compatible.

ImageModel also has a number of Methods attached to it that allow you to request image URLs with custom dimensions:

  • GetCustomHeightImageSrc(int height)
  • GetCustomWidthImageSrc(int width)
  • GetCustomImageSrc(int width, int height, bool allowStretch, bool ignoreAspectRatio)

These methods are indispensable if you:

  • Have multiple Views that consume the same ViewModel but need different image sizes (as in multi-site, or Thumbnail views)
  • Use the <picture/> tag and srcsets to create responsive images.

When to use the new Field Models

  • If you need all or most of the Properties they expose, the General Link and Image models can save you a few lines of typing.
  • If you need to de-couple the Image URL from your Feature so that it can vary at the Project level, you should use ImageModel.