Taking Advantage of XMetaL’s XInclude Support

in 37 minutesin 37 minutes

Episode 4Taking advantage ofTaking advantage of

XMetaL’s XInclude support

Tom Magliery, XML Technology Specialist

© 2010 JustSystems Inc.© 2010 JustSystems Inc.Brought to you by XMetaL Technical Services

AnnouncementsAnnouncements

• Next time: Su-Laine “XMetaL for Simple XML Editing”Editing

© 2010 JustSystems Inc.

AgendaAgenda

• IntroductionB i XI l d k• Basic XInclude markup

• XMetaL XInclude APIs

© 2010 JustSystems Inc.

What is XIncludeWhat is XInclude

• W3C XML standardG l i l i h i• General purpose inclusion mechanism

• Including XML inside other XML• A general way to achieve content reuse

© 2010 JustSystems Inc.

XMetaL’s XInclude supportXMetaL’s XInclude support

• XMetaL automatically recognizes XInclude markupmarkup

• XMetaL XInclude APIs allow customizers to add reuse functionality to document customizationsreuse functionality to document customizations

© 2010 JustSystems Inc.

Getting startedGetting started

• Step 1: Define XInclude elements in your DTD/schemaDTD/schema

St 2 P t XI l d k i i t• Step 2: Put XInclude markup in your instance document

• Step 3: See what happens in XMetaL• ...

© 2010 JustSystems Inc.

STEP 1: STEP 1: XINCLUDEXINCLUDE IN YOUR IN YOUR DTD OR SCHEMADTD OR SCHEMADTD OR SCHEMADTD OR SCHEMA

© 2010 JustSystems Inc.

XInclude specifies two new elementsXInclude specifies two new elements

• <xi:include>Pl h ld f f d t t– Placeholder for referenced content

– Pointer to referenced content– Put wherever you want to be able to include things– Put wherever you want to be able to include things

• <xi:fallback>– Content to be displayed if XInclude resolution failsContent to be displayed if XInclude resolution fails

© 2010 JustSystems Inc.

