Implementing Object Location and Naming Rule Hooks
ACL hooks can be used to override the object names and locations that are generated by the bursting rules. The hooks are called after the bursting rules have generated a candidate name and location, and can use any ACL functions to adjust the values based on the content or context of the object. Hooks are always called, whether useroverride is set to on or off.
Because hooks are configured using burst configuration files, you can define default and document type-specific hooks. Only ACL hook functions are supported.
Refer to
Defining object location and naming rule hooks for information on setting up your burst configuration file for using hooks.
Implementing Hook Functions
Hooks are implemented as inline ACL code in the burst configuration file. The inline code may call ACL functions defined elsewhere, and may define functions itself. The following ACL functions retrieve information about context, report errors, and return the desired object name or location:
• burst_hook_error
• burst_hook_first_oid
• burst_hook_is_graphic
• burst_hook_last_oid
• burst_hook_sess
• burst_hook_value
• set_burst_hook_error
• set_burst_hook_value
These functions require the dms:: prefix when used. Variables in hooks should always be in a function and declared local. For example:
<namehook type="acl">
<![CDATA[
function hook_example::name_hook()
{
local oid = dms::burst_hook_first_oid();
local name = dms::burst_hook_value();
local tagname = oid_name(oid);
dms::set_burst_hook_value(name . "-" . tagname);
}
hook_example::name_hook();
]]>
</namehook>
Hook functions may call back into the PTC Server connection to access related objects that have already been created. Because documents are burst from the bottom up, the children of the current object will already exist in the PTC Server, but the parents will not. This means that direct children of the object may have been replaced by entity references.
Hook functions report errors by calling the dms::set_burst_hook_error() function. For example:
local docobj = dobj_construct(logid);
if (!dobj_valid(docobj))
{
dms::set_burst_hook_error(logid . " does not exist");
}
All errors for text objects are fatal, causing the entire burst to stop. Errors on graphic objects cause the creation of that object to fail, but the burst will proceed. In some cases the burst log may only contain an error code, not a detailed error message. To view the last error reported by a hook, enter the following command at the Arbortext Editor command line:
eval dms::burst_hook_error()
Customizing an Object's Location
A location hook is called after all DMS location rules have been processed and the location generated by the built-in bursting rules is available. If useroverride is set to on, the location is the Logical ID of the folder selected by the user in the Save As Properties dialog box.
The hook must specify a Logical ID or absolute path for a folder that exists in the PTC Server; folders will not be created automatically. The hook may generate a relative path name and append it to the default location. It may also dynamically create a folder and return its Logical ID.
The default location may be a path or a Logical ID To build a path relative to the default location, the hook may need to convert the Logical ID into a path.
Following is a sample location hook that appends a subdirectory to the path generated by the built-in rules. It calls a separate function to convert the Logical ID supplied by the built-in rules into a path name.
<locnhook sourcetype="text" type="acl">
<![CDATA[
if (oid_name(dms::burst_hook_first_oid()) != 'book')
{
dms::set_burst_hook_value(sample_hook::logid_to_path(dms::burst_hook_value())
. "/components");
}
]]>
</locnhook>
Customizing an Object's Name
An object name hook can be called after the burst naming rules have been processed and the name generated by the built-in bursting rules is available.
Following is an example hook that replaces all spaces in an object name with underscores:
<namehook sourcetype="text" type="acl">
<![CDATA[
# override default rules to replace all
# spaces with underscores in text object names.
function name_hook::text_location_hook()
{
local name=dms::burst_hook_value();
gsub(' ', '_', name);
dms::set_burst_hook_value(name);
}
name_hook::text_location_hook();
]]>
</namehook>
Defining Common Functions and Data
Functions (ACL only) can be defined in script elements within the burst configuration file and called from hooks. Code should always be inside a CDATA section. Functions defined in the system-wide burst configuration file may be used by hooks in doctype-specific burst configuration files. To avoid conflicts, it is recommended that you place functions in a package.
ACL code in script elements is executed when the burst configuration file is loaded. In general, avoid global variables.
Writing Hook Functions
Keep the following items in mind when writing hook functions:
• During development, you can use the response ACL function to pause bursting and display information. This is useful for tracing through a hook to verify that it is working as expected. For example,
local tagname=oid_name(dms::burst_hook_first_oid());
response("tagname=" . tagname);
local new_name=dms::burst_hook_value() . " " . tagname;
response("new_name=" . new_name);
• During development, you can use the sess_clear_burst_config(session) ACL function to clear out burst configuration settings you have loaded and reload the system-wide settings. Document-type-specific settings would then be loaded as they are needed, such as when a document of that document type is burst. This enables you to test new burst configuration settings without exiting Arbortext Editor.
• Consider using the eval ACL command to print to the Arbortext Editor message window. The results will not be visible until the burst has completed, but this is a convenient way to print a summary of hook execution during development. Use output=>* to append to the message window. For example:
eval new_name output=>*
• Consider developing and testing burst configuration files on your local machine before moving them to the PTC Server. Use the APTOBJCFG environment variable to specify a location for the burst configuration files.
• When developing hooks in document type-specific burst configuration files, connect to the PTC Server connection before opening your document. If a document is already open, the burst configuration file will be parsed when you connect; warnings are not displayed at that time.
• If you do not use the sess_clear_burst_config function, then to reload a burst configuration file, disconnect from the PTC Server connection, close any open documents, and reconnect.
• Consider building hook functions incrementally. Isolating problems can be easier when you test frequently after making small changes.
• For best performance during bursting, consider using simple hooks that call functions defined in script elements to do the work.
• If you plan to use hooks that generate relative path names, your default location rules should put all objects in the same folder. This ensures that the same default location will be passed to your hook each time it is called.