XMetaL Macros for Non-Programmers

© 2010 JustSystems Inc.© 2010 JustSystems Inc.
in 37 minutes
Episode 15
XMetaL Macros
for Non-Programmers
Brought to you by XMetaL Technical Services
Tom Magliery, XML Technology Specialist

© 2010 JustSystems Inc.
• Announcements
• Introduction and your first macro
• How to run a macro (5 ways)
• Customizing the toolbar
• User and event macros
• Application and document macros
• Notes for DITA users
• Temptations
• Summary
• Resources
• Q&A
Agenda
This slide makes me hungry for Skyline Chili. Bonus points if you know why.

• Two new articles by our colleague Su-Laine:
– Information Today (how businesses can learn about
collaboration from Wikipedia):
http://www.infotoday.com/it/nov10/index.shtml
– CIDM Best Practices newsletter (localization in DITA):
http://www.infomanagementcenter.com/index.php?page=1419
• Best wishes to Dave from marketing as he
moves on today. The paddling feet below our
webinars’ waterline will never be the same.
Announcements

• XMetaL macro:
– A blob of script code that can be executed by XMetaL
– A way to extend the functionality of XMetaL
• MCR files aka macro files:
– XMetaL customization files that contain XMetaL
macros
Introduction to XMetaL macros
Sure, “blob” is a technical term.

Your first macro: “Hello, world”
DEMO_HelloWorld.mcr
An MCR file is actually an XML file.
Since script code often contains some of
the five reserved XML characters: < > &
' ", it is wrapped in a CDATA section,
which tells XML parsers not to treat
these characters as markup.
Source code already on Slide 3? You said “non-programmers”! Yes. Trust me ...

DEMO_HelloWorld.mcr
This is the name that XMetaL will use in the
Macros toolbar, dialog, and other places.

DEMO_HelloWorld.mcr
This tells XMetaL what scripting language
this macro uses.

DEMO_HelloWorld.mcr
This is the script code to be executed
whenever this macro is run.

1. Create an MCR file with a macro
DEMO_HelloWorld.mcr
2. Put the MCR file in the “Startup” folder
C:Program FilesXMetaL 6.0AuthorStartUp
3. Restart XMetaL
4. Run the macro
– How?
Adding your macro to XMetaL

• Option 1: Run from the Macros dialog
How to run your macro

• Option 2: Run from the Macros toolbar
– Select a macro, then click the “Run” button
New personal best: Most annoying thing I’ve ever put on a PowerPoint slide.
Run
1
2

• Option 3: Use a shortcut key
– TIP: You can edit MCR files in XMetaL (also in any
text editor). Then you need to refresh/reload the
macros for macro changes to take effect.
DEMO_HelloWorld.mcr

• Option 4: Add a custom menu or toolbar item
– But first, let’s see a more useful macro

Macro #2: Word Count
DEMO_WordCount.mcr
I can tell you how this script code works later, if we have time. It’s not perfect.

• You can put more
than one macro in
a single MCR file
• It looks something
like this
TIP: Multiple macros per file
ManyMacrosInOneFile.mcr
For ease-of-demo reasons, I’m not doing that today.

• Now back to Option 4: Add a custom menu or
toolbar item
Start with a
right-click in
the toolbars
1
Select “Customize...”
2

toolbar item
Click “New...”
3
Name your toolbar4

toolbar item
Select the
Buttons tab
5
Select
“Application
Macros”
6
Select your
macro
7
Choose an
icon for your
macro8

toolbar item
Drag the
icon to the
toolbar9

• Important notes:
– When adding toolbar buttons for application macros,
close all documents first
– Customizing the toolbars (or menus) manually is fine
for “simple” situations, but for more complex
customization it is better to manipulate them with
script (more script!)
• Advanced topics:
– Saving/sharing your toolbar settings
– Where XMetaL “hides” TBR files
• Toolbar cache & per-user folder
– Customizing menus/toolbars with script
Customizing toolbars

