Morpho XML Editor
April 28, 2004

The tree-based Morpho XML editor in version 1.5 has many changes from previous versions. This document is a discussion of how the editor has been changed, how it works, and how to update it in the future for new versions of eml.

The code for the tree editor is in the editor package with most of the code in the rather large DocFrame class (Yes, I know, it should have been broken into several smaller classes! DFH). The code folds together information from an XML instance document with schema information about cardinality, choices, sequences, etc.

In versions of Morpho before 1.5, DTDs were used instead of XMLSchemas to provide generic schema information. THe DTDs were parsed along with instance documents everytime the editor was launched. In Morpho 1.5+, we have shifted to eml2 and to the use of XMLSchemas (which are used to define eml2 - no eml2 DTDs have been generated).

In order to speed up the editor, it was decided not to parse the rather large eml2 schema everytime an instance document is loaded. Instead, the eml schema is parsed ahead of time and the information saved in a separate 'template' xml documemt which can be more easily merged with an instance document. In the case of eml2 and Morpho, this document is called 'eml.xml' and is stored in the Morpho ./lib/ directory. That template document contains all the schema information (cardinality, choices, help, etc) for all the possible eml elements in a form that is much closer to the form of an instance document.  

Note also that to minimize confusion, the XMLEditor now does not initially show all elements that MIGHT exist in an eml document. Instead, the default display contains just the nodes that already DO exist in the instance document. One has to click the "Show All" button to make the editor merge all the nodes in the template with those in the instance. (Also, xml attributes are now also shown in the tree, just like elements.)

A template document like eml.xml can be generated using the XMLSchema parser that is located in the Morpho CVS module (./lib/SchemaParser). This app can parse any XMLSchema package, but parses eml2.0.0 by default. (It can be launched using the 'runnit.bat' file on a Windows machine. It uses PSVI information from the Xerces XML parser to extract various XMLSchema information.) The app shows various schema information in a tree, including all 'Global Elements'. One of these is the eml2 root node, "eml:eml". You can expand that node to see eml structure, and selecting a node in the tree shows cardinality information at the bottom of the window. Clicking the "Save" button writes the information out to a file called "SchemaOut.xml" which is the basis of the template used by the XML Editor in Morpho.

Note that because eml is recursiuve, one has to have some means of stopping when building the eml tree. The XMLSchemaParser just sets the maximum number of 'levels' of the tree. In the default Java code, this maximum is set to 14. Note that this setting results in almost 5000 possible elements in the eml template! (This includes SEQUENCE and CHOICE nodes and well as elements repeated in several places.) 

The eml.xml file was originally created as described above, but a number of changes have been made in the machine-generated version to make the display less confusing. One example is changes to any 'TextType' subtrees which allow sections and paragraphs of text with inline formatting (html-like). These have been simplified to simple <para> elements for paragraph information. In addtion, an 'editor="edu.ucsb.nceas.morpho.editor.TextAreaPanel"' attribute has been added to many of these text elements to customize the display to show a large text area rather than a single line textbox. Another example is the use of a 'nodeVisLevel' attribute to make certain seldom used eml subtrees invisible (e.g. the "otherEntity" subtree). Also, the arbitrary depth of recursion in the machine generated template was insufficient in some cases. Thus, certain subtrees have been extended (made deeper) by copy and pasting from more fully expanded subtrees.

When a minor update to eml2 appears, it may be sufficient to simply hand-edit the existing eml.xml template. More extenisve changes would require regenerating the template using the SchemaParser.