11.6 Advanced Editing of a Document Style
In addition to selecting and deselecting the content of a document style, you can also change the layout and usability of your document style. You do this by editing the attributes that are associated with certain sections. You can also create additional sections for your documents as you see fit.
11.6.1 What’s In the Advanced Editing Mode
The Advanced Editing icon 
lets you toggle between simple editing and advanced editing modes. By using the advanced editing mode, you can define information and a structure that is different from the default template already attached to a predefined style. In this example, the Title Page template is shown in its XSL format, which you must maintain.
Figure 11-2 Viewing a Predefined Template
Table 11-2 Style Editor Legend
Advanced editing mode allows you to add the following:
You can have multiple sections in a document, but only one template per section. The template defines the section’s layout; however, you can use the default template for newly created sections. You can also have multiple attributes defining how the section looks, as well as multiple controls. You use parameters (such as names and values) to specify options for a Control type. A Parameter is a general name for a child item of a Control. The name of the Control denotes the type of control and what you can perform by using that type.
Sections
Sections are blocks of the documentation composed of attributes, parameters, templates, and controls through XSL programming. Section content includes a Title, Body, and children or subordinate information. The following example shows the Section Properties page of the Identity Manager System as seen through the simple edit mode.
Figure 11-3 Section Properties Page
The Identity Manager System section contains a section title (this can be changed), along with a number of tabs (attributes): , , , , and . Each of these tabs contain fields that are editable; for instance, you can give the section title a different name. When you click the icon, you see that the Identity Manager System section contains one template that includes several attributes, controls, and parameters underneath the heading.
Figure 11-4 Advanced Editing Mode
Viewing or Editing Properties of a Section
If you click a section within the Style Editor and look in the Properties view (by default the lower left corner of Designer), you see the values associated with the selection. (If you do not see the Properties view by default, right-click a section and select .)
Figure 11-5 The Properties View of the Appendix B: Schema
These values are edited in the Properties view. The Values for the section heading are listed in the following table:
Table 11-3 Values of a Section
NOTE:Values change, depending on what you select under the Style Editor view. For example, an attribute shows different properties than a section or a template.
Templates
A template is the XML source that defines the overall layout of a generated page. For instance, the Title Page contains a template, as well as a number of headings. The following figure illustrates the parts of the Executive Summary template. For more information about templates, see A Walk-through Tutorial.
Figure 11-6 Parts of the Executive Summary Template
Attributes
Attributes are the child elements of a section. For example, clicking the Advanced Editor mode while selecting the section title Identity Manager System reveals the following attributes in red (global), green (local), and grey (comment):
Figure 11-7 Attributes
Controls and Parameters
You can add parameters to control the appearance of a style. For example, in the Advanced Editing mode, the structure of the Short (abbreviated) Solution Name entry is a global attribute that contains a control and a label, and the control type known as textbox allows anyone to type a name that appears in the generated document. Use the Properties view to edit controls.
Designer’s supported parameters or values for controls include the following:
Table 11-4 Supported Parameters
11.6.2 A Walk-through Tutorial
Now that you better understand what components are necessary in order to add advanced functionality to your template, use this section to create a new section, add an attribute, and view the source.
Creating a New Section in a Style
To insert an additional section into the Style Editor:
-
Create or open an existing .docgen file in the Style Editor.
-
Click the icon.
The tree view of the document outline expands to include additional objects, (such as attributes, template, and parameters).
-
Right-click the parent section where you want to add your new section, then select . Specify a new section name; for this example, call it “My Section.”
-
(Optional) Reorder the section by dragging the section object to a different location in the navigation tree. You can also copy and paste within this style or other styles.
-
Click the icon, then continue with Adding an Attribute to a Style.
Adding an Attribute to a Style
-
Right-click a section under the Style Editor view. Select .
-
Specify the attribute name in the Attribute Name window. For example, MyAttribute with no spaces. Click .
-
Specify a value under the Value property in the Properties view. For example, .
The Properties view shows the following values for attributes (attributes are defined through controls and parameters):
-
Global: passed down to subsections.
-
Group: used to group attributes together. These appear as part of a tab in Style Editor’s simple mode.
-
Name: The attribute’s name.
-
NLS ID: The attribute’s NLS identification.
-
Value: The attribute’s value.
You can also show your attribute with another control type. The following example first creates a control, then changes the control type from check box (the default) to something else, such as a text area.
-
Right-click and select .
-
With your cursor on the control you just created, change the control type value to in the Properties view.
-
Click your section to see the changes take place.
Enabling Documents to Recognize Your Additions
After you have added attributes, your generated document doesn’t include information from these attributes until you do one of the following:
-
Make sure your section is a leaf section (does not contain child sections).
-
Create a template that uses the attribute explicitly. This is usually the preferred method because you can display the attribute values exactly the way you want.
Method 1: Set the Section Source to “Style”
If you create a section without a template (and the template is a leaf section containing no section children), the default template generates the attribute values with the document. You do not need to do anything. You can generate a document for just that section by right-clicking the section head and selecting . Or you can click the icon at the top to generate the whole document.
NOTE:Text boxes, text areas, and tables are the only attributes that are generated through the default template (check boxes, selects, and comments are not generated).
Method 2: Add a Template for a Custom Layout
Complete the following tasks:
Creating a Template
-
Right-click your newly created section.
-
Select .
The template has some default content that consists mostly of comments, which helps you get started on your first template. This is shown in the next task; for now, replace the comments in this template with the following XSL commands:
<xsl:param name="MyAttribute"/>
<xsl:template name="Section.Body">
MyAttribute:
<xsl:call-template name="Format.OutputTextArea">
<xsl:with-param name="value" select="$MyAttribute"/>
</xsl:call-template>
</xsl:template>
There is a Format.OutputTextArea call in the XSL that is a helper function included with the Document Generator Core Support Templates. Because HTML code is allowed in text areas, this ensures that it’s interpreted and escaped properly. If you want to see the core XSL library calls for documentation generation, see Document Generator Core Support Templates.
Your template should look like this:
Figure 11-8 Example Template
Generating a document for this section should give you something like this:
Figure 11-9 Sample Section
Creating Another Section and Template
-
Right-click your newly created section and select . In the Section Name window, name the new section Table of Contents and click .
-
Right-click this new section and select . Carefully read through the comments in this template. These details are important.
When you create a custom section, you are inserting some information into the document. As the comments mention, developers usually override one of the following template functions:
-
Section Body (most common)
-
Section Content
-
Section Title
The following image illustrates which section is being defined. As a developer of the style, you write this template to overwrite the area that is of interest.
For this example, you should overwrite the Section.Body because you don’t want to change the default behavior of the Title, nor do you want to change the way other sections are related to this one. (You can use the hierarchical view to control this with the default template if necessary).
-
-
To overwrite the Section Body, simply uncomment the sample function that is shown in the default template. This is shown below:
If you render your document at this point, you get no content in your Table of Contents (other than the surrounding text). This is because this template assumes that the style source has been specified for this section. To specify the source:
-
Click the Table of Contents section.
-
From the Properties view, set the source to .
-
Right-click and select .
Viewing the Source
When your generate your document, you’ll notice there is an option. Click the box next to this option to turn it on. You’ll see .xml source files appear where you are generating the document. These source files are the XML data that is used in your template when you set the source (for example, to “style”). Designer 1.1 and above include the following sources:
Table 11-5 Sources
11.6.3 Selecting a Language for Generated Documents
You can also select the language you want to print the document in.
-
Click . Under the heading, select the language you want to use for document generation.
Current languages include:
-
Chinese Simplified
-
Chinese Traditional
-
Dutch
-
English (default)
-
French
-
German
-
Italian
-
Japanese
-
Portuguese Brazil
-
Spanish
-
-
After you select a language, click .
-
Click to close the Preference page.
11.6.4 Double-Byte Font Support
Designer now has double-byte font support for the Document Generation feature. If you select a language that uses double-byte characters, such as Chinese Simplified, Chinese Traditional, and Japanese, as a starting point Designer automatically installs the font Proportional Mincho. A good font that covers both proportional spacing and double-byte support is Arial Unicode MS.
For English and other languages, the default font is Arial.
To add a font for your specific language:
-
Click then expand and select . Under , select the font you want to use.
To change the font on a Windows workstation, you must first copy the font file from the C:\Windows\Fonts directory to another directory. You can then use the button to select the font.
To change the font on a Linux workstation, browse to the usr/share/fonts/truetype directory, or to another directory containing the fonts you want.
-
Click the button to bring up the Open window, change to the directory where you placed the font, then click .
You can also type the directory and font file name into field, or use the drop-down menu to select a font that you have previously selected.
-
Click , then click .
Using the above steps globally changes the font in the generated document, and also adds double-byte font support for your selections.