Pages: 1
Author Topic: Script Example: DITA Bulk TopicRef Inserter  (Read 3969 times)
Derek Read
Program Manager (XMetaL)

Posts: 2443

« on: May 20, 2011, 05:08:52 PM »

Tested with XMetaL Author Enterprise and (aka: 6.0 and 6.0 SP1)

This macro allows you to select one or more files (DITA topics) and have references to them inserted into an open DITA map file using <topicref> elements.

This is a quick attempt to improve the map editing interface. We may add similar (possibly more robust) functionality to an official release.

1. Download
2. Shut down XMetaL Author Enterprise.
3. Unzip downloaded file and copy the MCR file it contains into <XMetaL Author Install Path>\Author\Startup

1. Launch XMetaL Author Enterprise.
2. Open a map or bookmap and position insertion point at the location you wish to insert multiple <topicref> elements.
3. From the Macros toolbar run the macro named "DITA Bulk TopicRef Inserter - v1.0".
4. Browse to and select one or more DITA documents from a single folder on your local machine then select "Open".

1. Delete the MCR file installed in steps above.
2. Restart XMetaL Author Enterprise.

- This is beta code. Use in a production environment only after you are satisfied with its behavior -- test on sample documents first.
- This macro is not designed for use with XMetaL Connector and as such should not be used in conjunction with a CMS integration.
- This macro is not DITA-specialization-aware. It assumes you are editing a standard DITA map or bookmap and inserts <topicref> elements using their standard DITA attribute names.
Assumptions and Limitations:
1. A map file must be the active document open in TagsOn or Normal view (and not in the Map Editor in the Resource Manager). The macro will appear in the Macros toolbar list for all document types but should only be used for DITA Map files open in TagsOn or Normal view. Running this macro with another document type open should not cause any problems and the macro should simply fail to run. However, if it does modify the document simply press undo until the document has reverted to its previous state.

2. <topicref> elements for each of the files you have selected will be inserted into the map regardless of the type of files you choose. This means that references may be created that refer to files that are not DITA topics. The documents are parsed after the references have been inserted in order to populate the navtitle attribute. Non-DITA documents will have "untitled topic" as their navtitle and should be easy to spot (and remove if desired). Note that topics that do not have a title will also have "untitled topic" as their navtitle. In this case you can right click on them to open them and correct the omission.
3. Topic references (topicref elements) are inserted at the next possible location in the document. So, before you run this script place your cursor inside the document at the location you wish the insertion of these elements to begin. You may find it is easiest to do this in TagsOn view if you require the insertion to begin at a very specific location.
4. In this version the topicref href values are generated relative to the existing DITA Map file. This means that the user must first save the DITA map before running this script.

5. The Windows MSComDlg control (a standard Windows control used by this script) returns a list of files in an order that does not generally match the order the user sees or selects. This script sorts the files alphabetically by filename before insertion of their corresponding topicrefs.

6. Topic references are all inserted at the same level. If you wish nest topic references that you have just inserted switch to TagsOn view and drag and drop them to nest one inside another.

7. All topicref elements inserted should have the following attributes set:
<topicref href="{relative path to file you chose}" format="dita" scope="local" type="topic">

Refer to the code inside the MCR file for comments regarding changing the attributes that are inserted and their values.

 Licensed Materials - Property of JustSystems, Canada, Inc.

 (c) Copyright JustSystems Canada, Inc. 2011
 All rights reserved.

 The sample contained herein is provided to you "AS IS".

 It is furnished by JustSystems Corporation as a simple example and
 has not been thoroughly tested under all conditions. JustSystems
 Canada, Inc., therefore, cannot guarantee its reliability,
 serviceability or functionality.

 This sample may include the names of individuals, companies, brands
 and products in order to illustrate concepts as completely as
 possible. All of these names are fictitious and any similarity to
 the names and addresses used by actual persons or business
 enterprises is entirely coincidental.

* (3.69 KB - downloaded 289 times.)
« Last Edit: May 20, 2011, 05:16:36 PM by Derek Read » Logged

Posts: 56

« Reply #1 on: February 23, 2012, 02:35:28 PM »

When I run the macro, with a saved DITA Map open in Tags On or Normal view, I receive a Run-Time Error: Line 125, Column 2 Description: Automation server can't create object.

XMetaL Author Enterprise on Windows 7 64-bit SP1.

Is this a Windows 7 issue?



DST Systems, Inc.
Derek Read
Program Manager (XMetaL)

Posts: 2443

« Reply #2 on: February 23, 2012, 04:40:37 PM »

The line in question is this one:

      var commonDlg = new ActiveXObject("MSComDlg.CommonDialog");

It is trying to create a "browse for files" dialog using a standard Windows control commonly installed on XP (which is where I tested the script). The error you are seeing means that the control is either not on your machine or it is not registered.

I have been unsuccessful trying to find official information from Microsoft that discusses why this control is not available on Windows 7 but that appears to be the case (it might not be on Vista either).

I used this Windows control because it allows you to do multi-select when browsing for files. SQExtras (a control included with XMetaL Author) does not support multi-select when choosing files. There was some discussion recently of extending it to allow for multi-select, but when I wrote this you could only select a folder or a single file. The script could probably be rewritten to use SQExtras but possibly with reduced functionality. If you want to try doing that you can search for "SQExtras" in the XMetaL Developer Programmers Guide.

You might try copying the control from an XP machine to your Windows 7 machine and registering it using RegSvr32.exe. That might be the simplest solution if it will actually work on Windows 7. The control is this one C:\Windows\System32\comdlg32.ocx. It is a 32-bit control, and should probably be installed on a 64-bit machine using "WOW" (the Microsoft 'Windows on Windows' emulator -- aka: 32-bit compatibility mode). There is a discussion about getting this control into a Windows 7 installation here: Whether you can legally do this is a question to ask Microsoft.

Or you could try to find, install, and register a control that provides similar functionality to that one (but this would likely require script alterations as well since the properties will probably be different).

I will revisit my discussion with development to see if they can make insertion of multiple <topicref> elements into a map at one time, pointing to different files, into a first-class feature.
« Last Edit: February 23, 2012, 04:42:46 PM by Derek Read » Logged
Pages: 1
Jump to: