deploying schemas and xmetal customization files

© 2010 JustSystems Inc.© 2010 JustSystems Inc.

in 37 minutes

Episode 14

Deploying Schemas and XMetaL

Customization Files

Brought to you by XMetaL Technical Services

Derek Read, XMetaL Technical Support

© 2010 JustSystems Inc.

• Application-Level vs Document-Level Customizations

• How does XMetaL Author…

– …locate a DTD?

– …locate an XSD (W3C Schema)?

– …locate customization files?

• Complex Customizations, XAC files, XMetaL Developer

• Debugging the lookup process

• Questions

Agenda


• One or more macros contained in an MCR file loaded at

application initialization.

• May include supporting files (XFT, config and any other

file types) called from or used by the macros.

• Macros loaded at startup:<xmetal install>\Macros\xmetal.mcr

<xmetal install>\Macros\macros.mcr

<xmetal install>\Startup\*.mcr

• Other files may be located anywhere.

• Include macros in your own custom *.mcr file in \Startup

folder unless required by specific APIs (as documented).

• Toolbars and menus are best customized using script

and not delivered as *.TBR files.

Application-Level Customizations


• The basic startup sequence for XMetaL Author includes:

– Load catalog files into memory.

– Load Application-Level macros and fire any relevant

events.

• This means that for any changes to catalog and

Application-Level macros to take effect XMetaL Author

must be restarted.

Startup Sequence


• A schema (DTD* or XSD*) and all files used to enhance

the editing experience for an author working with

documents based on that schema.

• Minimum customization includes:

– schemaName.dtd / schemaName.xsd / schemaName.rlx /

schemaName.rld / schemaName.rls (SGML DTD)

– schemaName.css**

– schemaName.ctm**

* DTD or XSD may reference other files, such as *.mod, *.ent, etc.

** If these files are not present they will be auto-generated. So, all

customizations should include properly designed files of these types to

provide the best authoring experience.

Document-Level Customizations


• Optional file types (loaded if found):– schemaName_structure.css*

– schemaName.mcr

– schemaName.tbr**

– schemaName.att

– <path>\<filename>.xft***

* Will be auto-generated if not found when the main CSS file is auto-generated.

If the main CSS file is found but this file is missing

schemaName_structure.css will not be auto-generated.

** Recommend modifying toolbars and menus via script as delivery of updates

to these settings through TBR files can be troublesome.

*** Loaded according to <XFTReplacements> settings in the CTM file.

Document-Level Customizations (continued…)


• You may choose to distribute only the compiled form of a

DTD or XSD (RLX/RLS or RLD file).

• Compiled form may be useful when the DTD or XSD

references many other files (file management).

• You may wish to reduce chances of end users modifying

the schema.

Document-Level Customizations (continued…)


Locating a DTD


Locating an XSD (W3C Schema)


• Look in same folder as schema (DTD / XSD / RLX / RLD

/ RLS) and load any of the following if found:schemaName.xac*

schemaName.css

schemaName_structure.css

schemaName.ctm

schemaName.mcr

* XAC should take precedence. The XAC should be unpacked and the files it

contains used. However, we do not support mixing XAC with a “traditional”

set of customization files so it is best to distribute one or the other. Note as

well that the XAC file itself should normally contain the rules file (usually the

compiled version in RLX or RLD form) so an external rules file is not

necessary when a XAC file is used.

Locating Customization Files


• If not found in same folder as schema then load*:<xmetal install>\Display\schemaName.css

<xmetal install>\Display\schemaName_structure.css

<xmetal install>\Rules\schemaName.ctm

<xmetal install>\Macros\schemaName.mcr

* There are INI settings to alter these paths. Refer to the XMetaL Developer

Customization Guide.

Locating Customization Files (continued…)


• If still not found:schemaName.css : auto-generate.

schemaName.ctm : auto-generate.

schemaName_structure.css :

If schemaName.css was auto-generated then auto-generated,

else if schemaName.css was found then this will not auto-generate.

schemaName.mcr : fail to load.

• Auto-generated files should end up here:%appdata%\SoftQuad\XMetaL\6.0\gen\<drive>\<recreate schema path>

Example:

C:\Documents and Settings\dread\Application