• Option 5: Add to the context (right-click) menu
– But first, we need to learn about event macros

• Our examples so far are user macros
– XMetaL runs one whenever you request it
• XMetaL also supports event macros
– XMetaL runs them automatically when system events
occur
– The magic is in the name of the macro
– “On_” prefix indicates that it is an event macro
– XMetaL recognizes certain event names
– You can have multiple event macros with the same
name – in most cases they will all be run. (With user
macros, only one will run.)
User vs. event macros

– Whenever we open any document, this macro will
display some information about that file
Macro #3: When a document is opened
DEMO_OnDocOpenComplete.mcr

– Use this to hide event macros from the Macros
toolbar and dialog
TIP: Hiding a macro
DEMO_OnDocOpenComplete.mcr

• Now back to Option 5*: Add it to the context
(right-click) menu
– Note: This is a simplified example; maybe not “best
practice” but it will work for the demo
– “Best practice” is another advanced topic
*Finally!!
DEMO_ContextMenu.mcr

• Our examples so far are application macros
– Loaded at application startup
– Available no matter what type of document you are
working in (DITA, DocBook, ...)
– Also must be coded to handle any document type
• Can’t have script that relies on specific element names
• XMetaL also supports document macros
– MCR file is named “YourDTDName.mcr” and (usually)
lives with other YourDTDName files (CSS, CTM, etc.)
– Loaded the first time a document is opened
– Available only if the active document is that type
Application vs. document macros
DTD name or schema name, of course.

– TIP: You can run macros from other macros. (Need to
be sure they have been loaded first.)
Example: Add macros to Journalist
partial code, paste this into journalist.mcr

• Most of the DITA features in XMetaL are macros –
mostly document macros
– E.g. adding a conref is a macro that launches the (custom-
built) dialogs that let you browse for the target, then inserts
the conref attribute
• Script is far more complex than today’s examples
• Adding simple application macros to XMetaL will
usually work with DITA
– All of today’s samples work fine
• Adding document macros for DITA to XMetaL is “not
allowed”
– There are a few exceptions: special “hooks”
– This is an advanced topic for sure!
Some notes for DITA users

• Adding custom dialogs and wizards
• Transforming legacy content
• Importing data from databases
• Processing/analyzing content
• Working with ActiveX objects
• Handling drag-and-drop from other apps
• Improving authors’ user experience
• Automatically navigating through documents
• Generating content, e.g., TOC or index
• Capturing and pre-processing user input
• Hiding parts of the XMetaL UI
• Providing shortcuts for repetitive operations
• Adding custom UI to the Resource Manager
Temptations

• Macros ...
– are blobs of executable script code
– can be user-invoked (many ways) or event-based
– can be application-wide or document-type-specific
– can run other macros
– can do lots of different things
• XMetaL APIs – your subconscious has seen six:
– Application.Alert(), Application.AppendMacro(),
Application.Run(), ActiveDocument.FullName,
ActiveDocument.Xml, Application.MessageBox()
• There are over 1200 properties and methods!
Summary: what have we learned?

• Customization Guide:
– General guide to customizing XMetaL
– Some topics assume you are using XMetaL
Developer (Visual Studio)
• We’ve been “hand-editing” today, which is fine
• Programmer’s Guide:
– Complete reference guide to the XMetaL API
• Both are available here (PDF and WebHelp):
http://na.justsystems.com/content-support-user-guides
XMetaL developer resources

• XMetaL Community Forums
– http://forums.xmetal.com/
• JustSystems Partner Center
– http://justpartnercenter.com/
• Ask us for help (customer support)
– supportxmetal@justsystems.com
• Ask us for help (partner tech support)
– partnersupport-na@justsystems.com
Resources

XMetaL Macros for Non-Programmers

More Related Content

What's hot (20)

Similar to XMetaL Macros for Non-Programmers (20)

More from XMetaL (11)

Recently uploaded (20)

XMetaL Macros for Non-Programmers