Accessing Scripts from Arbortext Styler
The ability to access scripts from Arbortext Styler is an advanced feature that permits you to use ACL and Javascript as part of your stylesheet processing. For example, you might want to examine application configuration information to make a style decision, or insert a string from a configuration file in generated text. Script access is available wherever Arbortext Styler allows you to use XPath, via the supplied XPath extension functions _js:eval() and _acl:eval(). Scripting must be done with care. Please refer to Guidelines for Accessing Scripts below.
The examples below show how to utilize scripts to perform some common tasks in Arbortext Styler.
Example: Embedding the Output of a Script in Generated Text via XPath
You can embed any string that can be generated from a JavaScript or ACL function. This example uses XPath to embed the composition year in a generated text section in output.
1. Select an element context and choose the Generated text category.
2. Choose the Edit button associated with the Before-text or After-text field, depending on the intended placement of your generated text.
3. In the Generated Text Editor, choose > .
4. Enter the expression _js:eval("new Date().getFullYear()")
5. Save the generated text setting and exit the editor.
6. When you preview or publish your document, you will see that the selected element displays the current year in its generated text.
|
|
The PTC Arbortext print engines and HTML processing use different JavaScript processors. This may result in differences in output. Please ensure that you test your script in all outputs, and with the print engine you will be using to ensure you are happy with the results.
|
Example: Using XPath to Create Conditions Based on the Result of a Script
You can create a condition that is matched based on the result of an ACL or a JavaScript script.
Using this example, you will base the location of figure headers on the value of the application variable com.arbortext.sma.FigureHeaderLocation. This variable can have values of above and below, and can be accessed via the ACL function figure_header_loc(). The function figure_header_loc() could be code like this:
function figure_header_loc()
{
local figureHeaderLoc = \
get_user_property("com.arbortext.sma.FigureHeaderLocation", \
get_custom_property("com.arbortext.sma.FigureHeaderLocation"))
return tolower(figureHeaderLoc)
}
This example assumes the use of a fig element in your document type.
1. In your Arbortext Styler stylesheet, add a condition for the fig everywhere context.
2. Add an XPath test for the condition, and enter the following test:
_acl:eval("figure_header_loc()") = "above"
3. Assign the required properties to that condition to place the figure headers in their correct location.
4. Repeat the previous steps to create a second condition for the fig everywhere context, this time based on a test for the value of below:
_acl:eval("figure_header_loc()") = "below"
Set the properties to place the headers in the correct position.
Guidelines for Accessing Scripts
Please note the following when using scripts in Arbortext Styler:
• Functions that access or manipulate the current document, for example oid_caret() or current_doc(), or that modify any document, should not be used.
• XPath expressions are evaluated frequently. Calling functions that require significant processing time can have a significant impact on screen display response and composition time, and is not recommended
• Script functions used within XPath expressions should be loaded and available before the document that uses them is opened.
One way to do this is to place the scripts in a file alongside the doctype, with an appropriate extension. For example, ACL scripts used with mydoctype.dtd could be placed beside it in mydoctype.acl.
|
|
When the document will be published through a PE server, only scripts contained in the custom/init directory when the server is started will be loaded. Contact your PE server administrator if you need to install scripts on a PE server.
|
• When using XPath to call script functions that return boolean (true/false) values, note that the boolean values are returned from the scripts as strings — 1 (true) or 0 (false). Consequently, XPath expressions testing these functions should be written in the form shown below:
_acl:eval('myfunc()' = '0')
Otherwise, XPath will interpret the returned 0 as true, because XPath interprets any non-empty string as true.
Using Arbortext Editor to Test an XPath Expression
It might take multiple attempts to define script use in an XPath expression to obtain the results you desire. It is much quicker to develop and test expressions in Arbortext Editor than in Arbortext Styler - the steps below explain how:
1. Open your document in Arbortext Editor.
2. Declare the _js or _acl prefix as an XML prefix in the current document, using the following steps:
a. Select the document element of the current document.
b. From the command line, modify the current document by adding the namespace declaration to the document tag. Use one of the following:
mt
xmlns:_js="java:com.arbortext.epic.internal.js.JavaScript"
or
mt xmlns:_acl="java:com.arbortext.epic.Acl"
3. Place the cursor inside the element whose context will contain the required condition. In the Arbortext Editor command line, enter the command eval oid_xpath_boolean(oid_caret(), "self::node()[...]") - replacing ... with the expression you wish to use for the XPath test.
oid_xpath_boolean is useful for trying out scripts for conditions
Use oid_xpath_string if you want to test scripts for use in XPath string in generated text.
4. Look at the resulting value in the Eval Output window - if the value is 1, the test is true. If a value of 0 returned, the test is false.
