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

Upload: xmetal

Post on 18-Dec-2014

1.435 views

Category:

Documents


3 download

DESCRIPTION

 

TRANSCRIPT

Page 1: Fine-tuning the DITA customization

© 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

Page 2: Fine-tuning the DITA customization

© 2011 JustSystems Inc.

• 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

Page 3: Fine-tuning the DITA customization

© 2011 JustSystems Inc.

0. A few things not covered today:– DITA OT– Conditional text dialogs– Application macros

1. Templates

2. Editor styles (CSS)

3. Scripting extensions

What can be customized

Page 4: Fine-tuning the DITA customization

© 2011 JustSystems Inc.

1. Templates

XMetaL Authordefault task template

Customized “procedure” template for Acme Widget Company

Page 5: Fine-tuning the DITA customization

© 2011 JustSystems Inc.

A template (DITA or otherwise) is just an XML file, saved in a specific location

1. Edit the file– Open any XML file in any XML editor, edit it normally– Recommendation: Use XMetaL, of course!

2. Put the file in the right place– Will show where that is shortly ...

Editing templates in XMetaL

Page 6: Fine-tuning the DITA customization

© 2011 JustSystems Inc.

• 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

* PI == XML “processing instruction”

This can be any text you want

<p><?xm-replace_text Paragraph?></p>

The rest must be exactly as shown here

Page 7: Fine-tuning the DITA customization

© 2011 JustSystems Inc.

• 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”

Page 8: Fine-tuning the DITA customization

© 2011 JustSystems Inc.

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 byclicking the button

Page 9: Fine-tuning the DITA customization

© 2011 JustSystems Inc.

• 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 Files\XMetaL 6.0\Author\DITA\XACs\task\task_ditabase.dtd">

• Remove path info and “_ditabase”:<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">

Fixing the DOCTYPE

Page 10: Fine-tuning the DITA customization

© 2011 JustSystems Inc.

Where to save your templates

Replace any/all of these folders with your own

Page 11: Fine-tuning the DITA customization

© 2011 JustSystems Inc.

Where to save your templates

Replace any/all of these files with your own

Page 12: Fine-tuning the DITA customization

© 2011 JustSystems Inc.

CSS file(s) Who “owns”

Purpose Edit?

ditabase-base.cssditabase-derived.css

XMetaL Built-in CSS that is used by all DITA document types

ditabase-base-override.cssditabase-derived-override.css

You Your custom CSS that is used by all DITA document types

mytopic_ditabase-specialized.css You Your custom CSS that pertains to one specific DITA document type (e.g. “concept” or “mytopic”)

2. Editor styles (CSS)

Primary CSS file for each DITA doctype customizationmerely imports five other files:

“Mytopic” can also be concept, task, reference, etc.

Page 13: Fine-tuning the DITA customization

© 2011 JustSystems Inc.

• 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

Page 14: Fine-tuning the DITA customization

© 2011 JustSystems Inc.

• 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.cssmytopic_ditabase-specialized.css

Page 15: Fine-tuning the DITA customization

© 2011 JustSystems Inc.

• 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.cssmytopic_ditabase-specialized.css

Page 16: Fine-tuning the DITA customization

© 2011 JustSystems Inc.

• 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

Page 17: Fine-tuning the DITA customization

© 2011 JustSystems Inc.

• Copy this file (sample code included with XMetaL):C:\Program Files\XMetaL 6.0\Author\DITA\XACs\ditabase

ditabase_ditabase.off.js

• Paste into this directory:C:\Program Files\XMetaL 6.0\Author\DITA\XACs\concept

• 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

Page 18: Fine-tuning the DITA customization

© 2011 JustSystems Inc.

• 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

Page 19: Fine-tuning the DITA customization

© 2011 JustSystems Inc.

• 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!}

Page 20: Fine-tuning the DITA customization

© 2011 JustSystems Inc.

• 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. var hstr = Math.floor(1000000000*Math.random()).toString(16); return domNode.nodeName + "_37mins_" + hstr;}

Page 21: Fine-tuning the DITA customization

© 2011 JustSystems Inc.

• 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

Page 22: Fine-tuning the DITA customization

© 2011 JustSystems Inc.

• 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.}

Page 23: Fine-tuning the DITA customization

© 2011 JustSystems Inc.

• 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") { var str = Application.Prompt("Enter a new ID"); rng.ContainerNode.setAttribute("id", str); return true; }

// ...otherwise, let built-in behavior run return false; }

Page 24: Fine-tuning the DITA customization

© 2011 JustSystems Inc.

• 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

Page 25: Fine-tuning the DITA customization

© 2011 JustSystems Inc.

• 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.}

Page 26: Fine-tuning the DITA customization

© 2011 JustSystems Inc.

• 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; }}

Page 27: Fine-tuning the DITA customization

© 2011 JustSystems Inc.

• 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

Page 28: Fine-tuning the DITA customization

© 2011 JustSystems Inc.

• 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.}

Page 29: Fine-tuning the DITA customization

© 2011 JustSystems Inc.

• 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?

Page 30: Fine-tuning the DITA customization

© 2011 JustSystems Inc.

• 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

Page 31: Fine-tuning the DITA customization

© 2011 JustSystems Inc.

• Thank you for attending!

Q&A