Index Control Streams
Index control streams configure the collation and sorting of indexes. They also define the markup that is generated around the index entries. Several objects in the Formatting Object Model (FOM) provide this configuration. These objects combine to provide either a simple or an advanced index control stream. The main differences between the two types of index are the level of control PTC Arbortext Layout Developer provides over grouping and the nature of the markup generated for each entry. It is recommended that advanced indexes are used when formatting XML content.
Index control streams appear as .ix tags in an PTC Arbortext Layout Developer template. Since they are control streams, they inherit all the properties and methods of fControl. A formatting process that creates an index must be advised which index control stream to use. The fIndex object provides this information with a group of index configurations represented by index items. The fIndexSimpleItem and fIndexAdvancedItem objects represent simple and advanced index items, respectively. Both of these objects inherit from the fIndexItem object.
The fIndex object holds a list of index items in its fIndex.indexes array. Index items are managed through the fIndex.addItem(), fIndex.removeItem(), and fIndex.clearItems() methods.
The fIndex object also configures the use of index data generated from other documents or formatting passes using an index control stream. The fIndexItem object has an fIndexItem.saveFilename property which instructs PTC Arbortext Layout Developer to save the raw index data to an external file. The data can then be included in the current index, using the fIndex.includePaths property to point to the external files created. This behavior allows PTC Arbortext Layout Developer to create multiple volume indexes.
The simple and advanced index items inherit from a base fIndexItem object. The properties for this object are:
• fIndexItem.output — provides the name of the content stream to which the generated index is written
The index is not output if this property is null.
• fIndexItem.groups — specifies the groups that should be used to populate the index
The allowed groups are listed on the fIndexItem.GroupMask constant.
The indexes feature can pull indexes together from multiple different groups. Using a value of fIndexItem.GROUP_1 + fIndexItem.GROUP_4 pulls entries together from groups 1 and 4.
• fIndexItem.sortIndex (boolean) — specifies whether PTC Arbortext Layout Developer should sort the index
If set to true, the index is sorted according to the value of the fIndexItem.sortMethod property.
• fIndexItem.sortMethod — specifies the sort method to use when sorting the index entries
PTC Arbortext Layout Developer can use either its own sorting method or a method based on locale.
The allowed values are listed on the fIndexItem.SortMethods constant.
• fIndexItem.sortingLocale — defines the locale that should be used, if the index sorting method includes the locale option
The locale is specified using a two character locale code.
• fIndexItem.localeCaseOrder — determines whether uppercase characters should be sorted differently from lowercase characters.
The allowed values for this property are listed on the fIndexItem.LocaleSortOrder constant. It includes options for ignoring the case when sorting, sorting uppercase characters ahead of lowercase characters, and vice versa.
• fIndexItem.sortAsNumbers (boolean) — determines numbers should be treated when sorting an index
If false, entries are sorted without consideration for contained numbers, for example entry10 is sorted before entry2.
If true, entries containing numbers are sorted using the decimal representation of the number, for example entry2 is sorted before entry10.
• fIndexItem.ignorePunctuation (boolean) — specifies whether punctuation should be ignored when sorting an index
• fIndexItem.ignoreRefs (boolean) — specifies whether entity references should be ignored when sorting an index
• fIndexItem.ignoreMarkup (boolean) — specifies whether markup in the index entry should be ignored when sorting an index
• fIndexItem.saveSorted (boolean) — specifies whether index data should be sorted when saving it out to an external file
• fIndexItem.saveFilename — provides the name of an external file
Set this property when raw index information is being saved out to an external file.
• fIndexItem.generationMode — specifies the mode of generating an index
By default, indexes are generated once the formatting process has ended. Alternatively, PTC Arbortext Layout Developer can generate an index on demand or when the output stream is referenced.
This behavior must be set in advance using this property. The allowed values are listed on the fIndexItem.IndexGenerationMode constant.
Simple indexes are used to generate basic index lists with all entries in markup at the same hierarchical level.
The advanced index type provides more flexibility:
• more control over markup generated around the components of an index entry
• the ability to nest the different levels of index entries,
• a feature which allows control over how characters are grouped in the output index
fIndexAdvancedItem inherits from fIndexItem. It also has its own properties:
• Markup properties, which define the element names to use to wrap the different parts of the index and index entries:
◦ fIndexAdvancedItem.rootNode — specifies the name of the element which wraps all the index content
◦ fIndexAdvancedItem.alphaElement, fIndexAdvancedItem.preAlphaElement, fIndex.postAlphaElement — specify the name of the element which wraps groups of index entries
With advanced indexes it is possible to create groups of entries based on the initial character of the entry:
▪ alphabetical characters
▪ those which should be grouped before the alphabetical characters, for example numbers
▪ those which should be grouped after the alphabetical characters, for example such as symbols
◦ fIndexAdvancedItem.groupHeadingElement — specifies the name of the element for the index heading, if the index is configured to create one with the fAdvancedIndexItem.useGroupHeadings property
◦ fIndexAdvancedItem.levelElements (array) — specifies the name of the element for each of the index entry levels
Index entries can be nested up to five levels.
◦ fIndexAdvancedItem.entryHeadingElement — specifies the name of the element which wraps the index entry text
◦ fIndexAdvancedItem.entryLocationElement — specifies the name of the element which wraps the page number information in an index entry
◦ fIndexAdvancedItem.entryPageElement — specifies the name of the element which wraps the first page number in an index entry
◦ fIndexAdvancedItem.entryToPageElement — specifies the name of the element which wraps the second number in a page range in an index entry
This would be used to generate the range indicator, for example an en rule or the word to.
◦ fIndexAdvancedItem.entrySeeElement, fIndexAdvancedItem.entrySeeAlsoElement — specify the name of the elements which wrap see and see also components, if the index entry includes these components
Using these element names, it is possible to control the markup of the XML which gets created in an index. For example:
• XML structure properties
◦ fIndexAdvancedItem.nestLevels — determines whether the different levels of index entry are nested within each other
Setting this to false outputs all levels at the same hierarchical level, which can be difficult to format properly.
◦ fIndexAdvancedItem.xsltControl — points to an PTC Arbortext Layout Developer tag which holds an XSL transformation
If present, the transformation is applied to the index before it is generated/output.
◦ fIndexAdvancedItem.xsltParameters — points to an XSLT parameter control stream
If present, the control stream passes additional parameters to the transformation process identified with fIndexAdvancedItem.xsltControl.
• Properties to control grouping
Index grouping provides a method for configuring different language-based sorting and grouping rules. This is particularly pertinent for languages that use different alphabets or consider certain characters as equivalent. Grouping is controlled using a control stream. Many common grouping rules are provided, but you can create your own grouping control streams for custom grouping configuration.
◦ fIndexAdvancedItem.useGrouping (boolean) — activates grouping if sorting is also active (see fIndexItem.sortIndex)
◦ fIndexAdvancedItem.groupingControl — points to an index grouping control stream
The built-in control streams are listed on the fIndexAdvancedItem.GroupControlNames constant. This property can also point to a custom control stream provided by the template.
• Other properties
◦ fIndexAdvancedItem.useRawText — determines whether special characters in the XML output, such as & and <, should be encoded
◦ fIndexAdvancedItem.xmlScope — provides a location path for hierarchy in the source XML
Only index references found at this path are included in the index generation.
New advanced index items are created using the constructor of the fIndexAdvancedItem object, for example:
var myIndex = new fIndexAdvancedItem();
The item is then added to the index control stream as shown in this example:
var myIndexControl;
myIndexControl = template.content.getIndex("IndexControl");
if (!myIndexControl) template.content.createIndex("IndexControl");
myIndexControl.addItem(myIndex);