Reply To: Unique ids

[Derek Read]

This feature was well-intentioned and we have so far chosen to leave it as is for consistency and because we have not heard of anyone having the types of issues you are raising here. Is the DITA OT really slower when parsing id values like this during output creation? I'll see if I can reproduce that. When this feature was created DITA was suggesting that id values should be universally unique (hence our use of GUID-like id values). Early versions of the DITA OT would fail with fatal errors if this was not the case (that has not been true for a long time now, and I believe id values are now rewritten during the merging phases of map processing by the DITA OT).

You can override this behavior in an “extender” script file. Various entry points are provided, including one that allows customizers to alter the format of the values used for the auto-id functionality. This is not documented as it is typically something our partners would be expected to do, however, you can do it yourself if you are familiar with JScript.

There is a way to extend the product to create id values of your own design. A sample file is included here with (very) basic documentation inside it:
AuthorDITAXACsditabaseditabase_ditabase.off.js

To properly enable this functionality you need to:
1. Clone that file to the XAC folder containing the topic type(s) you use.

2. Rename the file so that it matches the name of the DTD in that folder but with a .js file extension.
Example:
AuthorDITAXACstasktask_ditabase.js

3. Inside the file change line line 47:
Old:  function ditabase_ditabase()
New:  function task_ditabase()

4. Change line 70 and the script between lines 71 and 74 to add your own override code (the stuff in red is what you will change):
 ditabase_ditabase.prototype.makeUniqueId = function(domNode)
 {
   // Override factory auto-id generator function
   return "ID" + strGetGUID() + "_" + domNode.nodeName;
 }

Example 1:
This one uses the standard JScript function Date(), so there is no need to know your way around any of the XMetaL Author APIs.

 task_ditabase.prototype.makeUniqueId = function(domNode)
 {
// Override factory auto-id generator function
var d = new Date();
return "gcrews" + "_" + d.getTime();
 }

Example 2:
This one is similar to Example 1 above but uses an additional XMetaL Author API called UniqueAttributeValue. It also uses the domNode value passed in to this prototype function (the function we are providing to override the default auto-id functionality) passes in (domNode) which allows you to obtain information about the element the ID is being set for (in this case I use it twice, once to obtain information about the element itself – the nodeName – and also to access the document node containing the element so that I can use the API UniqueAttributeValue on the correct document). You may wish to have a look at the XMetaL Developer Programmers Guide for documentation on these things.

 task_ditabase.prototype.makeUniqueId = function(domNode)
 {
// Override factory auto-id generator function
var prefix = domNode.ownerDocument.doctype.name + “_” + domNode.nodeName + “_”;
var docUniqueID = domNode.ownerDocument.UniqueAttributeValue(“id”,prefix,1);
return docUniqueID;
 }

5. Remove all of the other prototype functions that you are not using (in your case all of them) except the one you changed and the one at the very top that now looks like this:
function task_ditabase()
{
}

6. Save the file.

7. Repeat this process, if desired, for each document type you want to enable this behavior for.
 
These scripts are loaded dynamically when a document is opened or a new document is created from template so to test this you can simply save the .js file, and then select File > New (selecting the correct topic type, in this case a task). Make sure you test thoroughly on all document types you make this change for. If your script creates an invalid value XMetaL will catch it during validation (F9 or during a save) but not inside this script.

Reply