String Writer

Extracted from Tridion manual but modified the code snippets for C# standards.

This topic provides you with implementation tips that are specific to the Tridion Object Model (TOM). Following these guidelines makes it easier to write and maintain your template code.

You can call external COM objects from inside your Template script just as you would inside ASP script. Script extensions enable you to use any COM object. The script extension enables any template to use this function when content is published or previewed. For example:

TDSE tdse = new TDSE();
Object objMyClass= tdse.GetNeweObject("MyCOMComponent.MyClass");
…
objMyClass = null;

Use the GetItems and GetListItems functions to retrieve items and to create lists of items within an Organizational Item (that is, a Structure Group, Folder, Search Folder, or Category). You can use these functions to build navigation structures or automatic lists.

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

// GetItems retrieves a collection of items
object objStructureGroup = null, objPage = null;
objStructureGroup = TDSE.GetObject("tcm:2-3-4", 1);
// Get all Pages (item type number 64) in this Structure Group
// as a collection of Page objects.
foreach(Page objPage in objStructureGroup.GetItems(64))
{
objPage.Publish("tcm:0-1-65538", false, false, false);
}
objStructureGroup = null;
objPage = null;

GetListItems returns an XML string 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.

GetListItems is not only a function on all Organizational Items (Structure Group, Folder, Search Folder, or Category) but also on the Publication object. When calling Publication.GetListItems(), you can add the Recursive filter, which retrieves all items in the entire Publication.

The Publication class also has a GetListOrganizationalItems() function, which works like GetListItems() but only returns Organizational Items. Use this function to:

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

Use 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.

Metadata values can be used in the following types of scenarios:

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

For example, you may want to use a metadata field on one of these items to specify the color of Pages in a specific Structure Group. To retrieve this information from the Page Template, you can then use the MetadataFields object.

objStructureGroup = Page.OrganizationalItem;
WriteOut(objStructureGroup.MetadataFields.Item("Color").Value(1));

For more examples about how you can use metadata fields, refer to the Content Management Implementation Guide.

To pass parameters from the Page Template to the Component Template, use the AddParameter and GetParameter functions.

XSLT natively supports the concept of parameters through xsl:param elements. These parameter declarations can be used on a rule level, but also on a “global” (stylesheet scope) level.

Global XSLT parameters are passed to the XSLT Processor. The ComponentPresentation object internally creates an XSLT Processor for an XSLT Component Template and supports parameters.

In the following example, a Page Template script passes parameters to the (XSLT) Component Templates. The Component Templates retrieve these parameters using GetParameters and use them.

[%
object lComponentPresentation = null, lCount = null;
foreach(ComponentPresentation cp in Page.ComponentPresentations)
{
cp.AddParameter("TestParam1", lCount);
cp.AddParameter("TestParam2", "Test");
WriteOut(cp.Content + "<hr>" + lCount = lCount + 1);
}
%]

Use the Search object to search for items. You can perform simple and advanced queries. The returned search results contain detailed information about each item found.

The Search object supports the following methods:

• GetSearchResults returns all search results.
• GetSearchResultsEx parses the search criteria previously passed to the Component and calls the Verity. Searchcomponent to obtain the search results. After obtaining the basic search results, the function further populates the array with Content Manager-specific information about each item.
• ReIndexAllPublications rebuilds the full-text search index for all Publications.
• ReIndexPublications rebuilds the full-text search index for a given Publications.
• ResultQuery returns the Verity Command Query that was used to obtain the last search results.
• SetSearchInstruction sets the parameters for search.

In the following example of a Page Template script, the Search object is passed an XML string and returns an XML string. This returned string is then searched and the Title of each item is written to the Page.

[%
#include "tcm:2-237-2048"
Dim objSearch
Dim strSearchString : strSearchString = "GSM OR Mobile"
Dim strSearchXML
Dim strSearchResults
Dim lNumberOfItems
Dim lElement
Dim objXMLResults
objSearch = TDSE.GetSearch
intNumberOfItems = 100
strSearchXML = "<tcm:SearchInstruction"
xmlns:tcm='http://www.tridion.com/ContentManager/5.0'
xmlns:xlink ='http://www.w3.org/1999/xlink'><tcm:SearchQuery"
strSearchXML = strSearchXML & strSearchString
strSearchXML = strSearchXML & "</tcm:SearchQuery> <tcm:SearchIn xlink:href='" & Component.Publication.ID & "' Recursive='1'/>"
</tcm:GeneralParameters><tcm:AdvancedParameters><tcm:NumberOfItems" & intNumberOfItems & "</tcm:NumberOfItems>
</tcm:AdvancedParameters></tcmSearchInstruction>"
Call objSearch.SetSearchInstruction(strSearchXML)
strSearchResults = objSearch.GetSearchResults
objXMLResults = GetNewDOMDocument()
objXMLResults.LoadXML(strSearchResults)
Dim nCount : nCount = 1
For Each lElement In objXMLResults.selectNodes("//tcm:Item")
WriteOut(lElement.getAttribute("Title") & "<BR>")
nCount = nCount + 1
Next
WriteOut(nCount & " results found.")
objXMLResults = Nothing
objSearch = Nothing
%]

Although it is possible to create a TDSE object by calling a COM Component, the preferred method is to use the global TDSE object.

Use the GetObject method of the TDSE object to access all items in the system. The following examples displays the title of a specific Folder:

[%
Folder objFolder = TDSE.GetObject("tcm:12-25-2", 1);
WriteOut("Folder name: " & objFolder.Title);
objFolder = null;
%]