Working with Template Objects

Template objects are Synthesis’ single most important feature. They are the concrete classes and interfaces that result from the Generator, and represent Sitecore templates in code. Template objects are capable of both reading and writing values, and abstract out many of the boilerplate code situations that are encountered when using Sitecore’s built in field types. It’s very easy to convert a Sitecore Item class into a strongly typed template object (and back again, if need be). All Template Objects have common features that a Sitecore Item would have, such as ID, TemplateID, Database, Language, Name, Paths, Axes, and Statistics. These work exactly like their Item equivalents, except for Axes. The Synthesis Axes object returns Template Objects instead of Items. Synthesis also adds a Url property that gets the correct link for the object. There is an InnerItem property that lets you get at the underlying Item, but use it only when absolutely necessary - the Synthesis API is always preferable as it separates concerns.

Transforming Items into Template Objects

At its heart Synthesis’ Template Objects are just a strongly typed wrapper around a Sitecore Item instance or a search index result. There are three primary methods you can use to obtain Template Objects:

1. You can implement a Presentation Framework View rendering, which is automatically supplied the rendering's data source as a Template Object. This method is appropriate to use when implementing renderings. See the section on the Presentation Framework for additional details.
2. There is a set of extension methods defined in the Synthesis.Extensions namespace that allow you to transform Sitecore API objects (Item) and collections (IEnumerable<Item>) into Template Objects.
   • Item.AsStronglyTyped() converts an Item into its Template Object equivalent. An IStandardTemplateItem is returned, but is the actual template type.
   • Item.As<T>() converts an Item into its Template Object equivalent and expects the result to be of a particular type. If the item does not resolve to that type, null will be returned instead.
   • IEnumerable<Item>.AsStronglyTypedCollection() converts a collection of items into an IEnumerable<IStandardTemplateItem>(). Each item is its actual template type. Note: this uses lazy enumeration, so copy it to a collection if you plan to iterate over it several times.
   • IEnumerable<Item>.AsStronglyTypedCollectionOf<T>() converts a collection of items into an IEnumerable<T> (a specific template object type). Any items in the original collection that are not representable using the requested template object type will be excluded from the resulting collection. Note: this uses lazy enumeration, so copy it to a collection if you plan to iterate over it several times.
3. Using a Sitecore 7 LINQ query to bind the results to Synthesis items. See the page about LINQ searching for more information on using this method.

Navigating the Item Tree with Template Objects

Once you have a Template Object, you may need to work with items in the Sitecore tree related to the object – parents, children, relative Sitecore queries, and other axis queries. Synthesis provides all template objects with an Axes property that gives you a façade to the Sitecore Item’s Axes property – only all the results are returned as Template Objects. This gives you the ability to manipulate the Sitecore tree without leaving Synthesis.

Note: Unlike a Sitecore Item object, the GetChildren method and Parent property are on the Axes property, not the actual Template Object.

Working with Fields

When you transform a Sitecore Item into a Synthesis Template Object, you gain strongly typed properties that represent each field on the item. These properties are not simply copies of the standard field classes Sitecore offers (i.e. LinkField, ImageField, LookupField), they are extensions that are designed to make it even easier to deal with fields and their values. There is a wide array of field types, from the simple TextField or IntegerField to an ItemReferenceListField (aka multilist).

Each of these types are mapped to one or more Sitecore field types by the Field Mapping Provider. See the section on configuration for more about how the Field Mapping Provider works.

This document does not dive into the details of each field type, as they should be easily discoverable using IntelliSense. That said there are some common features across Synthesis’ field types that are useful to be aware of.

• The fields that support FieldRenderer all have a RenderedValue property that allows you to get the value as it would be if a FieldRenderer was used. The default value of the field is never the rendered value; you must explicitly choose which fields you want to make editable in Page Editor Mode.
• Where it makes sense, the field may be implicitly cast to a primitive .NET data type that represents the field’s value (i.e. DateTimeField can be implicitly used as a DateTime, TextField as a string, etc.)
• They are all implicitly castable to their Sitecore field class equivalent (i.e. a DateTimeField can be cast directly to Sitecore’s DateField class).
• Field types that would be commonly rendered onto ASP.NET web controls (images, links) have Attach methods that allow you to quickly attach the field’s value to the relevant properties of a control (image alt text, link titles and targets, etc.) or render them to HtmlTextWriter for use in WebControl renderings.

Saving Template Objects to Sitecore

Synthesis fully supports editing Template Objects and persisting the results back to Sitecore. The editing API is largely identical to the Sitecore API. Synthesis extends the Sitecore editing API to allow you to set individual property values without explicitly putting the item in edit mode – Synthesis will transparently place the item in edit mode if it needs to when a field’s value is set, and restore editing mode to the way it was when it’s done. You should still place the item in edit mode manually if editing more than one field for performance reasons.

ISamplePageItem typedTemplateObject;

// changes to a single field can use the automatic edit context features
typedTemplateObject.Title.RawValue = "Hello, world";

// you can use SynthesisEditContext just like EditContext in the Sitecore API
using (new SynthesisEditContext(typedTemplateObject))
{
	typedTemplateObject.Title.RawValue = "Hello, world";
}
		
// you can use templateObject.Editing just like the Sitecore API
try
{
	testTemplateObject.Editing.BeginEdit();
 
	typedTemplateObject.Title.RawValue = "Hello, world";
}
finally
{
	testTemplateObject.Editing.EndEdit();
}

Adding Items

Synthesis provides the ability to add strongly typed items directly using the Add method. This method works exactly like the Add method on a normal Item instance, except that the template type is inferred using a Synthesis concrete type instead. The following example creates a new "My Page" item under /sitecore/content using this API, and then sets the display name after creating the item:

var home = Factory.GetDatabase("master").GetItem("/sitecore/content").AsStronglyTyped();

// note that you must use a concrete item type here - interfaces are not allowed
var newItem = home.Add<MyPage>("Hello world");
using (new SynthesisEditContext(newItem))
{
	newItem.DisplayName = "Goodbye world";
}