Reply To: How to Disallow Empty Elements?

[Derek Read]

The event On_Update_ElementList (and associated APIs) allow you to change or restrict what is displayed in the Element List, so I don't think that's what you want.

You want to add additional validation requirements that cannot be defined in the DTD. We tend to refer to these as “business rules” (though I don't know if that term is actually used anywhere officially). However, it sounds like you also want to guide the user so they are unlikely to see a validation error. Both of these are doable.

The simplest method to guide a user to enter text is to use the PI. The difference between this an a normal PI is the way it is displayed and the fact that the entire PI is selected when click on, allowing the user to type over it.

You can use these PIs inside a document template (the files in the Template subfolder) or inside the “mini template” for a particular element.

The mini template can be used to create a chunk of XML to insert when the user inserts an element from the Element List. This is defined for each element in the CTM file. Whatever is in the mini template is inserted instead of just the element. If there is content that must always be inserted for a particular element you can include that in the mini template for the element as well, including text, child elements and their children and/or text, and/or attributes and their values.

Another method might be to pop up a dialog when the user inserts the element and then have that dialog guide the user into creating something acceptable, perhaps by simply asking them to fill in a text form and checking to see that they entered something or that they entered something that matches a particular format. However, as an implies a URL or path of some kind you might also display a “browse to file” dialog and use the path they pick, or maybe ask the user to copy the address from web browser to the clipboard and then read that into the dialog, something else?

XMetaL Author supports its own form format: XFT. You create these in the XMetaL Forms Layout tool included with XMetaL Developer. Then you hook up the form to either display as a popup or embed it inline in the document (for a particular element) by setting the appropriate settings in the CTM file associated with the DTD.

You can also pop up a dialog inside the On_Click or On_Double_Click events (fired when the user clicks in the document) using the CreateFormDlg() method.

The Journalist customization has a number of form examples (as does the DITA author functionality, though these are typically written in much more complex fashion so that a single XFT morphs how it looks in order to allow it to be reused for multiple elements and situations). The following Journalist elements either trigger the display of an XFT form or show an embedded XFT form when the element is inserted:

Yet another approach (one that you might want to include even if one of those above is also implemented) would be to use the event On_Check_Element_SimpleContent. This runs whenever the document is validated (ie: if the user requests it via F9 or during save or open). In here you can check the PCDATA content for an element and create a corresponding custom error message if your requirements are not met. This means the user needs to insert an put in the wrong content (or in your case no content) then they are told about it when they validate or save (just like any other validation issues). This way, if the user somehow gets past your guide and manages to create something that violates your rule (Plain Text editing is the easiest, or perhaps in another piece of software) this code would still catch the issue.

The On_Check_Attribute_Value is a similar event that that lets you check attribute values according to your own business rules.

The XMetaL Developer Customization Guide has information on all of these things.

Keep in mind that XMetaL Author has a feature called Rules Checking that other products don't have. Most products only validate documents (at various times) showing you what is wrong with them after the issue has been introduced. The rules checking feature in XMetaL Author attempts to stop someone from creating an invalid document in the first place. It does this through various means: by listing only valid elements in the Element List (for the current position in the document), by stopping people from pasting in invalid elements, by stopping you from dragging and dropping content to places where it will be invalid, by stopping you from deleting elements (which is not always possible), by stopping you from setting bad attribute values, etc. This feature works automatically based on the definitions in the DTD or XSD, which also means the only way to get it to function is to make modifications to the DTD or XSD.

Reply