Defining Object Location and Naming Rule Hooks
During bursting, the object naming rules provide a set of options for specifying the name of the object, and the object location rules provide a way to specify where new objects should be created. However, you may have requirements for names and locations of new objects that are more complex than the default rules allow. If so, you can write your own naming or location logic in an ACL function and the bursting logic will call into it as a hook.
Hooks are defined in the burst configuration files. Except for simple one-line hooks, hook definitions should always be inside a CDATA section. The following information on defining hooks applies to default and document type-specific burst configuration files.
Configuring Object Location Hooks
In addition to locnrule elements, a dmslocation element may contain locnhook elements which define hooks. locnhook has the following attributes:
• type — Required. acl as the only valid value.
• sourcetype — Optional. A value of text (the default) specifies the hook should be called for text objects. A value of graphic specifies the hook should be called for graphic objects.
Only one hook may be specified for each source type. If multiple locnhook elements are specified for the same source type, the last one is used. Note that any folder used to store objects in an object location hook must already exist on the PTC Server.
Location hooks defined in document-type-specific burst configuration files override hooks defined in the system-wide burst configuration. For each source type, if no hook is defined in the document-type-specific burst configuration, the system-wide hook will be used (if any).
Following is an example of an object location hook that assigns text objects to a folder based on the value stored in the role attribute for the current object:
<dmslocation>
<locnrule location="/Graphics" sourcetype="graphic"/>
<!-- hook function which organizes components based on -->
<!-- the value stored in the attribute ‘role’. Arbortext Editor's -->
<!-- built-in location rules are ignored for text objects. -->
<locnhook sourcetype="text" type="acl">
<![CDATA[
function mypackage::generate_folder(oid)
{
# root_folder is a global variable defined in the user's
# ACL startup scripts. It contains the path name of the
# root folder for storing all documents (e.g., "/home/joe").
local folder_path = oid_xpath_string(oid, \
'translate(normalize-space(@role)," ", "_")');
return mypackage::root_folder . "/" . folder_path;
}
dms::set_burst_hook_value(mypackage::generate_folder(dms::burst_hook_first_oid()));
]]>
</locnhook>
</dmslocation>
Following is an example of an object location hook that uses XPath to assign text objects to a folder based on the object's parent and grandparent objects:
<dmslocation>
<locnrule location="/Graphics" sourcetype="graphic"/>
<!-- hook function which organizes components based on -->
<!-- their parent and grandparent. Arbortext Editor's built-in -->
<!-- location rules are ignored for text objects. -->
<locnhook sourcetype="text" type="acl">
<![CDATA[
function mypackage::generate_path(oid)
{
# root_folder is a global variable defined in the user's
# ACL startup scripts. It contains the path name of the
# root folder for storing all documents (e.g., "/home/joe").
local rel_path = oid_xpath_string(oid, \
'translate(normalize-space(concat(parent::*/title,"/",title))," ", "_")');
return mypackage::root_folder . "/" . rel_path;
}
dms::set_burst_hook_value(mypackage::generate_path(dms::burst_hook_first_oid()));
]]>
</locnhook>
</dmslocation>
Using locations relative to the top-level object requires careful planning. If the objectreuse attribute is set to on, the folder for the top-level object will always be the default, otherwise it will depend on the location rules. Because documents are burst from the bottom up, you cannot simply store the location of the top-most object.
Additionally, when bursting while checking in objects, the location of the top-level object is not available. To determine the location of the top-level object, you will need to write custom code for your site.
Configuring Default Naming Rule Hooks
In addition to namerule elements, a defaultnamecriteria element may contain namehook elements which define the hooks. namehook has the following attributes:
• type — Required. acl as the only valid value.
• sourcetype — Optional. A value of text (the default) specifies the hook should be called for text objects. A value of graphic specifies the hook should be called for graphic objects.
Only one hook may be defined for each source type. If multiple namehook elements are specified for the same source type, the last one is used.
Following is an example of configuring a default naming rule hook:
<defaultnamecriteria>
<namerule rule="topmost-is-filename"/>
<namerule rule="expression" nameexpression="%division-head-content% (%element-name%)"/>
<namerule rule="division-head-content"/>
<namerule rule="element-content"/>
<namerule rule="element-name"/>
<!-- hook function which appends the root document 'id' -->
<!-- attribute to all object names -->
<namehook sourcetype="text" type="acl">
<![CDATA[
function sample_hook::adjust_name()
{
local ctx = dms::burst_hook_first_oid();
local basename = dms::burst_hook_value();
local attr_val = oid_xpath_string(ctx, "/book/attribute::id")
dms::set_burst_hook_value(basename . "-" . attr_val);
}
sample_hook::adjust_name();
]]>
</namehook>
</defaultnamecriteria>
Configuring Naming Rule Hooks
The content of the namecriteria element in the document-type-specific burst configuration file is identical to the defaultnamecriteria element in the system-wide burst configuration (that is, atidefaults.bcf). If a name hook is not specified in the document-type-specific burst configuration file, the hook specified in the system-wide burst configuration file is used (if any).