fine-tuning the dita customization

Click here to load reader

Post on 18-Dec-2014




3 download

Embed Size (px)




  • 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:
    Conditional text dialogs
    Application macros
    Editor styles (CSS)
    Scripting extensions
    What can be customized
  • 4. 1. Templates
    XMetaL Author
    default task template
    template for
    Acme Widget
  • 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
  • 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;
  • 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;
  • 16. Add new JScript code specific to any one DITA doctype (including concept, task, reference)
    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
    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);