fine-tuning the dita customization

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

Post on 18-Dec-2014

1.432 views

Category:

Documents

3 download

Embed Size (px)

DESCRIPTION

 

TRANSCRIPT

  • 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)
    [email protected]
    Community resources
  • 31. Thank you for attending!
    Q&A