Regular or retrofit modes for mapping View Models to Schemas

DXA performs intelligent, automatic mapping from View Models to Schemas. To map your View Models to Schemas and the View Model properties to Schema fields, you typically use generated, default semantics. The way in which this is done differs depending on the use of regular mode or retrofit mode.

Mapping in regular or retrofit mode

Use of generated, default semantics for View Model mapping replaces specifying explicit Schema and Schema field semantics in Content Manager. When using automatic mapping of View Models to Schemas, DXA makes an assumption that all Schema root element names are unique, which is the case for the Example Site Content Model and is strongly recommended for new Content Model implementations. This is regular mode.

In contrast, pre-existing Content Models have Schemas with the root elements of Schemas are, by default, called simply Content. The retrofit mode for mapping ensures that Schemas and Schema fields are mapped to unique identifiers on the DXA side.

The retrofitMode parameter in the Publish Mappings Template Building Block (TBB) determines whether mapping is in regular or retrofit mode. The Publish Mappings TBB is invoked by the Publish Settings Component Template, which is located in the Folder 100 Master/Building Blocks/Framework/Developer/Templates/.

The following example shows the parameter with its default value of false (for regular mode):

<CompoundTemplate xmlns="http://www.tridion.com/ContentManager/5.3/CompoundTemplate">
  <TemplateInvocation>
    <Template xlink:href="tcm:2-1508-2048" xmlns:xlink="http://www.w3.org/1999/xlink" xlink:title="Publish Mappings" />
    <TemplateParameters>
      <Parameters xmlns="http://www.sdl.com/web/schemas/publishmappings">
        <retrofitMode xmlns="http://www.sdl.com/web/schemas/publishmappings">false</retrofitMode>
      </Parameters>
    </TemplateParameters>
  </TemplateInvocation>
</CompoundTemplate>

In regular mode, the generated semantics are based on the Title field of the Schema, the name of its root element, and the name of its fields.

On the Content Manager side, the following happens:
Schemas
Schemas get a semantic type in the DXA core vocabulary, http://www.sdl.com/web/schemas/core. The name of the semantic type is one of the following:
  • The name of the root element, if the Schema is a Component Schema or an embedded Schema
  • The Title field (alphanumeric characters only) of the Schema, if the Schema is a Multimedia Schemas or a Metadata Schemas
Schema fields
Schema Fields get a semantic property in the DXA core vocabulary. The name of the property is the Schema field's XML name.
On the View Model side, the following happens:
View Model types
View Model types get a semantic type in the DXA core vocabulary. The name of the semantic type is equal to the name of the View Model type.
View Model properties
View Model properties get a semantic property in the DXA core vocabulary. The name of the semantic property is equal to the name of the View Model property with the following changes applied:
  • The first character is made lowercase.
  • If the property is a List type, any trailing "s" is removed from the end of the name.

To achieve implicit mapping from View Model types to Schemas and from View Model properties to Schema fields, ensure that View Model type names correspond to Schema names, and that View Model property names correspond to Schema field names.

Retrofit mode

To change mapping to retrofit mode,

  1. Modify the Publish Mappings Template Building Block within the Publish Settings Component Template.
  2. Change the value of the retrofitMode parameter to true.
  3. Republish the Publish Settings page located in 100 Master/Home/_System.
  4. Go to your web application and add /admin/refresh to the URL and press Enter. refresh the cache and reload the settings in the web application. You will be redirected to the homepage and the new settings will be in place.
When in retrofit mode, View Model mapping works as follows:
Schemas
Each Schema that is not an embedded Schema gets its own semantic vocabulary. The vocabulary ID is the namespace URI of the Schema. A vocabulary prefix of the form sSCHEMAID is used, where SCHEMAID is the ID of the Schema. The prefix makes it possible to distinguish two Schemas that have the same namespace URI (and therefore also have the same semantic vocabulary).
Schema fields
Schema fields get a semantic property in the Schema's vocabulary. The name of the semantic property is that of the Schema field's XML name. If the field is embedded, it gets the following two semantic properties:
  • One semantic property in the vocabulary of the embedding Schema
  • One semantic property in the DXA core vocabulary representing the field in the embedded Schema, to enable mappings for the embedded Schema (regardless of where it is embedded).

Retrofit mode avoids the problem of non-unique Schema root elements; however, implicit mapping from View Model types to Schemas and from View Model properties to Schema fields cannot be achieved quite so easily. You need to ensure that your Schema namespace URI is identical to the URI of the DXA core vocabulary (which is true for most DXA Core Module Schemas). In practice, you will probably need to create explicit mappings from the View Models to the Schema's vocabulary (namespace URI).

Here is an example of semantic View Model annotations (.NET) used in retrofit mode:

public abstract class Tsi1757TestEntity : EntityModel
{
}

[SemanticEntity(Prefix = "s1", Vocab = "uuid:a3cbac3c-375a-43d3-937e-788110d6b9ee", EntityName = "Content")]
public class Tsi1757TestEntity1 : Tsi1757TestEntity
{
  [SemanticProperty("s1:textField")]
  public string TextField { get; set; }
  [SemanticProperty("s1:embeddedTextField")]
  public string EmbeddedTextField { get; set; }
}

[SemanticEntity(Prefix = "s2", Vocab = "uuid:3a50c82e-f113-4e7d-94f5-23359b3b0a4e", EntityName = "Content")]
public class Tsi1757TestEntity2 : Tsi1757TestEntity
{
  [SemanticProperty("s2:textField")]
  public string TextField { get; set; }
}
]
[SemanticEntity(Prefix = "s3", Vocab = "uuid:e6b74fb5-d407-4baa-ab53-ef1bc0b72887", EntityName = "Content")]
public class Tsi1757TestEntity3 : Tsi1757TestEntity
{
  [SemanticProperty("s3:textField")]
  public string TextField { get; set; }
  [SemanticProperty("s3:compLinkField")]
  public List<Tsi1757TestEntity> CompLinkField { get; set; }
}