xmetal macros for non-programmers

© 2010 JustSystems Inc.© 2010 JustSystems Inc.

in 37 minutes

Episode 15

XMetaL Macrosfor 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

http://www.infotoday.com/it/nov10/index.shtml

http://www.infomanagementcenter.com/index.php?page=1419


• 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.mcrThis is the name that XMetaL will use in the Macros toolbar, dialog, and other places.




DEMO_HelloWorld.mcrThis 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 macroDEMO_HelloWorld.mcr

2. Put the MCR file in the “Startup” folderC:\Program Files\XMetaL 6.0\Author\StartUp\

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




Click “New...”

3

Name your toolbar4




Select the Buttons tab5

Select “Application

Macros”

6Select your

macro

7

Choose an icon for your

macro8




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)– [email protected]

• Ask us for help (partner tech support)– [email protected]

Resources

xmetal macros for non-programmers

Technology

macro files

macro changes

macros toolbar

run button

macro new personal best

xmetal macrosintroduction

xmetal macrossure

xmetal macrosfor