Example DTD with XIncludeExample DTD with XInclude<?xml version="1.0" encoding="UTF-8"?><!-- "-//Mag//DTD Simple Paper//EN" --><!ELEMENT Paper (Title, Author, (Section | xi:include)*) >p ( , , ( | ) )<!ELEMENT Title (#PCDATA) ><!ELEMENT Author (#PCDATA) ><!ELEMENT Section (Title, (Para | Blockquote | xi:include)*) ><!ELEMENT Para (#PCDATA | Bold | Italic)* ><!ELEMENT Blockquote (#PCDATA | Bold | Italic)* ><!ELEMENT Bold (#PCDATA) ><!ELEMENT Italic (#PCDATA) >

<!ELEMENT xi:include (xi:fallback?)><!ATTLIST xi:include

xmlns:xi CDATA #FIXED "http://www w3 org/2001/XInclude"xmlns:xi CDATA #FIXED http://www.w3.org/2001/XIncludehref CDATA #IMPLIEDparse (xml|text) "xml"xpointer CDATA #IMPLIEDencoding CDATA #IMPLIEDaccept CDATA #IMPLIEDpaccept-language CDATA #IMPLIED

>

<!ELEMENT xi:fallback (#PCDATA|Para)*><!ATTLIST xi:fallback

l i # h // 3 /2001/ l d

© 2010 JustSystems Inc.

xmlns:xi CDATA #FIXED "http://www.w3.org/2001/XInclude">

STEP 2: XINCLUDE IN YOUR STEP 2: XINCLUDE IN YOUR DOCUMENT MARKUPDOCUMENT MARKUPDOCUMENT MARKUPDOCUMENT MARKUP

© 2010 JustSystems Inc.

XInclude markupXInclude markup

i i l d h f " th l"<xi:include href="my_other_paper.xml"xpointer="xpointer(/Paper/Section)"><xi:fallback>This is fallback text.</xi:fallback>

</xi:include>/

© 2010 JustSystems Inc.

Sample documentSample document

<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE Paper PUBLIC "-//Mag//DTD Simple Paper//EN" "simplepaper.dtd"><Paper><Title>This is my Paper</Title><Author>John Q. Public</Author><Section>

<Title>First section</Title><Para>First paragraph.</Para><Para>Second paragraph.</Para>

</Section><xi:include href="my_other_paper.xml"

xpointer="xpointer(/Paper/Section[1])"><xi:fallback>This is fallback text.</xi:fallback></xi:include></Paper>

© 2010 JustSystems Inc.

STEP 3: SEE WHAT HAPPENS STEP 3: SEE WHAT HAPPENS ININ XMETALXMETALIN IN XMETALXMETAL

© 2010 JustSystems Inc.

STEP 4: DO STUFF WITH STEP 4: DO STUFF WITH SCRIPTSCRIPTSCRIPTSCRIPT

© 2010 JustSystems Inc.

Implementing XML inclusionsImplementing XML inclusions

• XMetaL automatically recognizes XInclude markupmarkup

• But there is no built-in user interfaceTh API• There are new APIs– XInclude-related methods/properties on Document

and Application objectsand Application objects• Write script using APIs to implement desired

functionalityy

© 2010 JustSystems Inc.

Bonus tip: Pasting scriptBonus tip: Pasting script

• (Not related to XML inclusions)C t t bl i t d i t th• Can paste executable script code into the XMetaL main document windowR i ifi i t h d li• Requires specific script header line:

//XMetaL Script Language JScript://XMetaL Script Language JScript:ActiveDocument.Host.Alert("Hello, world");

© 2010 JustSystems Inc.

ShowXIncludeShowXInclude(node)(node)

• Document object methodIf d i XI l d th t t i di l d• If node is an XInclude, the target is displayed

• Else, if node has XInclude ancestor(s), the t i di l dnearest one is displayed

• Else, if node has XInclude descendants, they are all displayedare all displayed– ShowXInclude(ActiveDocument.documentElement)

will show all inclusions in the documents o a c us o s e docu e• NOTE: An XInclude must be updated at least

once before it can be displayed

© 2010 JustSystems Inc.

p y

UpdateXIncludeUpdateXInclude(node)(node)

• Document object methodS l b t hi h d ( ) ff t d• Same rules about which node(s) are affected

• Causes a “refresh” of the affected node(s)• Does not change visibility of the included

content

© 2010 JustSystems Inc.

HideXIncludeHideXInclude(node)(node)

• Document object methodS l b t hi h d ( ) ff t d• Same rules about which node(s) are affected

• Hides the target content of affected nodes• Display reverts to fallback content

© 2010 JustSystems Inc.

OpenXIncludeTargetOpenXIncludeTarget(node)(node)

• Document object methodIf d i XI l d th t t• If node is an XInclude, opens the target document (specified in href)El if d h XI l d t ( )• Else, if node has XInclude ancestor(s), opens the target document of the nearest one

© 2010 JustSystems Inc.

Some other interesting APIsSome other interesting APIs

• ExportWithXIncludesToFile(strFile)E tWithXI l d T XML()• ExportWithXIncludesToXML()– Returns an XML stringLi kR l ti E Li t• LinkResolutionErrorList– Property, returns ValidationErrorList object

• ResultsManager object• ResultsManager object– Application.ResultsManager.ShowLinkLogTab()

Application ResultsManager HideLinkLogTab()– Application.ResultsManager.HideLinkLogTab()

© 2010 JustSystems Inc.

DocumentationDocumentation

• Full documentation on the XML inclusion APIs is in XMetaL Developer 6 0 docsin XMetaL Developer 6.0 docs

© 2010 JustSystems Inc.

Some possible functionalitySome possible functionality

• Menu commands:I t XML i l i– Insert XML inclusions

– Show or hide all inclusions• Context menu commands:• Context menu commands:

– Hide or show one XML inclusion– Open XML inclusion targetOpen XML inclusion target

• Other– Combine with “Treat as link” AI buttonCombine with Treat as link AI button– Custom dialogs

© 2010 JustSystems Inc.

DocBook sampleDocBook sample

• Included* with XMetaL 6.0Ill t t l XI l d f t• Illustrates several XInclude features

• (DEMO)

© 2010 JustSystems Inc.* No pun intended

ResourcesResources

• XMetaL Community Forumshtt //f t l /– http://forums.xmetal.com/

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

• Ask us for help (partner tech support)partnersupport na@justsystems com– partnersupport-na@justsystems.com

© 2010 JustSystems Inc.