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

16.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 16-2 Viewing a Predefined Template

Table 16-2 Style Editor Legend

Icon

Name

Description

Green Page

A green page means it’s a titled section. The title appears when you generate the document.

Grey Page

A grey page means it’s not a titled selection. These pages are also in parentheses; for example, (Title Page).

White Page

A white page means this section is disabled and will not be included when you generate the document.

Template

A yellow template page gives specific format and styles that are included when you generate a document.

Global Attribute

A global (red) attribute means it is passed down to every section below it (all children sections).

Local Attribute

A local (green) attribute means it is only used by the section in which it appears.

Grey Attribute

A grey attribute is used for comments.

Control Icon

A Control type defines the functionality that you can give to Attributes. Each Control type has a different functionality.

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 16-3 Section Properties Page

The Identity Manager System section contains a Section Title (this can be changed), along with a number of tabs (attributes): Document Properties, Client Properties, Header, Font Settings, and Other. Each of these tabs contain fields that are editable; for instance, you can give the Section Title a different name. When you click the Advanced Editing icon, you see that the Identity Manager System section contains one template but several attributes, controls, and parameters underneath the heading.

Figure 16-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 Show Properties View.)

Figure 16-5 The Properties View of the Appendix B: Schema

These values are edited in the Properties view, and for the Section heading the values are listed in the following table:

Table 16-3 Values of a Section

Property Name

Description

Enabled

(True/False) Indicates whether this section is enabled. You can change this setting using the section Style Editor, which is the editor shown to the right of the hierarchical view.

ID

Used for reference. Most the time, ID is left empty. However, you can specify an ID for convenience in finding this section during the transformation process.

NLS ID

Used for reference. Most the time, NLS ID is left empty.

Numbered

(True/False) Indicates whether this section should be included in the numbering and placed in the Table of Contents.

Source

Data source used to transform the template. For example, designer, style, and none.

Title

The value to be displayed as the title. You can change this setting using the section Style editor, which is the editor shown to the right of the hierarchical view.

Titled

(True/False) Indicates whether the title value should be shown in the generated document. Otherwise, it is used only in the GUI for context.

Version

The version of the 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 other headings. The following figure illustrates the parts of the Executive Summary template. For more information about templates, see A Walk-through Tutorial.

Figure 16-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 16-7 Attributes

Controls and Parameters

You can add parameters to control how things appear. 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. For example, 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 16-4 Supported Parameters

Control

Parameter or Value

Description

Table

columns=“3” header=“date” width=“30” label=“show this” addrows removerows

Number of columns to show in the Control. Column header text. Column width for each column. Explains what you see in this control. Displays a button to perform this function. Displays a button to perform this function.

File

extensions=“.jpg;*.gif” label=“show this”

Supported extensions separated by a semicolon (*. jpg;*. jpeg;*. gif). (One file only.) The label explains what to perform with this control.

Select (Identity Manager System/font Settings)

option=“font 1” option=“font 2” label=“show this”

Parameters allow font point selection, such as option = “20pt” and option = “24pt” The label indicates what you can do with this control.

Checkbox

label=“show this”

The label explains what you can perform with this control. It includes a check box.

Textbox or Textarea

label=“show this”

The name gives a title to the text box or text area control. You edit these controls through the Properties view.

Comment

label=“show this”

Allows you to add comments to help guide users. You edit this control through the Properties view.

