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.