Displaying additional image types in XMetaL

in 37 minutesEpisode 22Viewing the unviewable: Displaying additional image types in XMetaL Using the InPlaceControl interface to add custom viewer controlsTom Magliery, XML Technology Specialist12 May 2011Brought to you by XMetaL Technical Services

XMetaL can display images in several common graphics formats (full list in Help)For non-supported formats, XMetaL can use an ActiveX viewer control to display the imagesYou have to supply the viewerYou have to do some script customizationPurpose of today: show you how to do the script customizationIntroduction

CTM file <OCXReplacement>Associates an ActiveX viewer control with an elementEvent macros_OnShouldCreate, _OnInitialize, _OnFocus, _OnSynchronizeInPlaceControl interfaceApplication.ActiveInPlaceControl gives access to the viewer control during these eventsKeys to this customization

Have an XML element solely dedicated to the special image type: <Visio_Image>Always use viewer control to display this elementNeed two bits of code:<OCXReplacement> in CTM file_OnInitialize macroExample 1

<OCXReplacement><OCXReplacements> is an optional main element in the CTM file – like <ElementPropertiesList>, <Templates>, etc.Name of your image elementPrefix to be used with event macros (can be whatever you want provided the resulting macro name is valid)...<OCXReplacements> <OCXReplacement> <SelectorName>Visio_Image</SelectorName> <MacroPrefix>VisioViewer</MacroPrefix> <ProgID>VisioViewer.Viewer</ProgID> </OCXReplacement></OCXReplacements>...ProgID of your ActiveX viewer control

_OnInitialize macroThis macro is executed for each <Visio_Image> element in the document.ActiveInPlaceControl object exists for the duration of this macro.Name prefix matches what was in the CTM file.Sets the size for the control.<MACRO name="VisioViewer_OnInitialize" hide="true" lang="JScript"><![CDATA[ varaipc = Application.ActiveInPlaceControl;aipc.Width = 500; aipc.Height = 300;var filename = aipc.Node.getAttribute("href");aipc.Control.SRC = filename;]]></MACRO>Node is the element being displayed with this control.Control property gives you access to the IDispatch interface of the viewer control. SRC is a property of the Visio Viewer control.Can also perform other initializations here using the control’s interface, via aipc.Control.*.

Use the same image element for built-in and a special image formatUse viewer control for special image type<Dual_Purpose_Imagehref=“myVisioDiagram.vsd”/>Fall back to default XMetaL behavior otherwise<Dual_Purpose_Imagehref=“myJPG.jpg”/>Need same code bits as before, plus:<Image> in CTM file_OnShouldCreate macroExample 2

Same stuff from before<OCXReplacement> in the CTM – different element name, different macro prefix...<OCXReplacements> <OCXReplacement> <SelectorName>Dual_Purpose_Image</SelectorName> <MacroPrefix>VV2</MacroPrefix> <ProgID>VisioViewer.Viewer</ProgID> </OCXReplacement></OCXReplacements>..._OnInitialize macro does the same thing as before – it’s using the same viewer control<MACRO name="VV2_OnInitialize" hide="true" lang="JScript"><![CDATA[ varaipc = Application.ActiveInPlaceControl;aipc.Width = 500; aipc.Height = 300;var filename = aipc.Node.getAttribute("href");aipc.Control.SRC = filename;]]></MACRO>

<Image>Handles the fall-back case of built-in image formats. <Dual_Purpose_Image> is designated as an image element in the CTM....<Image> <Name>Dual_Purpose_Image</Name> <Source-Attribute>href</Source-Attribute> <Height-Attribute>height</Height-Attribute> <Width-Attribute>width</Width-Attribute> <AltText-Attribute>alt</AltText-Attribute></Image>...

