Fine-tuning the DITA customization
Upcoming SlideShare
Loading in...5

Fine-tuning the DITA customization






Total Views
Views on SlideShare
Embed Views



0 Embeds 0

No embeds



Upload Details

Uploaded via as Microsoft PowerPoint

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
Post Comment
Edit your comment

Fine-tuning the DITA customization Fine-tuning the DITA customization Presentation Transcript

  • 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
  • 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
  • 0. A few things not covered today:
    Conditional text dialogs
    Application macros
    Editor styles (CSS)
    Scripting extensions
    What can be customized
  • 1. Templates
    XMetaL Author
    default task template
    template for
    Acme Widget
  • 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
  • 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”
  • 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”
  • 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
  • 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:Program FilesXMetaL 6.0AuthorDITAXACstasktask_ditabase.dtd">
    Remove path info and “_ditabase”:
    <!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
    Fixing the DOCTYPE
  • Where to save your templates
    Replace any/all of these folders with your own
  • Where to save your templates
    Replace any/all of these files with your own
  • 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.
  • 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
  • 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;
  • 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;
  • 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
  • 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
  • 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
  • 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!
  • 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;
  • 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
  • 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.
  • 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;
  • 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
  • Write code for the following function:
    Adding items to the context menu
    concept_ditabase.prototype.OnSpecializeContextMenu =
    // 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.
  • Example:
    Adding items to the context menu
    concept_ditabase.prototype.OnSpecializeContextMenu =
    // 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;
  • 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
  • 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 =
    // 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.
  • For XMetaL scripting and customization information
    XMetaL Customization Guide
    XMetaL Programmer’s Guide
    Both are available here:
    Those guides are very deep and comprehensive
    Feel free to ask us for specific advice
    Where to go from here?
  • XMetaL users:
    XMetaL Community Forums
    JustSystems partners:
    JustSystems Partner Center
    Ask us for help (partner tech support)
    Community resources
  • Thank you for attending!