Custom Rule Find Scriptlets

Sample Find scriptlets are provided with the Astoria system.

Find scriptlets can respond with 0 or more elements. The results serve as the context for further processing to perform whatever changes are desired.

Sample Find scriptlets are included in starScriptlets.py. The script is located on the ACS server.

getElements(xpathStr)

Returns an element array of interesting elements or None if not found.

The XPath can be relative or absolute using the specified object or containing document. XPath support is limited to that allowed by the Astoria SDK.

For example, to find all topicref elements that are immediate children of the selected map, specify the following custom rule Find string: 
getElements("/map/topicref")

getFolderItems(includeStructuredDocuments = 1, includeFiles = 1, recurse = 1)

Returns an array of folder items which are the members or descendant members of the folder.
  • If includeStructuredDocuments is 1, XML documents are included in the results.
  • If includeFiles is 1, graphics and other unstructured files are included.
  • If recurse is 1, contents of nested folders are also included.
You can leave off trailing arguments whose defaults you like, so the following are all equivalent :
  • getFolderItems()
  • getFolderItems(1)
  • getFolderItems(1, 1)
  • getFolderItems(1, 1, 1)
Similarly, the following are equivalent:
  • getFolderItems(1, 0)
  • getFolderItems(1, 0, 1)

getMapTopics()

Returns an element array of root topic elements.

The array includes the root elements of topics referenced by the map as well as topics referenced by maps that are referenced by the map.

Note: This scriptlet is most likely used in a preprocess rule.

getMetadataElement()

Returns an element array containing the one <metadata> element within the prolog if one exists.

getParentElements(ancestorDepth)

Returns an element array of parent elements or None if not found. ancestorDepth is number of ancestor levels of interest; for example:
  • 1 = Parent
  • 2 = Grandparent
  • <other numbers> = <greater level of ancestor parent>
Note: If source object is the root element of an unreferenced document, None will be returned (since it has no parent element).

getProdinfoElements(prodNameStr)

Returns an element array containing the <prodinfo> elements within the prolog that match the specified prodNameStr.
  • If prodNameStr is not specified, all <prodinfo> elements are returned.
  • If a <prodinfo> element exists that has a <prodname> child element with a value matching prodNameStr, that <prodinfo> element will be returned.

getVRMlistElements(prodNameStr)

Returns an element array containing the <vrmlist> elements within the prolog that match the specified prodNameStr.
  • If prodNameStr is not specified, all <vrmlist> elements are returned.
  • If a <prodinfo> element exists that has a <prodname> child element with a value matching prodNameStr, that element's <vrmlist> child element will be returned.

isElement(elementNames)

Returns an element array of one element or None if not matched.

The elementNames parameter is either a single element name or a "|" separated list of element names.

If the context element (object) name matches a specified elementName, return a list with the context element as the one list member.

For example, to process only the subset of selected elements that are <topicref> or <topichead> elements, specify the following custom rule Find parameter: 
isElement("topicref|topichead")

rollForwardIf(approvalLabelStr, False or True)

Note: This scriptlet operates on snapshot labels, formerly called approval labels.

Rolls forward a previous version of objects with the specified snapshot label (approvalLabelStr) if the object has a revision date after the date of the snapshot label.

The scriptlet takes a snapshot label string as a parameter (such as rollForwardIf("Release_4.5",) and a second parameter (either False or True). If False specified, Global Substitution does a dry run and doesn't actually make any changes. It logs all of the changes it will make, but it doesn't actually roll forward any files. If the parameter is True, the files are actually rolled forward.

Because rollForwardIf is a custom scriptlet, the Check In and Version Note fields in the Global Substitution dialog are ignored. Document versions are rolled forward based on the True argument passed into the rollForwardIf scriptlet. The version note used for the roll forward is generated by the scriptlet.

Important: Astoria recommends doing a dry run first and inspecting the log to verify that the scriptlet is going to do what you want it to.

switchReferences

This scriptlet enables selected graphic files that are referenced in DITA documents to be replaced with same-named graphics of another type (that is, with a different file extension).
Important:
  • Replacement graphic files must reside in the same folder as the graphic files to be retired.
  • Replacement graphic files must have system id values.
The switchReferences scriptlet takes three arguments:
attribute name The attribute which provides the reference. For an image element, the attribute name is href.
findPattern The regular expression to match in the file name. An example might be .gif.
replaceString The value to be replaced to match the replacement graphic. An example might be .svg.
For example, to replace the .gif type graphics files with .svg type graphic files of the same name, specify the following custom rule Find parameter:
switchReference("href", ".gif", ".svg")

thisElement()

Returns a one-element array of the context element, or None if the context object is not an element.

Note: This method may be used to filter results from preprocess or custom rules that created objects other than elements.
Parent topic: Custom Substitution Rule