_OnShouldCreateUse business logic to determine whether XMetaL should be displaying this element in the viewer control in this instance; store the outcome in the ShouldCreate property.Get the href attribute from the element to which this control is (tentatively) attached<MACRO name="VV2_OnShouldCreate" hide="true" lang="JScript"><![CDATA[varaipc = Application.ActiveInPlaceControl;varhref = aipc.Node.getAttribute("href");vari = href.lastIndexOf(".vsd"); if (i != -1) {aipc.ShouldCreate = true; } else {aipc.ShouldCreate = false; }]]></MACRO> Look at the file extension to see if this is a Visio fileSet the ShouldCreate property accordingly

Using _OnFocus event to manipulate the viewer controlOur Visio viewer has APIs for turning on/off various features of the controlSuppose we want toolbar, scrollbars, etc. only when the control has focusExample 3

_OnFocusThis macro is executed both on focus and on blur – when the user clicks in or out of the viewer control.UserMovedIntoControl property is true on “focus” and false on “blur”<MACRO name="VisioViewer_OnFocus" hide="true" lang="JScript"><![CDATA[varaipc = Application.ActiveInPlaceControl;aipc.Control.AlertsEnabled = aipc.UserMovedIntoControl;aipc.Control.ScrollbarsVisible = aipc.UserMovedIntoControl;aipc.Control.ToolbarVisible = aipc.UserMovedIntoControl;aipc.Control.PageVisible = aipc.UserMovedIntoControl;]]></MACRO>

Using _OnSynchronize event to update the document and/or the controlUseful when you need to update data in the viewer control because of changes in the document – or vice versaBizarre hypothetical example: Suppose we have an element in our document that we wish to reflect the current “zoom” level of the Visio controlExample 4

_OnSynchronizeMacro is executed whenever the document changes and whenever focus leaves the viewer control.UpdateFromDocument=true if the control may need updating because the document state has changed; false if it’s the other way around.This is our bizarre “zoom” data element<MACRO name="VisioViewer_OnSynchronize" hide="true" lang="JScript"><![CDATA[varaipc = Application.ActiveInPlaceControl;varndlist = aipc.Document.GetElementsByTagName("Author"); if (!aipc.UpdateFromDocument) {var zoom = aipc.Control.Zoom;ndlist.item(0).firstChild.nodeValue = zoom; } else {var value = ndlist.item(0).firstChild.nodeValue;aipc.Control.Zoom = value; }]]></MACRO>Set document data based on the controlSet control data based on the document

If your viewer control API includes events, you can write script in XMetaL to handle the eventsIf your viewer has an event called “SomeEvent”, you can write a macro like this:When the viewer fires the event, XMetaL will execute this macroActiveInPlaceControl.NextEventParam property allows you to access the arguments of the eventUnfortunately no example to show today :-((Non)-example:Events in the viewer control<MACRO name="VisioViewer_SomeEvent" hide="true" lang="JScript"><![CDATA[ // In here you do whatever you need to handle this event]]></MACRO>

If you require more than one viewer control, and if all the image types use the same <Image> element, some additional scripting is requiredCTM file can only have one <OCXReplacement> for each DTD elementBut you can define additional OCXReplacements dynamically in scriptRelevant APIs:DOMDocumentType.addInPlaceControl()InPlaceControl.userDataA little too much for an example here today!(Non)-example:More than one custom viewer

XMetaL DITA customization uses this technique – recursively! – to display SVG graphicsXMetaL’s viewer control is Internet ExplorerIE (through 8) does not natively support SVG either – requires you to install a pluginSo XMetaL hands the image over to IE, which in turn hands it over to your SVG pluginSVG in DITA in XMetaL

XMetaL Community Forumshttp://forums.xmetal.com/JustSystems Partner Centerhttp://justpartnercenter.com/Ask us for help (partner tech support)partnersupport-na@justsystems.comResources

Displaying additional image types in XMetaL

More Related Content

What's hot (20)

Similar to Displaying additional image types in XMetaL (20)

Displaying additional image types in XMetaL