Best practices for templating

To make it easier to write and maintain your template code, it is recommended to use Metadata and GetItems() and GetListItems().

Using GetItems() and GetListItems()

Use the GetItems() and GetListItems() methods to retrieve items and to create lists of items within a Content Manager container, such as a Folder or a Category. You can use these methods to build navigation structures or automatic lists.

GetItems() gets the contents of an Organizational Item in the form of a collection of TOM.NET objects.

// Retrieve the Pages in a given Structure Group and check if they are in use by other items.
StructureGroup structureGroup = (StructureGroup) engine.GetSession().GetObject("tcm:2-3-4");
// Define a filter to return only Pages.
OrganizationalItemItemsFilter filter = new OrganizationalItemItemsFilter(structureGroup.session)
{
	ItemTypes = new[] { ItemType.Page }
}
bool inUse = false;
// Iterate over all Pages (as a collection of Page objects) in this Structure Group.
foreach (Page page in structureGroup.GetItems(filter)) {
// Set inUse to true if any one Page is in use.
	inUse = inUse || page.HasUsingItems();
}

GetListItems() returns a DOM object containing the XML equivalent of the objects returned by GetItems(). If you only need the properties of the items, GetListItems() gives you much better performance. You can also select which attributes to include or exclude in the XML string, and filter the items returned. Like GetListItems(), GetListItems() is a methods for all classes that represent Content Manager containers, such as Publications or Virtual Folders.

The Publication class also has a GetListOrganizationalItems() function, which works like GetListItems() but only returns Organizational Items, that is, Folders, Virtual Folders, Categories and Structure Groups. Use this function to:

  • Create a report of a Publication's security structure.
  • Build an organizational item tree.

For more information, see Getting items.

Using metadata fields

Content designers can create metadata fields to specify custom properties for a Page, Structure Group, Folder or Publication. If metadata is added to these items using a Metadata Schema, you can then use the values in these fields during processing.

You can use metadata values in the following types of scenarios:

  • Localization
  • Archiving
  • Folder ownership
  • Directing publishing processes
  • Automatic publishing

For example, a content designer may create a metadata field for a Structure Group to specify the color scheme of Pages contained in that Structure Group. To retrieve this information from the Structure Group metadata, use the MetadataFields property.

// Find out the color scheme of a certain Structure Group.
StructureGroup structureGroup = (StructureGroup) engine.GetSession().GetObject("tcm:2-3-4");
ItemFields metadataFields = new ItemFields(structureGroup.Metadata, structureGroup.MetadataSchema);
if (metadataFields.Contains("ColorScheme")) 
{
	string colorScheme = metadataFields["ColorScheme"].ToString();
}

For more examples about how you can use metadata fields, refer to Metadata.