Raise your hand if you've heard this before: Can I drag and drop (or paste) content from somewhere else into XMetaL? The answer is a qualified "yes" -- it can be done, but if the stuff being dropped is not already plain XML, someone has to write some script to make it happen. (That someone is you, the XMetaL customizer.) The stickiest part of the problem is transforming the dropped data into valid XML. But in addition to that, you need to know the mechanics of processing these user actions in XMetaL. In this webinar we will leave aside the "transformation" part of the problem, and focus on the XMetaL APIs for detecting and handling user drop/paste events and inspecting and accessing the user's data from the clipboard.

1. in 37 minutes Episode 20 Dropping content isn’t a drag! Handling drag & drop (& paste) into XMetaL documents Tom Magliery, XML Technology Specialist 7 April 2011 Brought to you by XMetaL Technical Services

2. A common authoring requirement is to allow users to paste or drop content from other applications into XMetaL Via customization (script), you can capture and process content that is being pasted or dropped Note: This talk is for customizers working with non-DITA document types For DITA some of these techniques have already been used to customize XMetaL Introduction

3. Writing script to handle paste and drop events, and access the clipboard contents Transforming the clipboard contents into valid XML for your doctype We are focused solely on part 1 today. Two-part problem

4. When you copy something, the source application puts it on the clipboard in one or more formats When you drag something, it will be available as drop data in the same formats Some formats are defined as standard in Windows (e.g., CF_TEXT, CF_UNICODETEXT) Others are defined by the source application (e.g., Adobe Photoshop Image) Some are used by many applications (e.g., HTML Format) Background info

5. No customization (default XMetaL behavior) Handling dropped/pasted text Handling dropped/pasted other formats Handling dropped files Agenda

6. XMetaL has some simple handling of drop/paste without any script customization Text or files can be dropped/pasted into XMetaL with certain happy results Part 1: No customization required

7. If the clipboard object includes a text format: If the text is valid markup that can be pasted at the current location, then it will be pasted as markup Otherwise the full text will be pasted as text Note: There are some strange “in-between” cases that depend on the context of your paste Example 1: No customization required

8. If the clipboard contains files If any of the file(s) are images, and if your CTM file specifies an image element, then the files that are images will be pasted as image elements Other files are ignored Example 2: No customization required Excerpt from simplepaper.ctm ... <Images> <Image> <Name>Image</Name> <Source-Attribute>href</Source-Attribute> <Height-Attribute>height</Height-Attribute> <Width-Attribute>width</Width-Attribute> </Image> </Images> ...

9. Key event macro: On_Document_Before_DropText Called immediately before the drop/paste is performed Use script in the macro to manipulate the clipboard contents and drop/paste location After this macro finishes, the drop/paste is performed Part 2: Plain text

10. ActiveDocument.DropClipboardText Boolean property, returns true if the action is a paste; false if it is a drop When text is being pasted Application.Clipboard Contains other properties and methods for accessing the clipboard Application.Clipboard.Text The text contents of the clipboard Read/write property Useful APIs in On_Document_Before_DropText

11. When text is being dropped ActiveDocument.DropText The text being dropped Read/write property ActiveDocument.DropPoint A Range object representing the location at which the text is being dropped/pasted Read-only property If a different drop location is desired, use Application.MoveDropPoint(range) More useful APIs in On_Document_Before_DropText

12. Example 3: On_Document_Before_DropText <MACRO name="On_Document_Before_DropText" hide="false" lang="JScript"><![CDATA[ varmsg = "On_Document_Before_DropText"; if (ActiveDocument.DropClipboardText) { msg += "...pasting"; msg += "Clipboard text is:" + Application.Clipboard.Text; msg += "Being pasted inside "; } else { msg += "...dropping"; msg += "Droptext is:" + ActiveDocument.DropText; msg += "Being dropped inside "; } varrng = ActiveDocument.DropPoint; msg += "<" + rng.ContainerName + "> element."; Application.Alert(msg); ]]></MACRO>

13. Example 3: On_Document_Before_DropText Determine whether this is a drop or a paste <MACRO name="On_Document_Before_DropText" hide="false" lang="JScript"><![CDATA[ varmsg = "On_Document_Before_DropText"; if (ActiveDocument.DropClipboardText) { msg += "...pasting"; msg += "Clipboard text is:" + Application.Clipboard.Text; msg += "Being pasted inside "; } else { msg += "...dropping"; msg += "Droptext is:" + ActiveDocument.DropText; msg += "Being dropped inside "; } varrng = ActiveDocument.DropPoint; msg += "<" + rng.ContainerName + "> element."; Application.Alert(msg); ]]></MACRO> If pasting, access the Clipboard text If dropping, access the DropText Find out where the text is being dropped/pasted

