Taking Advantage of XMetaL’s XInclude Support

in 37 minutes

Episode 4
Taking advantage of
XMetaL’s XInclude support

Tom Magliery, XML Technology Specialist

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

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

© 2010 JustSystems Inc.

Agenda
• Introduction
• B i XI l d markup
Basic XInclude k
• XMetaL XInclude APIs


What is XInclude
• W3C XML standard
• General purpose inclusion mechanism
G l i l i h i
• Including XML inside other XML
• A general way to achieve content reuse


XMetaL’s XInclude support
• XMetaL automatically recognizes XInclude
markup
• XMetaL XInclude APIs allow customizers to add
reuse functionality to document customizations


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

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

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


STEP 1: XINCLUDE IN YOUR
DTD OR SCHEMA


XInclude specifies two new elements
• <xi:include>
– Pl
Placeholder f referenced content
h ld for f d t t
– Pointer to referenced content
– Put wherever you want to be able to include things
• <xi:fallback>
– Content to be displayed if XInclude resolution fails


Example DTD with XInclude
<?xml version="1.0" encoding="UTF-8"?>

<!ELEMENT Paper (
p (Title, Author, (
, , (Section | xi:include)*) >
) )
<!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"
http://www.w3.org/2001/XInclude
href CDATA #IMPLIED
parse (xml|text) "xml"
xpointer CDATA #IMPLIED
encoding CDATA #IMPLIED
accept
p CDATA #IMPLIED
accept-language CDATA #IMPLIED
>

<!ELEMENT xi:fallback (#PCDATA|Para)*>
<!ATTLIST xi:fallback
xmlns:xi
l i CDATA #
#FIXED "http://www.w3.org/2001/XInclude"
h // 3 /2001/ l d
>

STEP 2: XINCLUDE IN YOUR
DOCUMENT MARKUP


XInclude markup

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


Sample 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>


STEP 3: SEE WHAT HAPPENS
IN XMETAL


STEP 4: DO STUFF WITH
SCRIPT


Implementing XML inclusions
• XMetaL automatically recognizes XInclude
markup
• But there is no built-in user interface
• Th
There are new API
APIs
– XInclude-related methods/properties on Document
and Application objects
• Write script using APIs to implement desired
functionality
y


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

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


ShowXInclude(node)
ShowXInclude(node)
• Document object method
• If node i an XI l d the t
d is XInclude, th target is displayed
t i di l d
• Else, if node has XInclude ancestor(s), the
nearest one is di l
t i displayed
d
• Else, if node has XInclude descendants, they
are all displayed
– ShowXInclude(ActiveDocument.documentElement)
will show a inclusions in the docu e
s o all c us o s e document
• NOTE: An XInclude must be updated at least
once before it can be displayed
p y


UpdateXInclude(node)
UpdateXInclude(node)
• Same rules about which node(s) are affected
S l b t hi h d ( ) ff t d
• Causes a “refresh” of the affected node(s)
• Does not change visibility of the included
content


HideXInclude(node)
HideXInclude(node)
• Same rules about which node(s) are affected
S l b t hi h d ( ) ff t d
• Hides the target content of affected nodes
• Display reverts to fallback content


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


Some other interesting APIs
• ExportWithXIncludesToFile(strFile)
• E
ExportWithXIncludesToXML()
tWithXI l d T XML()
– Returns an XML string
• Li kR l ti E Li t
LinkResolutionErrorList
– Property, returns ValidationErrorList object
• ResultsManager object
– Application.ResultsManager.ShowLinkLogTab()
– Application ResultsManager HideLinkLogTab()
Application.ResultsManager.HideLinkLogTab()


Documentation
• Full documentation on the XML inclusion APIs is
in XMetaL Developer 6.0 docs
60


Some possible functionality
• Menu commands:
–IInsert XML inclusions
t i l i
– Show or hide all inclusions
• Context menu commands:
– Hide or show one XML inclusion
– Open XML inclusion target
• Other
– Combine with “Treat as link AI button
Treat link”
– Custom dialogs


DocBook sample
• Included* with XMetaL 6.0
• Ill t t several XI l d f t
Illustrates l XInclude features
• (DEMO)

* No pun intended © 2010 JustSystems Inc.

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


Taking Advantage of XMetaL’s XInclude Support

Recommended

Recommended

More Related Content

Viewers also liked

Viewers also liked (10)

Similar to Taking Advantage of XMetaL’s XInclude Support

Similar to Taking Advantage of XMetaL’s XInclude Support (20)

Recently uploaded

Recently uploaded (20)

Taking Advantage of XMetaL’s XInclude Support