Data\SoftQuad\XMetaL\6.0\gen\C\myDTDs\*.*

Locating Customization Files (continued…)


• Customizations may consist of many files.

• Keep files close together whenever possible.

• Place files in well-known locations. ActiveDocument.ResourceSet provides information

about all files loaded automatically (via XAC or

otherwise).

Complex Customizations


• For file types that are not automatically located there are

APIs to help:

– ActiveDocument.RulesFile tells you the location of the

active schema. Useful for finding files delivered in XAC file or

otherwise located relative to the schema (DTD, XSD, RLX, RLD,

RLS).

– Application.Path gives location to xmetal60.exe. Lets you

do things like (JScript): Application.Path+"\\Rules"

• Use Windows Environment Variables to create “limited-

user savvy” customizations when constructing file paths.

Examples:

%temp%, %appdata%, %userprofile%, etc…

Complex Customizations (continued…)


Example:

On_Application_Resolve_Entity

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

//Put this macro in \Startup\myApplicationMacros.mcr

var msg = "";

var entInfo = Application.ResolveEntityInfo;

msg += "From doctype declaration (DTD or XSD?): ";

msg += entInfo.IsDocType();

//Following properties are read/write.

//This is where you would do any overrides.

//Any “read” comes from the XML file

//a “write” affects memory only.

msg += "\nSYSTEM id: " + entInfo.systemID;

msg += "\nPUBLIC id: " + entInfo.publicID;

Application.Alert(msg);

]]></MACRO>


• Path to XFT is relative to the CTM file. If the CTM file is

found then the XFT will be found.

• When using Application.CreateFormDlg() the

XFT path should be a full path.

• To find the full path for any file delivered by XAC

(including XFT) use script similar to this:

What About XFT Forms?

//JScript Example:

var rfPath = ActiveDocument.RulesFile;

var xacFolder = rfPath.substr(0,rfPath.lastIndexOf("\\"));

var myForm = xacFolder + "\\myform.xft";

Application.CreateFormDlg(myForm);


• XMetaL Developer builds both a XAC file and a

“traditional” customization (RLX + CSS + CTM + MCR +

other).

• XAC file consists of a ZIP archive (renamed *.xac)

containing all customization files and a manifest.

• Unpacked to a temp folder before being opened.

XAC Files


• XMetaL Developer puts all files in the same folder when

building. Distribute either XAC or “traditional” files only.

Do not distribute both.

• When designing complex customizations my personal

preference is to avoid XAC files as the unpacking

process can add a little bit of complexity.

XAC Files (continued…)


• Using F5 to debug XMetaL Author from within XMetaL

Developer triggers some additional functionality that

links the current project (schema and other files) directly

to XMetaL Author (or XMAX).

• CSS and CTM files can be modified in XMetaL

Developer and these changes are automatically

reflected in the authoring tool.

• XMetaL Author adds two items to the Edit menu to allow

you to jump back to a particular element in either the

CSS or CTM editor.

XMetaL Developer


• Usually macros can be modified with an “edit

and continue” feature.

– Exceptions are adding new macros and certain

events.

• Always test customizations on a machine that

does not have XMetaL Developer installed as a

final step before distributing to end users.

XMetaL Developer (continued…)


• Some CMS integrations require document-level

customization files to be installed on the client machine.

• Some CMS integrations store document-level

customization files in the CMS and push these files to

the client machine when documents are checked out.

• In both cases the CMS integration provider should

provide documentation on where XMetaL customization

files should be placed and how to configure them to work

with that particular CMS.

CMS Systems


• Use the following xmetal60.ini settings to troubleshoot

DTD and XSD look-up problems.

make_log_file = yes *

log_file = <path> **

* Default is „no‟.

** Default is the install folder for xmetal60.exe so on some systems (non-

admins / UAC enabled) you will need to alter this. Specify the full path and filename of the file. Example: C:\temp\xm_lookup.log

Settings for Troubleshooting


Thank you for attending!

Next “37 Minute” Webinar:

Watch for an announcement at

http://forums.xmetal.com

Q&A

deploying schemas and xmetal customization files

Documents

xac files

files file management

autogenerated files

tbr files

place files

designed files

rld file

load catalog files