Semantic mapping (Java)
SDL Digital Experience Accelerator provides default semantic mapping, but you can mapping fields explicitly, exclude properties from mapping, and map Schemas.
Default semantic mapping
- When attempting to populate a View Model property from the Content Manager model, look for a Schema field with the same name, but using
camelCasinginstead ofPascalCasing. For example, the propertyHeadlineis mapped to Schema fieldheadline. - When attempting to populate a property of type
List<T>, remove any trailing s's from the property name. For example, theParagraphsproperty is mapped to Schema fieldparagraph.
Mapping fields explicitly
If the default semantics are not sufficient, for example if the Schema field names do not make sensible View Model property names, you can specify the SemanticProperty attribute to map fields explicitly:
@SemanticProperty("internalLink")
public String link
Mapping multiple Schema fields to a single View Model property
If your link property contains an external or an internal link, modeled in the Content Manager using optional fields, internalLink (a Component Link) and externalLink (an External Link), you can specify semantic property attributes for both and the implementation will populate the model with whichever links it finds. You therefore do not have to put this logic in the Model or View.
@SemanticProperties({
@SemanticProperty("internalLink"),
@SemanticProperty("externallink"),
})
public String link
Mapping multiple Schemas to a single Entity
You can add SemanticEntity attributes to the View Model class to map multiple Schemas to a single Entity.
For example, a Teaser View Model is a generic block of content containing headline, summary text and link that you can use to create content teasers that link through to other content on the Web site. You have a corresponding Teaser Schema in the Content Manager, but you also want to use the Teaser views for other types of content that has similar fields, for example an article, or an event. Add SemanticEntity attributes to map the different field names in the different Schemas to a single Entity, or to control which fields map to which properties for each Schema:
package example.models;
import com.sdl.webapp.common.api.mapping.annotations.SemanticEntities;
import com.sdl.webapp.common.api.mapping.annotations.SemanticEntity;
import com.sdl.webapp.common.api.mapping.annotations.SemanticProperties;
import com.sdl.webapp.common.api.mapping.annotations.SemanticProperty;
import com.sdl.webapp.common.api.model.RichText;
import org.joda.time.DateTime;
import static com.sdl.webapp.common.api.mapping.config.SemanticVocabulary.SDL_CORE;
@SemanticEntities({
@SemanticEntity(entityName = "Event", vocabulary = SDL_CORE, prefix = "e"),
@SemanticEntity(entityName = "Article", vocabulary = SDL_CORE, prefix = "a"),
})
public class Teaser extends AbstractEntityModel {
@SemanticProperties({
@SemanticProperty("a:_self"),
@SemanticProperty("e:_self"),
})
private Link link;
@SemanticProperties({
@SemanticProperty("headline"),
@SemanticProperty("e:eventName"),
})
private String headline;
@SemanticProperties({
@SemanticProperty("a:introText"),
@SemanticProperty("e:description"),
})
private String summary;
public Link getLink() {
return link;
}
public void setLink(Link link) {
this.link = link;
}
public String getHeadline() {
return headline;
}
public void setHeadline(String headline) {
this.headline = headline;
}
public String getSummary() {
return summary;
}
public void setSummary (String text) {
this.summary = text;
}
@Override
public String toString() {
return "Teaser{" +
"link=" + link +
", headline='" + headline + '\'' +
", summary='" + text + '\'' +
'}';
}
}
SemanticEntityEntityNamemust correspond to the XML Root Element name on the Schema.Vocabmust match the Schema namespace.- use the
CoreVocabularydefault vocabulary To map from Schemas in the DXA Core _selfis a special syntax for links:- For a
StringorLinktype property, it will resolve a dynamic link to the source Component and put the result in the property value. - For a
MediaItemtype property, it will attempt map the whole source component to the property value, useful when creating summary or teaser Views/View Models which link through to the same content but show a different (complete) View/View Model.
- For a
Excluding properties from mapping
If you have View Model properties that you want to exclude from mapping, for example if part of your View Model is populated by search or an other external data source, you can specify exclusions for each single property:
@SemanticMappingIgnore
public class ContentList extends AbstractEntityModel {
}