Mapping Page Properties to Occurrences |
Top Previous Next |
The TMCore EPiServer Module also allows the administrator to map page properties to occurrence values, so that when an editor updates a property on the page an occurrence is created on the topic for the page containing either the value of the page property, or a derivation of it. The mappings are specified in the web.config file using a new configuration section. At the top of the web.config file declare the following configuration section: <sectionGroup name="TMCoreEPiServerModule"> <section name="OccurrenceMappings" allowLocation="false" type="NetworkedPlanet.EPiServerModule.FieldMapper.ConfigurationSectionHandler, NetworkedPlanet.EPiServerModule, Culture=neutral, PublicKeyToken=da294bc4e1ae447d"/> </sectionGroup> Then as a direct child of the <configuration> top-level element add the following: <TMCoreEPiServerModule> <OccurrenceMappings> </OccurrenceMappings> </TMCoreEPiServerModule> Within the <OccurrenceMappings> element you may define individual mappings in the following format: <mapping pageTypeName="epiPageTypeName" pageFieldName="epiPropertyName" occurrenceTypeSI="subjectIdentifier" occurrenceData="resource|value" addOnPublish="true|false" serializerType="typeName" /> <mapping> elements may not be nested. The attributes are interpreted as follows:
Attributes of the mapping element for defining occurrence mappings If an invalid mapping is detected, then an error message will be printed out in the EPiServer log. No other cues are given to the administrator that a mapping has failed (i.e. if a mapping fails then EPiServer will continue to function normally). Example Mappings The following is a very simple mapping that makes use of all the defaults to create a value occurrence for the value of the name property on any instance of page Person. <mapping pageTypeName="Person" pageFieldName="name" occurrenceTypeSI="http://psi.networkedplanet.com/occurrences/name" /> The following mapping shows how you can use a custom serializer to process an occurrence value. This serialize takes a date of birth field for a person and stores in the topic map the name of the season that user was born. The code for the serializer is shown below: <mapping pageTypeName="Person" pageFieldName="dateofbirth" occurrenceTypeSI="http://psi.networkedplanet.com/occurrences/seasonBorn" addOnPublish="false" serializerType="NetworkedPlanet.EPiServerModule.FieldMapper.SeasonBornSerializer,NetworkedPlanet.EPiServerModule, Culture=Neutral, PublicKeyToken=da294bc4e1ae447d" />
using System; using EPiServer.Core; namespace NetworkedPlanet.EPiServerModule.FieldMapper { /// <summary> /// Converts the <see cref="DateTime"/> property passed to the name of a season. /// </summary> public class SeasonBornSerializer : IOccurrenceValueSerializer { /// <summary> /// Serializes a property value to be serialized to a string in the form of an occurrence. /// </summary> /// <param name="page">The page containing the property. This is included in case the occurrence value needs derivation from other page properties.</param> /// <param name="property">The property that is being serialized.</param> /// <returns>A string value that will be placed in to the occurrence.</returns> public string Serialize(PageData page, PropertyData property) { string season = String.Empty; if (property.Value!=null) { DateTime dt = (DateTime) property.Value; switch(dt.Month) { case 12: case 1: case 2: season = "Winter"; break; case 3: case 4: case 5: season = "Spring"; break; case 6: case 7: case 8: season = "Summer"; break; case 9: case 10: case 11: season = "Autumn (Fall)"; break; } } return season; } } } As you can see from the code, if the value for the month cannot be parsed (for example, because no date has been specified), then the empty string is returned, which is equivalent to returning null, which instructs the TMCore EPiServer Module to not create an occurrence (or remove an existing one). Restrictions & Caveats DO NOT use different values for addOnPublish when using the same occurrence type and same page type. An example of this would be: <mapping pageTypeName="Person" pageFieldName="firstName" occurrenceTypeSI="http://psi.networkedplanet.com/occurrences/name" addOnPublish="false" /> <mapping pageTypeName="Person" pageFieldName="secondName" occurrenceTypeSI="http://psi.networkedplanet.com/occurrences/name" addOnPublish="true" /> Here, the mapping is trying to instruct the TMCore EPiServer Module to update the occurrence for someone's first name whenever the page is saved, but only update their last name when the page is published. This will not work and you will observe the following effect:
This happens because the TMCore EPiServer Module can't tell whether an occurrence on the topic is meant to be there or not. When the page is saved the TMCore EPiServer Module needs a way to ignore occurrences that are only meant to be updated on publish (i.e. not update them). When a page property is updated the old value of the property is not available, therefore it is not possible to find the occurrence that was created for the old values - the best we can do if look for an occurrence of the correct type. If the occurrence created with addOnPublish=false has the same type as the occurrence created with addOnPublish=true the TMCore EPiServer Module cannot determine whether an existing occurrence is the old value of the "secondName" property or if it is an old value of the "firstName" property that should be overwritten. To work around this either:
|