Automatic ID Generation

[Eddie]

Hello,
We want to generate IDs automatically for topics, but we want some control over the ID. For example, we don't want any underscores in the ID. Is there a way to do this? Perhaps by defining the "id" part of "${localName}_${id}"

Thanks,

Eddie.

[alex_jitianu]

Hello Eddie,

In case of newly created topics all you have to do is change the used template: ${oxygenInstallDir}/frameworks/dita/templates/Topic.dita. You can change the editor variables used for the id attribute, for example let only the ${id} part. Alternatively you can use a custom editor variable which can be either defined inside options or resolved through the API (if you are interested in this please let me know and I can offer some more details about each).

In case of the the *Generate IDs...* action (available in the DITA menu), there is a configuration file that you can edit. Open ${oxygenInstallDir}/frameworks/dita/resources/idGenerationDefaultOptions.xml and change the value of element idPattern. You can also use custom editor variables as described above. We also have API for controlling the ID generation and pattern but I wont go into details unless you think you need to go on this path.

Best regards,
Alex

[Eddie]

Thanks for the reply, Alex.

To be more precise, we just want to control the id part such that the id starts with a lowercase letter and only contains lowercase letters, numbers and dashes. At the moment, we are telling our users to turn off automatic id generation and create ids manually. It seems we can't do what we want using the config file or options you mentioned, but we don't want our users to get too technically involved, so we don't want them to have to go so far as editing with APIs. We'll stick with manual creation for now.
Cheers,
Eddie.

[alex_jitianu]

Hello Eddie,

First of all I want to clarify one aspect. If you decide that the Java API is the only solution for a given problem that doesn't mean that your users will have to use the API. A developer will use the API to create a customization and the customization will then be deployed to the users. The whole process will be completely transparent for the common user.

Your requirement for a valid ID matches pretty good what our ${id} function already does. With one exception: we don't use dashes but underscores. Are these underscores the ones you don't like in the ID? If that's the case you can replace them with dashes using this pattern:

Code: Select all

${localName}_${xpath_eval(replace("${id}", "_", "-"))}

What you must do is to replace the default pattern with this one:
- inside DITA templates from ${oxygenInstallDir}/frameworks/dita/templates/
- inside elements idPattern from ${oxygenInstallDir}/frameworks/dita/resources/idGenerationDefaultOptions.xml.

After you do these changes you can pack the framework and deliver it to authors along with instructions on how to install it. You can either:
- ZIP ${oxygenInstallDir}/frameworks/dita and instruct the user to unzip inside {OxygenInstallDir}/frameworks.
- pack it as an add-on and publish it on an HTTP server. The users will receive an URL and instructions on how to use that URL to automatically install the plugin in Oxygen.

Best regards,
Alex

[Eddie]

Thanks, Alex.

That's exactly what we want.

Cheers,
Eddie.

[lief.erickson]

When someone creates a new DITA reference file through File > New, I'd like to copy the automatically generated ID and reuse it in a couple of places so that some @conrefs resolve. This is what I'm currently doing, but the ${xpath_eval} is returning nothing. I'm fairly positive I have everything correct. What am I missing?

Code: Select all

<reference id="${id}">

 <title><ph conref="#${xpath_eval(reference/@id)}/api-method"/></title>

 <refbody>

  <ph id="api-method">PUT</ph>

 </refbody>

</reference>

-Lief

[Radu]

Hi Lief,

This approach does not work because the editor variables are expanded before the content is inserted in the editor so the xpath evaluation does not return anything.
So using xpath_eval in a new file template content makes sense only if it is a static expression, evaluating for example an XPath on an external file.

As possible workarounds for your problem:

1) Have you considered setting a fixed ID on the reference root instead of using ${id}?
The DITA specification states that the topic ID must be unique in the context of the current file. So it is not mandatory that the topic ID should be unique in the context of the entire DITA Map.
Only some CMSs require this.

2) You could use our Java API from the Author SDK to add a listener and when the new editor is opened make changes in it.

3) You could use conkeyref instead of conref. The conkeyref syntax would be something like:

Code: Select all

<ph conkeyref="keyName/api-method"/>

but you would also need to define the "keyName" key on the topic reference.

DITA 1.3 will have a new feature in which you will be able to use a construct like:

Code: Select all

<ph conref="#./api-method"/>

to refer to an element in the same topic context.

Regards,
Radu

[lief.erickson]

Thanks for the answer, Radu. I'm not currently using a CMS, so I went with #1.