Reply To: How to Create New Element ID?

[Derek Read]

If this was for any DTD or W3C Schema other than DITA then it would make sense to try to figure this out. In that case you have full control over everything that is happening because the scripts you have created (your MCR files) are the only ones you need to worry about having conflicts with.

However, making modifications to the DITA authoring functionality is mostly not supported. CSS changes are supported, as are some configuration changes for CTM settings. However, because the entire DITA authoring system is implemented as an XMetaL customization that is running its own scripts, the only supported method for extending that functionality is by making modifications to a limited number of pre-defined scripting extension points. These are primarily meant to be used to add or change functionality for specialized DITA DTDs, but can also be used to alter some behaviours for the standard DITA DTDs.

They are limited to the following:

None of these will help you. I list them here because it may help to understand what is supported.

---

Specialization Extender:

• OnSpecializeCommandBars – for adding or modifying toolbars and menus
• OnSpecializeContextMenu – for adding or modifying context menu items (right click menu)
• makeUniqueId – for changing how ID values are constructed (the format) for the DITA auto-id feature, by defaultthe Windows GUID generator is used
• doProperties – provide a way to stop the context menu item for the DITA “Properties” dialog from being listed in the context of specific element(s)
• OnGetDisplayNameForDomain – provides control over the items listed for “Domains” in the DITA options dialog

A .js file needs to be placed in the XACs folder for the particular DITA DTD you wish to extend this functionality for. There is a specific naming convention for that filename and there is a specific naming convention for each of the prototype functions (that allow for code extension) that need to be defined inside that file.

A demo file is included here:
C:Program FilesXMetaL AuthorDITAXACsditabaseditabase_ditabase.off.js

To enable this functionality the file must be renamed to match the DTD filename in the same XACs subfolder for the particular DITA DTD you want to extend. So, for example, enable the demo file by renaming it ditabase_ditabase.js
Documentation for the file itself is included in inline comments inside the .js file listed above.

You may want to step through the DITA authoring code in a debug session to see what it does for any of the items you want to extend in order to understand how the existing code works. Without knowing that it is easy to break existing functionality. Two exceptions are possibly makeUniqueId and doProperties, which are quite simple and easily demonstrated by the provided demo code.

---

If you need to make modifications to a document programmatically, that might be done in a way that does not necessarily conflict with the DITA authoring functionality, but it would be difficult to support this. The APIs you are using in your sample code are ones that mimic behaviours that an author (end user) can do themselves, and so it might be possible to create a macro that does not get in the way of the DITA authoring functionality (which includes automatically setting DITA id attributes). To answer this for certain it would be best to provide a full (in your case not really working) sample to XMetaL Support to see if there is something that can be done. Again, this is unsupported so there are no guarantees, but it might be possible. XML file + MCR that includes whatever code you have so far and as much of a description as possible.

Keep in mind that “supported” also means something you create today will continue to function with all future versions. That is always true (short of introduced bugs that are later fixed) for all XMetaL APIs. However, it isn't true for the DITA functionality because of the potential for conflict, that the functionality might change in the future, and that it isn't documented to have been written to function in any specific way (unlike the XMetaL APIs). So, something created today that changes how the DITA authoring functions might work in a specific version but isn't guaranteed to work in the future (the only ones we plan to continue to support are those extension points listed above).

Reply