Defining a Footnote Control Stream
The footnote control stream defines how PTC Arbortext Layout Developer takes the footnote references and outputs them on the page. The control streams are applied to the frame containing the content which generates the footnote references. Each frame can have up to five different control streams applied, one for each group of footnotes that can be processed.
There are two ways to define footnote control streams:
1. Using the > > menu option in the PTC Arbortext Layout Developer— Desktop product
2. Using the Formatting Object Model (FOM) and JavaScript
This method is preferred if you want to interact with a control stream or build a new one.
The FOM provides the fFootnote object to represent the control stream. As it is a control stream, the object inherits the fControl object. It should be used with the fContent.getFootnote() and fContent.createFootnote() methods, both of which return an fFootnote object.
This example code creates the new footnote control stream myFootnoteControl:
var fNote;
fNote = template.content.getFootnote("myFootnoteControl");
if (!fNote) fNote = template.content.createFootnote("myFootnoteControl");
As with most PTC Arbortext Layout Developer tag creation code, this example tests for the presence of the tag before creating a new one.
The fFootnote object includes multiple properties. The fFootnote.verticalPlacement property is the only one that is required. The other properties fine tune the display of the footnotes:
• fFootnote.verticalPlacement — defines where PTC Arbortext Layout Developer outputs the footnote frames
The options are listed on the fFootnote.PlacementVertical constant:
◦ fFootnote.VERTICAL_BOTTOMUP — builds the standard footnote type where the footnotes are stacked upwards from the bottom of the page
◦ fFootnote.VERTICAL_LOWESTLINE — stacks the footnotes below the lowest line on the page
Use this option when the text on a page is short.
◦ fFootnote.VERTICAL_TOPDOWN — stacks the footnotes downwards from the top of the page
◦ fFootnote.VERTICAL_SIDENOTE — places the footnote as a sidenote
This option requires nominated columns in which to output the footnotes. Refer to fFootnote.HORIZONTAL_NOMINATED.
◦ fFootnote.VERTICAL_BELOWREFERENCE —outputs the footnote in a frame below the line which holds the footnote reference
◦ fFootnote.VERTICAL_BELOWLOWEST — places the footnote below the lowest footnote reference on the page
This option works in a similar way to the lowest line option.
• fFootnote.horizontalPlacement — specifies how the footnotes work with any columns in the frame to which the footnote control stream is applied
The valid options for this property are listed on the fFootnote.PlacementHorizontal constant:
◦ fFootnote.HORIZONTAL_ACROSSALL — build the footnote frame across all columns
◦ fFootnote.HORIZONTAL_SAMECOL — build the footnote frame in the same column as the reference
This would be the most typical usage.
◦ fFootnote.HORIZONTAL_NOMINATED — use the columns nominated by the fFootnote.nominatedColumns property
fFootnote.nominatedColumns is a list of the columns in which the references appear and the target columns in which to output the footnote.
Set this property when using side notes. Refer to fFootnote.VERTICAL_SIDENOTE.
• fFootnote.process — instructs PTC Arbortext Layout Developer how to process the footnote references when they are encountered
The options for the property are listed in the fFootnote.ProcessType constant:
◦ fFootnote.PROCESS_WITHREF — process the footnote as they are encountered
This is the default and most typical usage.
◦ fFootnote.PROCESS_AFTERPAGE —process footnotes after a page break
◦ fFootnote.PROCESS_AFTERCOLUMN — process footnotes after a column break
◦ fFootnote.PROCESS_MANUAL — process footnotes when a manual command to insert footnotes is encountered
The manual command is defined with the fFootnoteReference.TYPE_MANUAL footnote reference type.
• Properties that set the geometry of the footnote area:
◦ fFootnote.spaceAbove, fFootnote.spaceBetween, fFootnote.spaceBelow — specify the amount of space to apply above, between, and below the frames created to hold the footnotes
◦ fFootnote.maxHeight — sets the maximum allowed height of the area dedicated to footnotes on a page
PTC Arbortext Layout Developer applies rules if a footnote frame displaces the footnote reference. It is possible to create a footnote frame that fills the whole page. If you want the footnote to take up a proportion of the main content area, use this setting to restrict the footnote height
◦ fFootnote.minSplitHeight — sets the minimum height of the footnote area if it is permitted to split
◦ fFootnote.maxWidth — sets the maximum width of the area of the footnote text
◦ fFootnote.numColumns — specifies the number of columns to create for the footnote text area
If the number of columns is set to 0, PTC Arbortext Layout Developer calculates the column number automatically based on the frame to which the footnote control stream is applied.
◦ fFootnote.columnGutter — specifies the width of the column gutter (the space between columns) when the footnote area has more than one column
As with the number of columns, a value of 0 allows PTC Arbortext Layout Developer to automatically calculate the width.
• Properties that position a frame for sidenotes alongside the reference:
◦ fFootnote.alignSidenote — specifies the part of the sidenote or sidenote frame that should align with the reference alignment position
The options are listed on the fFootnote.SideAlignFrame constant:
▪ fFootnote.SIDENOTE_FIRST — the baseline of the first line of text in the sidenote
▪ fFootnote.SIDENOTE_FRAMETOP — the top of the sidenote frame
▪ fFootnote.SIDENOTE_FRAMEBOTTOM — the bottom of the sidenote frame
▪ fFootnote.SIDENOTE_FRAMECENTER — the middle of the sidenote frame
◦ fFootnote.alignWithReference — specifies the part of the reference that should align with the sidenote alignment position
The options are listed on the fFootnote.SideAlignRef constant:
▪ fFootnote.SIDENOTE_BASELINE — the baseline of the reference
▪ fFootnote.SIDENOTE_REFTOP — the top of the reference
▪ fFootnote.SIDENOTE_REFBOTTOM — the bottom of the reference
• Properties that control the frames created for the footnotes
When PTC Arbortext Layout Developer creates a footnote, it can either create separate frames for each footnote or combine all of the page’s (or column’s) footnotes into a single frame.
◦ fFootnote.combineFootnotes — specifies whether footnotes should be combined in a single frame
There are two ways of combining footnotes, either by copying the content of all footnotes into a new automatically generated content stream, or by creating a new stream with references to the original footnote streams.
The allowed values are listed on the fFootnote.CombineModes constant:
▪ fFootnote.COMBINE_NONE — do not combine footnotes
In this case, a separate frame is created for each footnote.
▪ fFootnote.COMBINE_COPY — use a copy of the original footnote content in the new content stream
▪ fFootnote.COMBINE_REFERENCE — create a new content stream containing references to the original footnote content items
◦ fFootnote.wrapperElement — specifies the name of a wrapper element to be created for the copied content, if the footnotes are XML
• Properties that specify the handling of any displaced, oversized, or overlapping frames generated during footnote/sidenote creation:
◦ fFootnote.displacedReferences — specifies how to resolve displaced footnotes
The allowed values are listed on the fFootnote.ResolveDisplaced constant:
▪ fFootnote.RESOLVE_REMOVETEXT — remove text from the current page and leave the space
Two other properties can be used with this method. The fFootnote.emptyPosition property controls whether the extra space is added on top of the footnotes. The fFootnote.reduceSpace property sets the amount of space to add in increments to ensure the displacement is resolved.
▪ fFootnote.RESOLVE_REDUCEHEIGHT — reduce the height of the footnote area
This option may cause a split footnote.
Two other properties are required when using this method. The fFootnote.stepSpace property specifies the size of increments by which to reduce the height. fFootnote.limitSpace sets the maximum amount of space which can be removed from the height of the footnote.
▪ fFootnote.RESOLVE_REDUCESPACE — reduce the amount of space above the first footnote (set using fFootnote.spaceAbove)
As with the REDUCEHEIGHT option, the fFootnote.stepSpace and fFootnote.limitSpace properties should be used.
◦ Properties that specify how to handle sidenotes when there is insufficient space
Sidenotes can run out of space when they reach the bottom of a page and when they are obeying alignment properties.
The allowed options are listed on the fFootnote.HandleSidenotes constant:
▪ fFootnote.SIDENOTE_SPLIT — split the sidenote across pages
▪ fFootnote.SIDENOTE_MOVE — move the oversized sidenote upwards so it fits on the page
▪ fFootnote.SIDENOTE_PUSH — push the oversized sidenote upwards so it fits on the page