1. in 37 minutes
Episode 23
Fine-tuning the DITA
authoring experience: Customizing the XMetaL DITA customization
Tom Magliery, XML Technology Specialist
9 June 2011
Brought to you by XMetaL Technical Services

2. What is a customization of XMetaL?
What is the DITA customization?
What do we mean by do not support modifying the DITA customization?
So then, what can be customized?
Introduction and background

3. 0.A few things not covered today:
DITA OT
Conditional text dialogs
Application macros
Templates
Editor styles (CSS)
Scripting extensions
What can be customized

4. 1. Templates
XMetaL Author
default task template
Customized
procedure
template for
Acme Widget
Company

5. A template (DITA or otherwise) is just an XML file, saved in a specific location
Edit the file
Open any XML file in any XML editor, edit it normally
Recommendation: Use XMetaL, of course!
Put the file in the right place
Will show where that is shortly ...
Editing templates in XMetaL

6. Youve seen these bits of replaceable text:
They are created by using replace-text PIs*
Put them anywhere text is allowed to go
Edit them in Plain Text View in XMetaL
Replaceable text
This can be any text you want

The rest must be exactly as shown here
* PI == XML processing instruction

7. If you are editing DITA templates in XMetaL, a normal Save or Save As wont do
XMetaL automatically adds IDs and other stuff that you dont want in your template
Instead of Save, use the Save Copy as Template DITA macro
Strips out auto-generated IDs and other stuff
NOTE: You still must fix the DOCTYPE !
More in a moment ...
Save Copy as Template

8. Finding the Save Copy as Template macro
1. Enable the Macros
toolbar by right-clicking
in the toolbar area
2. Select the macro from
the pull-down menu
3. Run it by
clicking the
button

9. After you save a DITA template with that macro, you must open it in a text editor (not XMetaL) and repair the DOCTYPE declaration
First line of the file will look like this:

Remove path info and _ditabase:

Fixing the DOCTYPE

10. Where to save your templates
Replace any/all of these folders with your own

11. Where to save your templates
Replace any/all of these files with your own

12. 2. Editor styles (CSS)
Primary CSS file for each DITA doctype customization
merely imports five other files:
Mytopic can also be concept, task, reference, etc.

13. The CSS files are loaded in this order:
ditabase-base.cssditabase-base-override.css [yours]ditabase-derived.cssditabase-derived-override.css [yours]mytopic_ditabase-specialized.css [yours]
If two rules match the same element and assign the same properties, the one that was loaded last will win
Also, more specific selector rules will win over less specific ones
Order of CSS loading

14. Give elements a yellow background
Add this to ditabase-base-override.css:
Note use of attribute-value matching instead of the element name
CSS example 1
[class~="topic/note"] {
background-color: yellow;
}
ditabase-base.cssditabase-base-override.cssditabase-derived.cssditabase-derived-override.css
mytopic_ditabase-specialized.css

15. Give elements a different colored background for one specific topic type
Add this to concept_ditabase-specialized.css:
Now s in topics will be green.
CSS example 2
[class~="topic/note"] {
background-color: #ffccff;
}
ditabase-base.cssditabase-base-override.cssditabase-derived.cssditabase-derived-override.css
mytopic_ditabase-specialized.css

16. Add new JScript code specific to any one DITA doctype (including concept, task, reference)
Examples:
Change the ID auto-generation algorithm
Override default properties dialogs
Add items to the context menu
Modify menus/toolbars
3. Adding script code withDitaSpecializationExtender

17. Copy this file (sample code included with XMetaL):
C:Program FilesXMetaL 6.0AuthorDITAXACsditabaseditabase_ditabase.off.js
Paste into this directory:
C:Program FilesXMetaL 6.0AuthorDITAXACsconcept
Rename to mytopic_ditabase.js
Global search/replace ditabase_ditabase with mytopic_ditabase
Add your custom code to the function implementations in the file
Using DitaSpecializationExtender

