scanHeadings
A logic command that finds all the headings of an HTML document and stores data about the headings into a Collection.
By default, scanHeadings seeks out all the standard HTML heading elements from <h1> to <h6>. With the selectors attribute it is possible to customize this by providing a set of element or class names that the command will look for instead. With either the default or custom selectors, scanHeadings only picks out elements that have the id attribute defined.
The resulting Collection will contain Map values in the order of the headings' appearance; each of these Maps contains the following entries:
level - A Number value that is the level of the heading, as defined by the order of the provided selectors. With the default selectors,
<h1>is level 1, while<h6>is level 6.text - A String that is the text content of the heading element and its possible descendant elements.
href - A String that is the heading element's id preceded by a
#. This can be used with href to create a link to the heading.numbering - A Collection that contains the sequential number of headings of the heading's own level, as well as the levels above its level. For example, if this is the second level 3 heading under the fifth level 2 heading under the first level 1 heading, the Collection would contain the Numbers 1, 5 and 2 in this order.
Attributes
var | ||
|---|---|---|
Required | Value type | EL-evaluated |
Yes | String | No |
Defines the name of the variable that will hold the Collection of found heading data. See the command's main documentation about details of the Collection's contents. | ||
file | ||
|---|---|---|
Required | Value type | EL-evaluated |
Yes | File | Yes |
Defines the HTML file whose headings this command will seek. The resolved value is therefore expected to be a File whose type is HTML. | ||
selectors | ||
|---|---|---|
Required | Value type | EL-evaluated |
No | Collection | Yes |
Defines a set of element and/or class names that the command treats as headings. The resolved value is expected to be a Collection of String values, each String being either of these two CSS-like selectors:
The order in which the selector Strings are in the Collection defines the levels of the headings, with any headings matching the first selector being headings of level 1, those matching the second selector being headings of level 2, and so on. If undefined, a Collection containing the following selectors in this order is used: "h1", "h2", "h3", "h4", "h5", "h6" | ||
Examples
Use the selectors attribute to have scanHeadings adapt to different document structures. For example, if the elements that should be treated as headings are <div> elements with specific classes, give the command a Collection of appropriate class selectors. The following example finds all elements with a defined id whose class attribute values contain either "product-group-name" or "product-name", with owners of the first class being first level headings and those with latter class being second level headings:
<setCollection var="selectors"><addItem value=".product-group-name"><addItem value=".product-name"><scanHeadings var="headingData" file="${composedDoc}" selectors="${selectors}">The Collection produced by scanHeadings could then be used to create a table of contents or a navigation tool in a Screen. Here's the previous example's data being used in HTML:
<div class="product-links"><div dyn-repeat="headingData" dyn-repeat-var="heading" dyn-class="product-link-level-${heading.level}"><a dyn-content="heading.text" dyn-href="heading.href"></a></div></div> The numbering data for the headings is provided in a Collection containing all the components for the heading's number. The previous example could have numberings like "1.1." and "2.5." included as follows:
<div class="product-links"><div dyn-repeat="headingData" dyn-repeat-var="heading" dyn-class="product-link-level-${heading.level}"><span dyn-repeat="heading.numbering" dyn-repeat-var="levelNum" dyn-content="${levelNum}."></span> <a dyn-content="heading.text" dyn-href="heading.href"></a></div></div>