dropping content isn't a drag!

© 2011 JustSystems Inc.© 2011 JustSystems Inc.

in 37 minutes

Episode 20

Dropping content isn’t a drag!Handling drag & drop (& paste)

into XMetaL documents

Brought to you by XMetaL Technical Services

Tom Magliery, XML Technology Specialist

7 April 2011

© 2011 JustSystems Inc.

• 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


1. Writing script to handle paste and drop events, and access the clipboard contents

2. Transforming the clipboard contents into valid XML for your doctype

• We are focused solely on part 1 today.

Two-part problem


• 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


1. No customization (default XMetaL behavior)

2. Handling dropped/pasted text

3. Handling dropped/pasted other formats

4. Handling dropped files

Agenda


• 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


• 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


• 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

...<Images> <Image> <Name>Image</Name> <Source-Attribute>href</Source-Attribute> <Height-Attribute>height</Height-Attribute> <Width-Attribute>width</Width-Attribute> </Image></Images>...

Excerpt from simplepaper.ctm


• 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


• 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


• 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


Example 3: On_Document_Before_DropText

<MACRO name="On_Document_Before_DropText" hide="false" lang="JScript"><![CDATA[var msg = "On_Document_Before_DropText";if (ActiveDocument.DropClipboardText){

msg += "...pasting";msg += "\n\nClipboard text is:\n\n" + Application.Clipboard.Text;msg += "\n\nBeing pasted inside ";

}else{

msg += "...dropping";msg += "\n\nDroptext is:\n\n" + ActiveDocument.DropText;msg += "\n\nBeing dropped inside ";

}var rng = ActiveDocument.DropPoint;msg += "<" + rng.ContainerName + "> element.";Application.Alert(msg);]]></MACRO>


Example 3: On_Document_Before_DropText

<MACRO name="On_Document_Before_DropText" hide="false" lang="JScript"><![CDATA[var msg = "On_Document_Before_DropText";if (ActiveDocument.DropClipboardText){

msg += "...pasting";msg += "\n\nClipboard text is:\n\n" + Application.Clipboard.Text;msg += "\n\nBeing pasted inside ";

}else{

msg += "...dropping";msg += "\n\nDroptext is:\n\n" + ActiveDocument.DropText;msg += "\n\nBeing dropped inside ";

}var rng = ActiveDocument.DropPoint;msg += "<" + rng.ContainerName + "> element.";Application.Alert(msg);]]></MACRO>

Determine whether this is a drop or a paste

If pasting, access the Clipboard text

If dropping, access the DropText

Find out where the text is being dropped/pasted


• Suppose there is a clipboard format that you know how to process into markup of your type

1. “Declare” that format type in XMetaL and give it your own name– Application.AcceptDropFormat("HTML Format",

“MyHTML");

2. 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


Example 4: Handling “HTML Format”

<MACRO name="On_Document_Open_Complete" hide="false" lang="JScript"><![CDATA[

Application.AcceptDropFormat("HTML Format", "MyHTML");

]]></MACRO>


Example 4: Handling “HTML Format”


Application.AcceptDropFormat("HTML Format", "MyHTML");

]]></MACRO>

Tells XMetaL to watch out for “HTML Format” and that our internal name is “MyHTML”


Example 4 continued: Handling “HTML Format”

<MACRO name="On_Drop_MyHTML" hide="false" lang="JScript"><![CDATA[var msg = "On_Drop_MyHTML";if (ActiveDocument.DropDataObject == Application.Clipboard.DataObject){

msg += " ... pasting";}else{

msg += " ... dropping";}msg += "\n\nContent to be pasted/dropped is:\n\n";var data = ActiveDocument.DropDataObject;msg += ActiveDocument.DataObjectAsText("HTML Format", data);Application.Alert(msg);]]></MACRO>


Example 4 continued: Handling “HTML Format”

<MACRO name="On_Drop_MyHTML" hide="false" lang="JScript"><![CDATA[var msg = "On_Drop_MyHTML";if (ActiveDocument.DropDataObject == Application.Clipboard.DataObject){

msg += " ... pasting";}else{

msg += " ... dropping";}msg += "\n\nContent to be pasted/dropped is:\n\n";var data = ActiveDocument.DropDataObject;msg += ActiveDocument.DataObjectAsText("HTML Format", data);Application.Alert(msg);]]></MACRO>

Event macro name matches our internal name “MyHTML”

How to test whether this is a drop or a paste

Get the text version of this HTML content (will include the tags)


• You can include handlers for as many clipboard formats as you wish

Example 5: Handling “Adobe Photoshop Image”


Application.AcceptDropFormat("HTML Format", "MyHTML"); Application.AcceptDropFormat("Adobe Photoshop Image", "MyPhotoshop");

]]></MACRO>


• You can include handlers for as many clipboard formats as you wish

Example 5: Handling “Adobe Photoshop Image”


Application.AcceptDropFormat("HTML Format", "MyHTML"); Application.AcceptDropFormat("Adobe Photoshop Image", "MyPhotoshop");

]]></MACRO>

Same idea aswith “HTML Format”


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>


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


• 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


Example 6: Handling dropped files

<MACRO name="On_Drop_Files" hide="false" lang="JScript"><![CDATA[var dp = Application.DropPoint;if (dp.ContainerName == "Para") {

for (var i=1; i<=Application.DropFileCount; i++) {Application.Alert(Application.DropFileName(i));dp.DropFile(Application.DropFileName(i));

}}]]></MACRO>


Example 6: Handling dropped files

<MACRO name="On_Drop_Files" hide="false" lang="JScript"><![CDATA[var dp = Application.DropPoint;if (dp.ContainerName == "Para") {

for (var i=1; i<=Application.DropFileCount; i++) {Application.Alert(Application.DropFileName(i));dp.DropFile(Application.DropFileName(i));

}}]]></MACRO>

Returns a Range which represents the drop location

Just for demo purposes we’ll do something only if we drop into a <Para>

For each file, display the filename and then do a regular “drop”


• 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


• XMetaL Community Forums– http://forums.xmetal.com/

• JustSystems Partner Center– http://justpartnercenter.com/

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

Resources


• Thank you for attending!

Q&A

dropping content isn't a drag!

Documents