18. XMetaL automatically assigns IDs to certain elements using a built-in algorithm
Which elements depends on your user preferences
You can change the algorithm that will be used
You can even use different algorithms for different elements
ID auto-generation algorithm

19. Write code for the following function:
ID auto-generation algorithm
concept_ditabase.prototype.makeUniqueId = function(domNode)
{
// Complete the function with code that
// returns a string. The returned string
// will be used as the new unique ID.
// Be sure the string is a valid XML ID!
}

20. Example:
ID auto-generation algorithm
concept_ditabase.prototype.makeUniqueId = function(domNode)
{
// for the root, allow XMetaL default behaviour
if (domNode.nodeName == "concept")
{
return null;
}
// Otherwise choose a random integer,
// convert it to hexadecimal, and append
// the result to the nodename.
varhstr = Math.floor(1000000000*Math.random()).toString(16);
return domNode.nodeName + "_37mins_" + hstr;
}

21. XMetaL has a Properties command on the context menu
Launches a dialog to set properties of the element
Some properties dialogs are already custom, e.g.
Others are generic default dialogs, e.g.

The doProperties function allows you to override the generic defaults and launch your own custom dialogs (or whatever you want)
Overriding properties dialogs

22. Write code for the following function:
Overriding properties dialogs
concept_ditabase.prototype.doProperties = function(rng)
{
// rng will be a Range representing the location
// that was selected.
// Your function should return true if you have
// handled the properties command with behavior of
// your own.
// Your function should return false if you wish
// to allow the default XMetaL behavior to occur.
}

23. Example:
NOTE: With XFT you can do fancier stuff
Overriding properties dialogs
concept_ditabase.prototype.doProperties = function(rng)
{
// Do something special if selection is in a paragraph
if (rng.ContainerName == "p")
{
varstr = Application.Prompt("Enter a new ID");
rng.ContainerNode.setAttribute("id", str);
return true;
}
// ...otherwise, let built-in behavior run
return false;
}

24. You can add commands to the context menu for performing additional operations on the selected element
There must be a macro available to perform each command you wish to add
Adding items to the context menu

25. Write code for the following function:
Adding items to the context menu
concept_ditabase.prototype.OnSpecializeContextMenu =
function(cmdPopup)
{
// cmdPopup is a CommandBar representing the context menu
// Use the CommandBar interface to add item(s)
// No need to return any value from this function.
}

26. Example:
Adding items to the context menu
concept_ditabase.prototype.OnSpecializeContextMenu =
function(cmdPopup)
{
// Add "Hello, world" menu item
var ctrl = cmdPopup.Controls.Add(sqcbcTypePopup, null);
if (ctrl) {
ctrl.BeginGroup = true;
ctrl.DescriptionText = "The old classic, XMetaL style.";
ctrl.OnAction = "Hello World";
ctrl.Caption = "Say hello!";
ctrl.FaceId = 0;
}
}

27. Command bars is the collective name for all the toolbars and menus in XMetaL
You can add items for inserting specialized elements ... or anything else
Function is called while XMetaL is initializing the command bars
Modifying command bars

28. Write code for the following function:
This type of code is a bit long and tedious not showing an example today
Modifying toolbars and menus
concept_ditabase.prototype.OnSpecializeCommandBars =
function(cmdBars)
{
// cmdBars is a CommandBars object representing the
// XMetaL command bars collection (menus + toolbars)
// Write code in here to add/remove items from
// the menus and toolbars as desired.
}

29. For XMetaL scripting and customization information
XMetaL Customization Guide
XMetaL Programmers Guide
Both are available here:
http://na.justsystems.com/content-support-user-guides
Those guides are very deep and comprehensive
Feel free to ask us for specific advice
Where to go from here?

30. XMetaL users:
XMetaL Community Forums
http://forums.xmetal.com/
JustSystems partners:
JustSystems Partner Center
http://justpartnercenter.com/
Ask us for help (partner tech support)
partnersupport-na@justsystems.com
Community resources

31. Thank you for attending!
Q&A