Fine-tuning the DITA customization


Published on

1 Like
  • Be the first to comment

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

Fine-tuning the DITA customization

  1. 1. in 37 minutes<br />Episode 23<br />Fine-tuning the DITA <br />authoring experience: Customizing the XMetaL DITA customization<br />Tom Magliery, XML Technology Specialist<br />9 June 2011<br />Brought to you by XMetaL Technical Services<br />
  2. 2. What is a “customization” of XMetaL?<br />What is the “DITA customization”?<br />What do we mean by “do not support modifying the DITA customization”?<br />So then, what can be customized?<br />Introduction and background<br />
  3. 3. 0. A few things not covered today:<br />DITA OT<br />Conditional text dialogs<br />Application macros<br />Templates<br />Editor styles (CSS)<br />Scripting extensions<br />What can be customized<br />
  4. 4. 1. Templates<br />XMetaL Author<br />default task template<br />Customized <br />“procedure” <br />template for <br />Acme Widget <br />Company<br />
  5. 5. A template (DITA or otherwise) is just an XML file, saved in a specific location<br />Edit the file<br />Open any XML file in any XML editor, edit it normally<br />Recommendation: Use XMetaL, of course! <br />Put the file in the right place<br />Will show where that is shortly ...<br />Editing templates in XMetaL<br />
  6. 6. You’ve seen these bits of replaceable text:<br />They are created by using replace-text PIs*<br />Put them anywhere text is allowed to go<br />Edit them in Plain Text View in XMetaL<br />Replaceable text<br />This can be any text you want<br /><p><?xm-replace_text Paragraph?></p><br />The rest must be exactly as shown here<br />* PI == XML “processing instruction”<br />
  7. 7. If you are editing DITA templates in XMetaL, a normal “Save” or “Save As” won’t do<br />XMetaL automatically adds IDs and other stuff that you don’t want in your template<br />Instead of “Save”, use the “Save Copy as Template” DITA macro<br />Strips out auto-generated IDs and other stuff<br />NOTE: You still must fix the DOCTYPE !<br />More in a moment ...<br />“Save Copy as Template”<br />
  8. 8. Finding the “Save Copy as Template” macro<br />1. Enable the “Macros” <br />toolbar by right-clicking <br />in the toolbar area<br />2. Select the macro from <br />the pull-down menu<br />3. Run it by<br />clicking the <br /> button<br />
  9. 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<br />First line of the file will look like this:<br /> <!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "C:Program FilesXMetaL 6.0AuthorDITAXACstasktask_ditabase.dtd"><br />Remove path info and “_ditabase”:<br /> <!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd"><br />Fixing the DOCTYPE<br />
  10. 10. Where to save your templates<br />Replace any/all of these folders with your own<br />
  11. 11. Where to save your templates<br />Replace any/all of these files with your own<br />
  12. 12. 2. Editor styles (CSS)<br />Primary CSS file for each DITA doctype customization<br />merely imports five other files:<br />“Mytopic” can also be concept, task, reference, etc.<br />
  13. 13. The CSS files are loaded in this order:<br /> ditabase-base.cssditabase-base-override.css [yours]ditabase-derived.cssditabase-derived-override.css [yours]mytopic_ditabase-specialized.css [yours]<br />If two rules match the same element and assign the same properties, the one that was loaded last will “win”<br />Also, more specific selector rules will win over less specific ones<br />Order of CSS loading<br />
  14. 14. Give <note> elements a yellow background<br />Add this to ditabase-base-override.css:<br />Note use of attribute-value matching instead of the element name<br />CSS example 1<br />[class~="topic/note"] {<br /> background-color: yellow;<br />}<br />ditabase-base.cssditabase-base-override.cssditabase-derived.cssditabase-derived-override.css<br />mytopic_ditabase-specialized.css<br />
  15. 15. Give <note> elements a different colored background for one specific topic type<br />Add this to concept_ditabase-specialized.css:<br />Now <note>s in <concept> topics will be green.<br />CSS example 2<br />[class~="topic/note"] {<br /> background-color: #ffccff;<br />}<br />ditabase-base.cssditabase-base-override.cssditabase-derived.cssditabase-derived-override.css<br />mytopic_ditabase-specialized.css<br />
  16. 16. Add new JScript code specific to any one DITA doctype (including concept, task, reference)<br />Examples:<br />Change the ID auto-generation algorithm<br />Override default “properties” dialogs<br />Add items to the context menu<br />Modify menus/toolbars<br />3. Adding script code withDitaSpecializationExtender<br />
  17. 17. Copy this file (sample code included with XMetaL):<br />C:Program FilesXMetaL<br />Paste into this directory:<br />C:Program FilesXMetaL 6.0AuthorDITAXACsconcept<br />Rename to mytopic_ditabase.js<br />Global search/replace “ditabase_ditabase” with “mytopic_ditabase”<br />Add your custom code to the function implementations in the file<br />Using DitaSpecializationExtender<br />
  18. 18. XMetaL automatically assigns IDs to certain elements using a built-in algorithm<br />Which elements – depends on your user preferences<br />You can change the algorithm that will be used<br />You can even use different algorithms for different elements<br />ID auto-generation algorithm<br />
  19. 19. Write code for the following function:<br />ID auto-generation algorithm<br />concept_ditabase.prototype.makeUniqueId = function(domNode)<br />{<br /> // Complete the function with code that<br /> // returns a string. The returned string<br /> // will be used as the new unique ID.<br /> // Be sure the string is a valid XML ID!<br />}<br />
  20. 20. Example:<br />ID auto-generation algorithm<br />concept_ditabase.prototype.makeUniqueId = function(domNode)<br />{<br /> // for the root, allow XMetaL default behaviour<br /> if (domNode.nodeName == "concept") <br /> {<br /> return null;<br /> }<br /> // Otherwise choose a random integer, <br /> // convert it to hexadecimal, and append<br /> // the result to the nodename.<br />varhstr = Math.floor(1000000000*Math.random()).toString(16);<br /> return domNode.nodeName + "_37mins_" + hstr;<br />}<br />
  21. 21. XMetaL has a “Properties” command on the context menu<br />Launches a dialog to set properties of the element<br />Some properties dialogs are already “custom”, e.g. <image><br />Others are generic default dialogs, e.g. <p><br />The doProperties function allows you to override the generic defaults and launch your own custom dialogs (or whatever you want)<br />Overriding properties dialogs<br />
  22. 22. Write code for the following function:<br />Overriding properties dialogs<br />concept_ditabase.prototype.doProperties = function(rng)<br />{<br /> // rng will be a Range representing the location <br /> // that was selected.<br /> // Your function should return “true” if you have<br /> // handled the properties command with behavior of<br /> // your own.<br /> // Your function should return “false” if you wish<br /> // to allow the default XMetaL behavior to occur.<br />}<br />
  23. 23. Example:<br />NOTE: With XFT you can do fancier stuff<br />Overriding properties dialogs<br />concept_ditabase.prototype.doProperties = function(rng)<br />{<br /> // Do something special if selection is in a paragraph<br /> if (rng.ContainerName == "p")<br /> {<br />varstr = Application.Prompt("Enter a new ID");<br />rng.ContainerNode.setAttribute("id", str);<br /> return true;<br /> }<br /> // ...otherwise, let built-in behavior run<br /> return false; <br />}<br />
  24. 24. You can add commands to the context menu for performing additional operations on the selected element<br />There must be a macro available to perform each command you wish to add<br />Adding items to the context menu<br />
  25. 25. Write code for the following function:<br />Adding items to the context menu<br />concept_ditabase.prototype.OnSpecializeContextMenu = <br /> function(cmdPopup)<br />{<br /> // cmdPopup is a CommandBar representing the context menu<br /> // Use the CommandBar interface to add item(s)<br /> // No need to return any value from this function.<br />}<br />
  26. 26. Example:<br />Adding items to the context menu<br />concept_ditabase.prototype.OnSpecializeContextMenu = <br /> function(cmdPopup)<br />{<br /> // Add "Hello, world" menu item<br />var ctrl = cmdPopup.Controls.Add(sqcbcTypePopup, null);<br /> if (ctrl) {<br />ctrl.BeginGroup = true;<br />ctrl.DescriptionText = "The old classic, XMetaL style.";<br />ctrl.OnAction = "Hello World"; <br />ctrl.Caption = "Say hello!";<br />ctrl.FaceId = 0;<br /> }<br />}<br />
  27. 27. Command bars is the collective name for all the toolbars and menus in XMetaL<br />You can add items for inserting specialized elements ... or anything else<br />Function is called while XMetaL is initializing the command bars<br />Modifying command bars<br />
  28. 28. Write code for the following function:<br />This type of code is a bit long and tedious – not showing an example today<br />Modifying toolbars and menus<br />concept_ditabase.prototype.OnSpecializeCommandBars = <br /> function(cmdBars)<br />{<br /> // cmdBars is a CommandBars object representing the<br /> // XMetaL command bars collection (menus + toolbars)<br /> // Write code in here to add/remove items from<br /> // the menus and toolbars as desired.<br />}<br />
  29. 29. For XMetaL scripting and customization information<br />XMetaL Customization Guide<br />XMetaL Programmer’s Guide<br />Both are available here:<br /><br />Those guides are very deep and comprehensive<br />Feel free to ask us for specific advice<br />Where to go from here?<br />
  30. 30. XMetaL users: <br />XMetaL Community Forums<br /><br />JustSystems partners:<br />JustSystems Partner Center<br /><br />Ask us for help (partner tech support)<br /><br />Community resources<br />
  31. 31. Thank you for attending!<br />Q&A<br />