Customizing & Extending

Constellation.Foundation.ModelMapping relies on a single configuration file that ships with the NuGet package. Regardless of whether you plan on building your own Mapping classes, you should review the file to get a better idea of how ModelMapper does its job.

Configuration File

The configuration has just a few options:

  • Specify the default field mapper

    Constellation.Foundation.ModelMapping.FieldMappers.TextFieldMapper
    is the default.

  • Specify whether ModelMapper should ignore Sitecore Standard Fields
    Standard fields are ignored by default.
  • Specify whether ModelMapper should continue if it encounters an error.
    Continue-on-error is true by default, but if you’re having problems, or you’ve built a custom Field Mapper, you might want to turn this off.
  • Specify which mappers should be used for each of the Sitecore Field types.

This last bit is the majority of the configuration file, and is the first place you should look if you’re not getting the result you’re expecting when mapping.

Field Mapping Configuration

Each Sitecore Field in the configuration file has a configuration section where the field name is specified. Within that section, one or more Field Mapper or Field Attribute Mappers are defined.

The ModelMapper reads the Field type on the Item about to be mapped, and then determines which mappers to run based on the field type.

Why multiple Field Mappers?

It’s possible that a particular FieldMapper isn’t appropriate for a given scenario. In that case, it will register the fact that it couldn’t map, and the Mapper will try the next FieldMapper class in the config. Be aware that the last FieldMapper that can successfully map the value to a property is the “winner”. Order matters.

When you review the configuration file you’ll also notice that some Field Mappers can be applied to multiple Field Types, In this case you may want to add/remove/customize exactly which mappers are used to get a more precise result.

Why multiple Field Attribute Mappers?

Field Attribute Mappers are much more straightforward, and you would generally only have one Attribute Mapper per Attribute scenario (for example, resolving the “height” value on an Image Field does not require multiple attempts…)

Mapping Limitations

You can only have one set of Mappers defined for a given field type. All Fields of that type will pass through the same mapping processors regardless of where they come from or what you need them to do. If you need more control, you’re probably better off assembling your ViewModel’s properties using logic in your Controller, rather than relying on ModelMapper.

Extending the Configuration File

Please note that Constellation follows Sitecore Helix practices. You should never modify the configuration file directly, as it will be overwritten the next time you update the NuGet package. Treat Constellation config files as if they were stock Sitecore config files. Use Sitecore’s XML patch syntax to create a patch config file specific to your project/installation/server and list your configuration overrides there.

Customization Opportunities

Add a new FieldMapper to a Sitecore Field Type

Although the most common Sitecore Field Types are pretty well covered, you might want to add an existing Field or Field Attribute Mapper to one of these, or replace the “stock” mappers altogether.

All FieldMappers must descend from the base Constellation.Foundation.ModelMapping.FieldMappers.FieldMapper<T> class. There are a few methods you can override:

PropertyTypeMatches()

Use this method to determine if the property on the Model provided is of type T

ExtractStringValueFromField()

Use this method to convert the original Field value into a string that will be assigned to the Model’s property. Note that the default implementation calls FieldRenderer.Render().

ExtractTypedValueFromField()

Use this method to convert the original Field value into an instance of T.

Map(object modelInstance, Field field)

This is the main method of the Field Mapper and should only be overridden if you are prepared to handle all the conditions within it. The “stock” body handles things like Attribute detection on Model Properties, extracting the name of the Field, locating an appropriate target Property to map, determining whether the destination is a string or some other type, and some error handling.

Add a new Attribute Mapper to a Sitecore Field Type

If you are going to extend ModelMapping to handle new or currently un-handled XML field types, you will need to use Attribute Mappers to expose the field’s attributes as Properties on your ViewModels.

All Field Attribute Mappers must descend from the base Constellation.Foundation.ModelMapping.FieldMappers.FieldAttributeMapper class. There are a few methods you can override:

GetPropertyName()

Use this method to specify the suffix to use on ViewModel Properties so that your mapper will target the correct property.

GetValueToAssign()

Use this method to read the Field’s attribute and convert it to the expected output object.