This document discusses customizing the authoring experience in XMetaL DITA. It describes how to customize templates, editor styles (CSS), script code using DitaSpecializationExtender, ID auto-generation algorithms, properties dialogs, context menus, and command bars (toolbars and menus). Examples are provided for each type of customization. The document directs users to resources like the XMetaL Customization Guide, Programmer's Guide, community forums, and partner support for additional help with customizations.

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. You’ve 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 <p><?xm-replace_text Paragraph?></p> 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” won’t do XMetaL automatically adds IDs and other stuff that you don’t 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: <!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "C:rogram FilesMetaL 6.0uthorITAACsaskask_ditabase.dtd"> Remove path info and “_ditabase”: <!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd"> 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 <note> 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 <note> elements a different colored background for one specific topic type Add this to concept_ditabase-specialized.css: Now <note>s in <concept> 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:rogram FilesMetaL 6.0uthorITAACsitabaseditabase_ditabase.off.js Paste into this directory: C:rogram FilesMetaL 6.0uthorITAACsoncept 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. <image> Others are generic default dialogs, e.g. <p> 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 Programmer’s 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