Sitecore ORM Field Mapper

The Sitecore ORM / Field mapper capability in Atlas allows you to map Sitecore items to POCOs (C# objects).

Enabling the Mapper

In order to use the Atlas mapper, you need to register both the ItemMapper and an ICache implementation from Atlas. You can use the WebCache implementation that Atlas ships with for this purpose or implement your own. Refer to the caching documentation for details. Register the following dependencies against the DI container used on your project:

• Interface DeloitteDigital.Atlas.Mapping.IItemMapper, DeloitteDigital.Atlas with implementation DeloitteDigital.Atlas.Mapping.ItemMapper, DeloitteDigital.Atlas
• Interface DeloitteDigital.Atlas.Caching.ICache, DeloitteDigital.Atlas with implementation DeloitteDigital.Atlas.Caching.WebCache, DeloitteDigital.Atlas (or your own)

Using the Mapper

The mapper can be used in 2 simple steps:

1. Annotating your view model with mapping attributes (see the various mapping attributes below)
2. Calling the IItemMapper.Map<TViewModel>(Item item) method which returns a newly created and populated/mapped view model object

Create your view model

Create a new C# class to act as your view model and add public properties for all values that you want to map to Sitecore. The full list of available attributes is below, but an example view model might look like this:

public class Example 
{
    [FieldMap]
    public string Title { get; set; }
   
    [ChildrenMap(ChildrenMapType.Direct)]
    public Example Children { get; set; }
}

Map an instance of this class

Once registered, you can inject an IItemMapper into your controller renderings and start using it. If you are using the view rendering / rendering model capability in Atlas, then the item mapper is already available through the abstract RenderingModel base class. Refer to the view rendering documentation for details.

If you use the IItemMapper directly, you can either let the mapper create the instance of the view model for you:

var viewModel = ItemMapper.Map<Example>(item);

or you can pass in an already created object. The mapper will only act on the public properties with mapping annotations:

var viewModel = new Example();
return ItemMapper.Map(Example, item);

Field Mapping Attributes

The field mapping allows you to map Sitecore fields to view model properties by simply adding a [FieldMap] attribute. By convention, the name of the view model property should match the name of the field in Sitecore - however, the actual Sitecore field to use can be overwritten using a parameter on the attribute. You can use code-generated field names here to ensure that you pick up changes to Sitecore field names.

[FieldMap]
public string Title { get; set; }

[FieldMap]
public string MetaKeywords { get; set; }

[FieldMap]
public IFieldRenderingString KeyMessage { get; set; }

[FieldMap("GeneralText")] // note - consider using the code generated field name here instead of a "magic string"
public IFieldRenderingString Content { get; set; }

The field mapping attribute can be applied to a number of different property types:

• Bool (for e.g. checkbox field types in Sitecore)
• DateTime
• Int / Double
• FieldRenderingString / MediaRenderingString / LinkFieldRenderingString (refer to the FieldRenderingString documentation)
• String

Multilist Field Mapping

Atlas also supports mapping items selected in multilists (e.g. TreeList, Multilist field types - anything that stores a pipe separated list of IDs). The assumption is that all items selected in the multilist can be mapped to the same view model.

To apply this mapping, set the option on the FieldType parameter on the [FieldMap] attribute to FieldType.Multi.

[FieldMap(FieldType.Multi)]
public IEnumerable<SampleItem> SampleItems { get; set; }

Item Property Mapping Attribute

The item property mapping gives access to common metadata / properties on an item that are not fields. The following item properties are available to be mapped:

• Item ID (can be mapped to string, ID or GUID fields on a view model)

• Item URL

• Template ID (can be mapped to string, ID or GUID fields on a view model)

• Template Name

• Item Name

• Item Path

  [ItemPropertyMap(ItemPropertyMappingType.ItemName)] public string ItemName { get; set; }

  [ItemPropertyMap(ItemPropertyMappingType.ItemId)] public ID ItemId { get; set; }

  [ItemPropertyMap(ItemPropertyMappingType.ItemUrl)] public string ItemUrl { get; set; }

Children Mapping Attribute

Atlas comes with support for basic child item mapping (basic because all children have to be of the same type and this should not be used to map items in the IA with a lot of children). This mapping supports a number of different ways to get the "children":

• ChildrenMapType.Direct - children of the current item
• ChildrenMapType.Id - children of the item with the given ID
• ChildrenMapType.Path - children of the item with the given Path
• ChildrenMapType.Field - children of the item referred to in the given field (e.g. droptree / droplink field)
• ChildrenMapType.Query - children of the item referred to in the given query

Note: The child mapping is recursive. Do not use it for IA items (e.g. for navigation components). It could potentially try to map thousands of items. The intention of this attribute is for content modules where the children of the data source item are mapped (e.g. content authored featured links, accordion modules).

[ChildrenMap(ChildrenMapType.Direct)]
public IEnumerable<SampleItem> Children { get; set; }
 
[ChildrenMap("{54D6DA31-8DFD-424E-B38F-2516D5C49962}", ChildrenMapType.Id)]
public IEnumerable<SampleItem> SampleItems { get; set; }

[ChildrenMap("ConfigItem", ChildrenMapType.Field)]
public IEnumerable<SampleItem> ConfigItems { get; set; }

Rendering Parameter Mapping Attribute

The rendering parameter mapping gives access to rendering parameters (mapped to strings, bool and int properties on a view model). Set up your rendering parameters in Sitecore (using the out of the box key/value or rendering parameter templates):

[RenderingParameterMap("MyStringParameter")]
public string MyStringRenderingParameter { get; set; }

[RenderingParameterMap("MyBoolParameter")]
public bool MyBoolRenderingParameter { get; set; }

Dictionary Mapping Attribute

The dictionary mapping gives access to the dictionary feature in Sitecore (mapped to strings on a view model). Set up your Dictionary entries Sitecore:

[DictionaryMap("global.copyright")]
public string Copyright { get; set; }