Content generators are server-side methods that create content when a specific schema element is initialized. These methods can be used to generate dynamic content, such as the table of data displayed in a default ItemInfo element. The first example below will demonstrate how we can use a content generator to dynamically display an assembly's BOM data and connect the document to your digital thread. The second example shows how to include a technical document's metadata into the document's content with a custom content generator. Lastly, the final example will demonstrate how a content generator can be used to create a default behavior - like automatically adding a child text element to every new table cell or list-item.
1. Display Item Data Dynamically
The default ItemInfo content generator populates the ItemInfo element with a table containing basic data from the selected item:
While it's great that this data is being populated dynamically based on the user's selection, this particular table may not fit every use case where we need to display item data in a document. Instead, we can define a new content generator method that queries the data we need and adds the necessary child elements to the ItemInfo element.
In the example below, our custom content generator inserts the following child elements:
- Title : Part's name
- Text : Part's description
- Text : Part's cost
- Text : Part's major rev, generation, state, created_on properties
The custom content generator also queries the database for the selected Part's BOM, retrieves the related Parts, and displays a table of BOM/related Part data.
To set up our custom content generator, let's create a new C# server method called Custom_ItemInfo_ContentGenerator and paste in the code from the editor below.
Note: It is important to keep the MethodTemplateName comment at the top of the method, as Aras uses this to determine which method template should be used to execute the Method item's code. The content generator will not work if this comment is not the first line in the file.
Once you've created and saved the new content generator method, open up your DocumentType for editing. Select the Xml Schema Element tab and replace the tp_ItemInfoContentGenerator with your new method, Custom_ItemInfo_ContentGenerator.
Save the DocumentType and be sure to close any open Tech Docs before trying to add an ItemInfo element with the new content generator. All you need to do is insert/add an ItemInfo element and select a Part from the search dialog that appears.
2. Display Tech Doc Metadata
Another application of content generators and custom elements is to display metadata from a technical document within the tech doc itself. In this example we look at a quick and simple way to automate a common requirement - including the document's number, revision, and last modified date in the document content.
The first step is to create a custom schema element that will be the container for the metadata and a trigger for our content generator method. Add the following Doc-Data element to your DocumentType schema.
If your schema has a root element or you want to add the Doc-Data element as a child of another element, be sure to reference Doc-Data as a child of that element in your schema. In the snippet below, I have added Doc-Data as a child of Standard-Doc.
Next, create a new C# server method and paste in the following code. This code retrieves the current tech doc's id from the executionContext object - available as part of the CSharp:Aras.TDF.ContentGenerator(Strict) method template - and retrieves the tp_Block item from the database. Once we have the tp_Block item, we can get the metadata properties and add them to the targetElement in child text elements.
Once the schema changes and content generator method are saved, we need to add a new Xml Schema Element so Aras knows to execute our content generator method when a new Doc-Data element is initialized. On your DocmentType, select the Xml Schema Element tab, click the "Add New" button, and fill the new row as follows:
- Name : Doc-Data
- Content Generator : DocData_ContentGenerator
- Dynamic Content : checked
Note that unlike in the first example, here we have checked off the Dynamic Content property. This means that the content generator will execute every time the document is rendered (in the editor or when published). We want to select this option so the revision and date properties always display the most current values, not the values the document had when the Doc-Data element was first added.
3. Define Default Behavior
Depending on a DocumentType's schema, elements can behave differently when they are added to a document tree. For example, when adding a Section to a document using the "Standard" schema, the editor will automatically add a Title child element. That's because the Section element definition in the Standard schema specifies that it has exactly one Title child element (minOccurs="1" maxOccurs="1").
Elements without required children are not added to the tree with child elements. Generally speaking, this is a good thing because you might not know what child elements are needed for a particular instance. However there may be use cases where you know what the child element will likely be, though you aren't certain enough to make the child required in the schema.
One such use case is when a user adds a new Entry (table cell) or List-Item. Since both of these elements can contain a number of different kinds of child elements, we can't make a child required to auto-populate new Entries or List-Items. Suppose a company's users of the Standard DocumentType populate Entry and List-Item elements with Text elements 95% of the time though. We can create a content generator that auto-populates each Entry and List-Item with a Text element, saving users the trouble of manually adding a child 95% of the time and costing users no additional time when they need to switch child elements the other 5% of the time.
We'll use the following content generator method code for both Entry and List-Item, since it just adds a text element to the target. Save the code to a new C# server method called AddTextChild_ContentGenerator.
Add two new rows to the Xml Schema Element tab on your DocumentType - one for Entry and one for List-Item. Set AddTextChild_ContentGenerator as the content generator for both and save the DocumentType.
You can now add Tables and Lists to your document without adding text elements to each Entry and List-Item. Additionally, you can use the TAB key to navigate through available text fields.
LOOKING FOR MORE ARAS INSPIRATION?
Subscribe to our blog and follow @ArasLabs on Twitter for more helpful content! You can also find our latest open-source projects and sample code on the Aras Labs GitHub page.