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

2.
Announcements
• Next time: Su-Laine “XMetaL for Simple XML
Editing
Editing”
© 2010 JustSystems Inc.

3.
Agenda
• Introduction
• B i XI l d markup
Basic XInclude k
• XMetaL XInclude APIs
© 2010 JustSystems Inc.

4.
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
© 2010 JustSystems Inc.

5.
XMetaL’s XInclude support
• XMetaL automatically recognizes XInclude
markup
• XMetaL XInclude APIs allow customizers to add
reuse functionality to document customizations
© 2010 JustSystems Inc.

6.
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
• ...
© 2010 JustSystems Inc.

7.
STEP 1: XINCLUDE IN YOUR
DTD OR SCHEMA
© 2010 JustSystems Inc.

8.
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
© 2010 JustSystems Inc.

9.
Example DTD with XInclude
<?xml version="1.0" encoding="UTF-8"?>
<!-- "-//Mag//DTD Simple Paper//EN" -->
<!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
>
© 2010 JustSystems Inc.

10.
STEP 2: XINCLUDE IN YOUR
DOCUMENT MARKUP
© 2010 JustSystems Inc.

11.
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>
/
© 2010 JustSystems Inc.

12.
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>
© 2010 JustSystems Inc.

13.
STEP 3: SEE WHAT HAPPENS
IN XMETAL
© 2010 JustSystems Inc.

14.
STEP 4: DO STUFF WITH
SCRIPT
© 2010 JustSystems Inc.

15.
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
© 2010 JustSystems Inc.

16.
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");
© 2010 JustSystems Inc.

17.
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
© 2010 JustSystems Inc.

18.
UpdateXInclude(node)
UpdateXInclude(node)
• Document object method
• 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
© 2010 JustSystems Inc.

19.
HideXInclude(node)
HideXInclude(node)
• Document object method
• 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
© 2010 JustSystems Inc.

20.
OpenXIncludeTarget(node)
OpenXIncludeTarget(node)
• Document object method
• 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
© 2010 JustSystems Inc.

21.
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()
© 2010 JustSystems Inc.

22.
Documentation
• Full documentation on the XML inclusion APIs is
in XMetaL Developer 6.0 docs
60
© 2010 JustSystems Inc.

23.
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
© 2010 JustSystems Inc.

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

25.
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
© 2010 JustSystems Inc.