1. in 37 minutes XMetaL Dialog Programming Odds & Ends Murray Smith, Director of Technical Services Brought to you by XMetaL Technical Services

2. Announcements Next time: Derek Read will talk about DITA Open Toolkit Deployment with XMetaL Author Enterprise 6.0

3. Introduction to XMetaL Dialogs Displaying your dialog from a menu button, Built-in XMetaL dialogs, Building a custom dialog, Passing objects from your macro code to the dialog, Options for where your dialog code will live. Agenda

4. Displaying Your Dialog From a Menu Button Step 1 The OnAction property of the menu button is associated with an XMetaL Macro. exampleMenu = Application.CommandBars.item( "Menu bar" ).Controls.Add(MENU_BUTTON_TYPE, null); exampleMenu.Caption = 'Example 1'; var example1Menu = exampleMenu.Controls.Add(sqcbcTypePopup); example1Menu.Caption = 'Run Example 1'; example1Menu.FaceId = 0; example1Menu.DescriptionText = 'Display Ex. 1 Dialog.'; example1Menu.OnAction = "ShowExample1Dialog";

5. Displaying Your Dialog From a Menu Button Step 2 The XMetaL macro associated with the menu button will create the dialog and display it by calling it’s DoModal() method. <MACRO name="ShowExample1Dialog" hide="true" lang="JScript"> <![CDATA[ // XMetaL Script Language JSCRIPT: var XMetaLPath = Application.Path; var xftPath = XMetaLPath + "XFTExample1.xft"; var dlg=Application.CreateFormDlg( xftPath ); dlg.DoModal(); dlg=null; ]]> </MACRO>

6. Built-in XMetaL Dialogs XMetaL Author supports a number of built-in dialogs. Alert: displays a message, with an ok button. Prompt: displays a message, and a text field for input. Confirm: displays a message, and ok & cancel buttons. NoticeBox: displays a message, and up to 3 buttons. MessageBox: Displays a message, a variety of buttons, and a variety of icons. Buttons: Ok, Ok/Cancel, Abort/Retry/Ignore, Yes/No, Yes/No/Cancel, Retry/Cancel. Icons: Critical, Warning Query, Warning Message, Info Message.

7. Built-in Dialogs – cont. The built-in dialogs are very easy to use. Example display an Alert: Application.Alert( "This is my message." ); Example display a NoticeBox: var response = Application.NoticeBox( "What is your favorite fruit?", "Apple", "Orange", "I don't like fruit." ); if( response == 1 ){ Application.Alert( "You like apples." ); } else if( response == 2 ){ Application.Alert( "You like oranges." ); } else{ Application.Alert( "You don't like fruit?" ); }

8. Building Custom Dialogs Custom dialogs are built in the XMetaL Form Layout Tool (XFLayout) which is part of the XMetaL Developer product.

9. Building Custom Dialogs – cont. After adding the dialog controls by dragging and dropping them on the form using the layout tool, you can add behavior to the controls by adding code to the desired event.

10. Passing Objects to Your Dialog This is simple. The script to create your dialog and display it is just slightly different from the approach we saw in example 1. var listEntries = new Array( "I don't like fruit", "Apple", "Orange", "Peach", "Pineapple" ); var returnVal = new Object(); returnVal.response = 0; var xftPath = Application.Path + "XFTExample4.xft"; var xft = new ActiveXObject("XF.XFTForm"); xft.AddTopLevelObject( "fruitOptions", listEntries ); xft.AddTopLevelObject( "returnVal", returnVal ); xft.AddTopLevelObject( "Application", Application ); var dlg = xft.StartForm( xftPath, 0 ); if( dlg.DoModal() == 1 ) { Application.Alert( "You said: " + listEntries[returnVal.response] ); } dlg = null; xft = null; listEntries = null;

11. Passing Objects to Your Dialog – cont. In the script code inside your dialog, you access the object using the name given to it when calling AddTopLevelObject(). xft.AddTopLevelObject( "fruitOptions", listEntries ); xft.AddTopLevelObject( "returnVal", returnVal ); xft.AddTopLevelObject( "Application", Application );

12. Passing Objects to Your Dialog – cont. Note: When using this approach to create your dialog, you need to explicitly pass the Application object to the dialog in order to be able to access it from your dialog code. xft.AddTopLevelObject( "Application", Application );

13. Options for Where Your Dialog Code Will Live Given that we can pass JavaScript objects to the dialog, the next logical question is whether we could pass a JavaScript object that implements the dialog behavior. Event scripts in the XFT call methods on the JavaScript object

14. Options for Where Your Dialog Code Will Live – cont. Advantages Script code is more easily viewed. (In the XFLayout tool you can only view the code for one event macro at a time.) Since the JavaScript object is instantiated in XMetaL Author’s script engine, you have access to the script debugger in your code by adding a “debugger;” statement. Further if you pass XFT controls into those methods, you can view the property values for those controls at run time. (Whereas, if the code is all in the XFT you will need to use Alerts to be able to view the property values.)

15. Summary We’ve looked at some introductory topics related to dialogs in XMetaL Author. Launching a dialog from a menu item, The built-in dialogs in XMetaL Author, Creating a custom dialog. Then we built on that to look at some more advanced topics. Passing JavaScript objects to you dialog, An interesting approach to structuring your dialog script code.

16. Thank you for attending! Q&A