14. Suppose there is a clipboard format that you know how to process into markup of your type “Declare” that format type in XMetaL and give it your own name Application.AcceptDropFormat("HTML Format", “MyHTML"); Write an event macro matching your name <MACRO name="On_Drop_MyHTML" hide="true" lang="JScript"> Drop/paste contents are available as a “DataObject” Part 3: Other formats

15. Example 4: Handling “HTML Format” <MACRO name="On_Document_Open_Complete" hide="false" lang="JScript"><![CDATA[ Application.AcceptDropFormat("HTML Format", "MyHTML"); ]]></MACRO>

16. Example 4: Handling “HTML Format” <MACRO name="On_Document_Open_Complete" hide="false" lang="JScript"><![CDATA[ Application.AcceptDropFormat("HTML Format", "MyHTML"); ]]></MACRO> Tells XMetaL to watch out for “HTML Format” and that our internal name is “MyHTML”

17. Example 4 continued: Handling “HTML Format” <MACRO name="On_Drop_MyHTML" hide="false" lang="JScript"><![CDATA[ varmsg = "On_Drop_MyHTML"; if (ActiveDocument.DropDataObject == Application.Clipboard.DataObject) { msg += " ... pasting"; } else { msg += " ... dropping"; } msg += "Content to be pasted/dropped is:"; var data = ActiveDocument.DropDataObject; msg += ActiveDocument.DataObjectAsText("HTML Format", data); Application.Alert(msg); ]]></MACRO>

18. Example 4 continued: Handling “HTML Format” Event macro name matches our internal name “MyHTML” <MACRO name="On_Drop_MyHTML" hide="false" lang="JScript"><![CDATA[ varmsg = "On_Drop_MyHTML"; if (ActiveDocument.DropDataObject == Application.Clipboard.DataObject) { msg += " ... pasting"; } else { msg += " ... dropping"; } msg += "Content to be pasted/dropped is:"; var data = ActiveDocument.DropDataObject; msg += ActiveDocument.DataObjectAsText("HTML Format", data); Application.Alert(msg); ]]></MACRO> How to test whether this is a drop or a paste Get the text version of this HTML content (will include the tags)

19. You can include handlers for as many clipboard formats as you wish Example 5: Handling “Adobe Photoshop Image” <MACRO name="On_Document_Open_Complete" hide="false" lang="JScript"><![CDATA[ Application.AcceptDropFormat("HTML Format", "MyHTML"); Application.AcceptDropFormat("Adobe Photoshop Image", "MyPhotoshop"); ]]></MACRO>

20. You can include handlers for as many clipboard formats as you wish Example 5: Handling “Adobe Photoshop Image” <MACRO name="On_Document_Open_Complete" hide="false" lang="JScript"><![CDATA[ Application.AcceptDropFormat("HTML Format", "MyHTML"); Application.AcceptDropFormat("Adobe Photoshop Image", "MyPhotoshop"); ]]></MACRO> Same idea aswith “HTML Format”

21. Example 5 continued: Handling “Adobe Photoshop Image” <MACRO name="On_Drop_MyPhotoshop" hide="false" lang="JScript"><![CDATA[ Application.Alert("You pasted an image from Photoshop!"); ]]></MACRO>

22. Example 5 continued: Handling “Adobe Photoshop Image” <MACRO name="On_Drop_MyPhotoshop" hide="false" lang="JScript"><![CDATA[ Application.Alert("You pasted an image from Photoshop!"); ]]></MACRO> Not much of a “handler” at all, really :-o

23. Key event macro:On_Drop_Files Called if files are dropped into the editor Replaces built-in behavior (Contrast with On_Document_Before_DropText) Use Application.DropFileCount and Application.DropFileName properties Can get basic drop behavior on individual files with Selection.DropFile Part 4: Dropping files

24. Example 6: Handling dropped files <MACRO name="On_Drop_Files" hide="false" lang="JScript"><![CDATA[ vardp = Application.DropPoint; if (dp.ContainerName == "Para") { for (vari=1; i<=Application.DropFileCount; i++) { Application.Alert(Application.DropFileName(i)); dp.DropFile(Application.DropFileName(i)); } } ]]></MACRO>

25. Example 6: Handling dropped files Just for demo purposes we’ll do something only if we drop into a <Para> Returns a Range which represents the drop location <MACRO name="On_Drop_Files" hide="false" lang="JScript"><![CDATA[ vardp = Application.DropPoint; if (dp.ContainerName == "Para") { for (vari=1; i<=Application.DropFileCount; i++) { Application.Alert(Application.DropFileName(i)); dp.DropFile(Application.DropFileName(i)); } } ]]></MACRO> For each file, display the filename and then do a regular “drop”

26. On_Document_After_DropText Event macro for performing operations after the drop/paste has occurred Application.DropRange Property returns a range that contains the dropped/pasted content On_Drag_Over_MyFormatName Event macro that fires while dragging content that matches a particular format ActiveDocument.DropNotAllowed(); Sets the “drop not allowed” cursor (use after inspecting DropPoint during drag-over) Handling DropFiles in the workspace (i.e., not in a document) Further reading

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

28. Thank you for attending! Q&A