Script Example: Custom Validation Log Messages

[Derek Read]

Background:
XMetaL Author provides APIs that allow you to add your own "business logic validation" for two special cases: the "simple content" of elements (PCDATA) and attribute values. The Journalist demo includes an example of this but requires a little bit of digging to find and set up (we don't ship an invalid file for testing it).

The example included here basically duplicates the Journalist demo script but just deals with this one feature. It also includes an example of an "invalid" file (technically valid according to the DTD but "invalid" according to the "business logic validation" in the MCR file) that will trigger the logic in the script.

Suggested Audience:
XMetaL Author developers interested in adding additional checks on XML content that:

• cannot be defined in a DTD, or...
• are not defined in an XSD (even though it might be possible to do so you might not wish to alter an existing Schema), or...
• are not caught properly by XMetaL's XML validation (for whatever reason).

Usage:
1) Unzip attached file to an empty folder on your machine (includes DTD, CSS, CTM, MCR and XML).
2) Open the file testDocument.xml in XMetaL Author and see what happens.
3) Examine the script called On_Check_Element_SimpleContent in the MCR file and adapt it for the needs of your own customization. Note that full validation is forced at document open by including an additional event macro. This is optional of course, as F9 and a standard Save or Save As will still trigger validation.

Notes:
It is also possible to "validate" attribute values in a similar way using the event On_Check_Attribute_Value. See the XMetaL Developer Programmer's Guide. The logic in a script for checking attributes would be virtually identical with the exception that you might also use the Application.CheckData.AttributeName property.

Please also heed the warning in the Programmer's Guide:

Do not change the DOMNode during the execution of either of these event macros. Unrecoverable errors may result.

If you wish to automatically "correct" these types of issues within a document there are various other events that are more suitable, such as On_Before_Document_Save or On_Before_Document_Validate, or in the case of attribute values set using the Attribute Inspector you might wish to do so right after the user has set the value using On_Before_Set_Attribute_From_AI or On_After_Set_Attribute_From_AI.

[dcramer]

This is a cool trick and I'd like to be able to use it. Your demo works perfectly for me, but when I add it to my dtd's macro file, it does odd things. Here's a simple test case. I added the following to docbookx.mcr in the same directory as the DocBook DTD:

Code:

<?xml version="1.0" encoding="UTF-16"?>
<!DOCTYPE MACROS SYSTEM "macros.dtd">
<MACROS>
<MACRO name="On_Check_Element_SimpleContent" key="" hide="true" lang="JScript"><![CDATA[
var cd = Application.CheckData;
var elem = cd.Element;
var name = elem.tagName;
Application.Alert(name);
]]></MACRO>
</MACROS>

I use catalog files so XMetaL will find the local copy of the DTD. When I validate the following simple document with that macro in place, nothing happens (i.e. the doc validates fine with no alerts):

Code:

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<book>
  <title>Guide to Creating, Editing, and Managing XML-based Documentation</title>
  <chapter>
<title>title</title>
<para>blahdsfsss  </para>
  </chapter>
</book>

It is even stranger when I add it to my real macro file (the one that I use with my customization of the DocBook DTD) and with a real (i.e. longer) document. A few Application.Alert(name)s do fire, but only about seven (a few keyword and subject elements and their parent keywordset and subjectset elements).

Any ideas?

Thanks,
David

[dcramer]

Nevermind, I just noticed the part where you mention it only fires for PCDATA elements. That explains everything. Not so useful after all :-(

There are a few elements in the DTD that cause weird things to happen when they're empty and I wanted to catch that at validation (I already check for it in the xslts), but none are PCDATA-only elements.

David