16.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:

  1. Create or open an existing .docgen file in the Style Editor.

  2. Click the Enable Advanced Editing icon.

    The tree view of the document outline expands to include additional objects, (such as attributes, template, and parameters).

  3. Right-click the parent section where you want to add your new section, then select New Child > Section. Specify a new section name; for this example, call it “My Section.”

  4. (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.

  5. Click the Save icon, then continue with the next section.

Adding an Attribute to a Style

  1. Right-click a section under the Style Editor view. Select New Child > Attribute.

  2. Specify the attribute name in the Attribute Name window. For example, MyAttribute with no spaces. Click OK.

  3. Specify a value under the Value property in the Properties view. For example, This is my attribute value.

    Value Property View

The Properties view shows the following values of 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.

  1. Right-click MyAttribute and select New Child > Control.

  2. With your cursor on the control you just created, change the control type value to Text Area in the Properties view.

  3. Click your section to see the changes take place.

    Changes applied

Getting 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 by describing the layout using the template.

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 Generate Documentation for This Section. Or you can click the Generate Document 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

  1. Right-click your newly created section.

  2. Select New Child > Template.

    Template

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 DocGen 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 16-8 Example Template

Generating a document for this section should give you something like this:

Figure 16-9 Sample Section

Creating Another Section and Template

  1. Right-click your newly created section and select New Child > Section. In the Section Name window, name the new section Table of Contents and click OK.

  2. Right-click this new section and select New Child > Template. 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.

    Template extension points

    For this example, we are going to overwrite the Section.Body because we don’t want to change the default behavior of the Title, nor do we 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 anyway).

  3. To overwrite the Section Body, we simply uncomment the sample function that is shown in the default template. This is shown below:

    Overwriting the template

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:

  1. Click the Table of Contents section.

  2. From the Properties view, set the source to style.

  3. Right-click MySection and select Generate Documentation for This Section.

    Generate Doc for This Sample

Viewing the Source

When your generate your document, you’ll notice there is an option to Output XML Source Files. 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 16-5 Sources

Source Key

Description

none

An empty source, used when no source is specified or when “none” is specified.

style

The XML source of the style, used to build things like the Table of Contents.

designer

A source that has been defined by an extension point for the Designer model. This contains all information about the configuration of your Designer project.

16.6.3 Selecting a Language for Generated Documents

You can also select the language you want to print the document in.

  1. Click Window > Preference > Designer for IDM > Document Generation. Under the Document Language heading, select the language you want to use for document generation.

    Choosing the language to print documents

    Present languages include:

    • Chinese simplified

    • Chinese traditional

    • Dutch

    • English (default)

    • French

    • German

    • Italian

    • Japanese

    • Portuguese Brazil

    • Spanish

  2. Once you select a language, click Apply.

  3. Click OK to close the Preference page.

16.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 fonts, such as Chinese Simplified, Chinese Traditional, and Japanese, Designer automatically installs the font Proportional Mincho.

Figure 16-10 Selecting a Double-Byte Font Language

For English and other languages, the default font is Arial.

To add a font for your specific language:

  1. Click Window > Preference > Designer for IDM > Document Generation. Under Font Settings, select the font you want to use.

    Selecting a Font

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

  2. Click the Browse button to bring up the Open window, then change to the directory where you placed the font, then click Open.

    You can also type the directory and font file name into Font Settings field, or use the pull-down menu to select a font that you have previously selected.

  3. Click Apply, then click OK.

Using the above steps will change the font globally in the generated document, as well as add double-byte font support for such selections.

16.6.5 Saving a Style File in the Styles Template Library

Designer provides one or more default styles that you can use to generate documentation for your project. The Default_Style.docgen file is stored in the Novell\designer\eclipse\plugins\ com.novell.designer.idm.docgen.editor_2.0\content\styles folder and is displayed as an option when you choose a new style.

You can add your own style files to the ...\content\styles folder so that you can easily find them when choosing a basis for a new style.

  1. Locate the .docgen file you want to add.

    By default, the file is in a directory inside the project where you saved it. For example, the Blanston2.docgen file was created in the workspace\Blanston2\documentation directory.

  2. Copy the .docgen file into the Styles Library ( Novell\designer\eclipse\plugins\ com.novell.designer.idm.docgen.editor_2.0\content\styles). The . docgen file appears in the styles folder the next time you open Designer and generate a document.

    Placing a .docgen File in the Styles Library