MiXml tightly integrates an XML (extensible markup language) forms based database with the InterMix messaging system.  Each MiXml "item" acts like an InterMix message in most ways.  A MiXml item can be posted to a discussion group; it can be replied to, rated, moved, modified, booted and deleted just like an InterMix message.  However,  an MiXml item cannot be a reply. 

MiXml form data are input into templates that will be familiar to anyone who uses the internet.  These templates are written in HTML so their look is very flexible.  Ditto for the display side of MiXml forms. 

Each MiXml item carries with it in the database, complete instructions how to modify and display its data.  The data itself is carried in standard XML format in its own section. The input and output instructions are sections of HTML with specially formatted MiXml "tags" incorporating the XML data names to indicate where in the HTML the different data fields are located. 

The three sections are stored together in the InterMix message table as one long text string.  InterMix parses the sections into an XML tree when the data is retrieved and reconverts the tree to a string when the data is stored.  New items are added using MiXml template forms which are kept in standard .txt files. 

These templates are XML documents created by hand, possibly with the help of an HTML editor.  Creating the templates is difficult and time consuming, since one is working with data design, form design and display design simultaneously.  When adding a new field the Xml change is easy, but shoehorning the addition into the input and display sections can require multiple adjustments to the html.  InterMix needs a MiXml Document Tool.  Changes can be applied retroactively to existing documents -- see the section below on catching up. 

An InterMix "Discussion Group", aka "area", can specify a MiXml template for all new items for that group.  Replies in the group are in standard message format, but root items are of the specified form. 

If a MiXml form template is changed internally to have new fields, say, or a different display, all new items added using that template embody the changes, but all pre-existing items are unaffected - except see below on catching up.

InterMix supports 1) standard text lines, 2) text boxes, 3) radio buttons, 4) select menus and 5) check boxes.  Note that InterMix detects and handles multiple selections for select menus.

Documents can be brought up to date to match changes to the form template.  There are rules that must be followed in the redesign of the form template or else data may be lost - CAUTION is advised.  Currently there is no function to "sweep" a database, changing all documents.  Documents are caught up one by one. 

There are three prerequisites for the catching up of a document.  1) The document root must have the MiXmlFileName attribute.  2) The input or output html must have been altered and 3) the document must be displayed for modification. 

If the root element of a MiXml document has the MiXmlFileName="name" attribute, then whenever the document is being displayed for modification, it is checked against the current version of the form template.  If either the input html or the output html have been altered, then the new html is installed in the existing document and the xml data section of the document is compared against the new template to pick up any new fields that might have been added.  Note that the document does not have to actually be modified to pick up the changes.  Just displaying for modification is enough. 

Changing either the input or display html in the template is what triggers the catch up process.  If you change just the xml data section, new documents will reflect those changes, but existing documents will not be affected when modified. 

Changing the template has no effect on existing documents until those documents are next modified.  Even then there is no effect unless the template had the MiXmlFileName="name" attribute on the root at the time the document was created.  Also, the "name" must match the name of the template in the Forms subdirectory under the current hub. If the name of the template has a .txt extension, as it normally will, then that extension can be left off the attribute value.  For instance, if the template is kept as c:\lamix\host\hub0\forms\event.txt, then use MiXmlFileName="event" or MiXmlFileName="event.txt" as an attribute on the root element.  Either way will work. 

In the xml section, elements may be added or deleted, but they cannot be moved.  Elements must be added at the end of the list of elements for the given super-element.  For instance, if we have a simple contact document and decide to add DickTracyWatch to the list of contact methods, the new element has to go at the bottom: 

<contact>
      <name></name>
      <phone></phone>
      <cellphone></cellphone>
      <pager></pager>
      <remarks></remarks>
      <DickTracyWatch></DickTracyWatch>
</contact>

It is very important to put the new DickTracyWatch at the end of the list instead of adding it after "pager" where it would seem to go better, logically. 

If you delete an element, the existing documents keep that element.  Then a confusion could arise if two years later you decide to add back an element of the same name.  In general it is better if you never delete elements, but only remove the references to the elements in the input/output html. 

Never move an element.  Never add an element in the middle. Never change a repeated element to non-repeated or vice versa.  (It is ok to reduce the maximum number of repeats - data in old documents with extra repeats over the new maximum will be maintained.)  If you change validation, that will be handled the next time the item is "sent". 

Extensions can be caught up, too.  Again, there is no automatic sweep of the database.  Rather, every document with the changed extension must be displayed for modification.  Care must be taken when building a compound template using extensions.  If those extensions are modified for the compound template, then be sure to remove the MiXmlFileName attribute from the newly formatted extension, or better yet, change the MiXmlFileName.  An extension will be "caught up" only if it has a MiXmlFileName of its own.

MiXml Repeats allow a form to have any number of repeated sections, nested to any degree.  Standard html forms are seriously deficient for practical purposes because they do not support repeated sections.  Say one wants to list authors and link them via a list to all of their books.  Or, a good example of nested repeats, for a genealogy database, one would want to list for each person their spouses and for each spouse the children.  With standard html, this is going to be a complicated multistep procedure, but with MiXml a single input form will do the trick. 

The difficulty of handling repeats is that one might want to allow any number of books for the author, but on the input side there has to be a limit to the number of books that can be input in the same go.  MiXml addresses this problem by allowing the form designer to specify both the maximum number of repeats allowed for a section and the number of new empty repeats to display whenever the form is to be modified.  Thus in the author/book example, the form might allow 9999 books, but only three new books at a time.  The form is created and the first three books listed.  Then if there are more books to be added, the form must be saved and reopened to add the next three. 

MiXml at this point can identify an empty repeat and remove it from the list, but there is no way to insert a repeat -- a feature for the future(!).

The MiXml Extension feature allows the basic MiXml form to be extended by adding additional MiXml forms at the bottom.  For instance, a basic form for a person with name and contact info can be extended with an optional "personal information" form.  With some know-how, a template can be "pre-extended" manually. 

MiXml reports can be displayed on the "message list" page of InterMix as an alternative to the standard listing, or as a standalone page. 

A standalone report is typically linked to from an InterMix network owner's site to display items from that network.  When invoked as a standalone page, various defaults for the display can be overridden by cgi parameters in the url. 

Reports are stored in the Reports folder in the InterMix server directory as .txt xml documents with four sections: 

1. header html
2. item html
3. footer html
4. control xml

The header and footer html sections allow the designer to enclose the report in an outer table. 

Usually, the designer will also want to include in the header all the standard html header elements, including the opening of the <BODY> element.  Likewise in the footer section, the close of the </BODY> element and the  </HTML> element will normally be included.  There is a trick here, though.  The html header elements should always be enclosed by a pair of html comments of the following form: <!--docheader--> and correspondingly the html document close elements in the footer should be enclosed in a pair of  <!--docfooter--> comments. 

The docfooter and docheader comments allow InterMix to locate and remove the page header and footer html when the report is displayed within InterMix as a substitute for the message list.  When the report is displayed standalone, InterMix allows the page header and footer html, so the page can display as desired.  Best to look at an example: 

<MiXmlReportFooterHtml> 
<![CDATA[ 
</table></td></tr></table></center> 
<!--docfooter--></body></html><!--docfooter--> 
]]> 
</MiXmlReportFooterHtml>

In the above example of a footer section, the <![CDATA[ and ]]> enclosure merely tells the xml parser not to parse the enclosed html.  It is only the two lines of html that are of interest.  The first of those two lines, beginning with </table> closes the header section tables.  The second line, with the docfooter comments, closes the html document. 

The item html will usually be a table row that displays a few of the most pertinent data elements for each selected item.  Here is an example: 

<MiXmlReportItemHtml> 
<![CDATA[ 
<tr><td><font face="Arial" size="2" color="#000040"> 
*[[%LAevent_date%]]*&nbsp;&nbsp;&nbsp; 
<a href="mixstub.exe?&hub=0&message=*[[%itemnumber%]]*"> 
*[[%LAevent_eventname%]]*</a> 
&nbsp;&nbsp;*[[%LAevent_timefrom%]]* 
<!--LAevent_timeto--> 
&nbsp;-&nbsp;*[[%LAevent_timeto%]]* 
<!--LAevent_timeto--> 
</font></td></tr> 
]]> 
</MiXmlReportItemHtml>

Again, the <![CDATA[ and ]]> enclosure just tells the xml parser not to parse the enclosed html. 

LAevent_date, LAevent_eventname, LAevent_timefrom and LAevent_timeto are the four data fields being reported for each selected item.  The href with message=*[[%itemnumber%]]* makes the event name clickable - taking the user to the details page for the event.  The paired <!--LAevent_timeto--> comments will cause the enclosed section to be removed if the LAevent_timeto field is blank. In this case, we don't want to see the hyphen between the from and to times if there is no "to" time. 

There are several special replacement options available: 

*[[%itemnumber%]]* - as displayed in upper right of item 
*[[%itemauthor%]]* - author of item 
*[[%itemsubject%]]* - subject of item 
*[[%itemvisits%]]* - number of visits so far to item 
*[[%itemvalue%]]* - current item rating value  
*[[%itemmixid%]]* - internal InterMix ID - see calendar report

MiXml data indexing is specified field by field.  There are two kinds of indexing for a field.  First, the optional basic indexing of the field data, word by word.  Second, also optional, an "indextag" prefix can be specified which is then added to each word of the data for the index.  For instance, a database of organizations might have a text box for keywords describing the organization.  Each keyword could be separately indexed, and also indexed with the indextag 'keyword_' prepended.  This double indexing allows a search to narrow its focus to a particular field. 

Additionally an item level keyword may be specified for each different form.  The item level keyword can be used to restrict a search to only items of a particular kind.  In conjunction with the indextag prefix, it allows pinpoint searching.

MiXml text or textarea fields can automatically pull data from and link to another MiXml item.  The basic pull and link capability is implemented in two attributes, a link="yes" attribute and related pull="itemKeyword::indextag::fieldname".  Normally both attributes are present or neither, but it is possible to just pull some data without linking.  As of June 2000,  the data is pulled only when the pulling item is created or modified. 

Note that if the item being pulled from has a namespace attribute, the fieldname must be prepended by the namespace value.  For instance, say the LAorg MiXml form has a namespace="LAorg_" attribute on the document, and the item keyword is "LAorg_item".  Then if we are going to pull from the "name" field, we would use pull="LAorg_item::name::LAorg_name".  It is ok to pull data from a field in an extension.  Just be sure to prepend the namespace of the extension to the field name. 

Automatic linking works two ways.  If the data inputter inputs a # sign followed by an item number, then InterMix goes direct to the item and pulls the data from the given fieldname, making it linkable.  If not successful, the #itemnbr is not replaced by data and not linked.  (As of June 2000, the code actually pulls the data from the specified item, but then uses the data as if it had been entered to find the item it links to, so if the data is not unique it is possible for the link to reference a different item -- eventually this will need to be fixed.) 

Note that without the link="yes" attribute, then the data is not pulled.  In this case, the use of the pull= attribute is only to locate a record from which data will be pulled using the copyfields= attribute (see below). 

If the data inputter inputs any other data besides a #number, InterMix uses the itemKeyword and indextag (see above) to locate the item, and adds the link.  If not successful, the data is not linked.  If the data is not unique, InterMix links to the first matching record. 

If you pull from a repeated field, the data from the first repeat will be pulled. If you link by matching data to a repeated field, all the repeats will be examined for a match.   Note that it is ok to add link and pull attributes to a repeated field.  In this case, each repeat may link to a different item. 

Items cannot be linked nor data pulled if the data inputter does not have access to the linked/pulled item because it is private.  Also, a public item cannot link to or pull data from a private item. 

Hint: success is not assured, so the data inputter needs to use the preview button. 

Info: the item number is given in the upper right corner of the item display. 

Example: in a database of books and authors, the author field in the book form can autolink to the author, and the book field in the author form can autolink to the book.  A desirable feature, not yet implemented, would be to automatically add a new book to the author form when the book item is being added and autolinked. 

An extended pull by fieldname capability is implemented when the item is created.  Pull by field name brings data from any number of fields in the linked item into the item that is being created.  Manually entered data overrides extended pull data.  Repeated data is pulled from the first repeat in the source item.  When data is pulled to the same target field from more than one source, the first non-blank data will be used. 

Extended pull will also occur when an item is modified, but the logic cannot distinguish between manually entered data and previously pulled data, so if a field is changed on the source record, the new data will normally not be pulled unless you manually remove the data in the target field.  To force the replacement of all extended pull data, enter !itemnumber instead of #itemnumber in the pull and link field. 

The purpose of extended pull is to ease data entry when data which is already available in other items has to be entered over and over again.  For instance, when entering an event for the Calendar, it is possible to pull contact information, description and location information, etc from a previously created calendar event just by entering the number of that event item. 

It is ok for source field names to be in an extension.  When source field names are specified, be sure to include the namespace prefix. 

Extended pull is implemented as an optional attribute of form: 
      copyfields="fromfield1::tofield1 
                         fromfield2::tofield2". 
If there are namespaces, they must be prepended to the field names. 

Any number of from/to pairs may be specified.  From/to pairs are separated by any combination of spaces and carriage returns.  The copyfields attribute must be on a text or textarea field which also has a pull= attribute.  See above. 

See below for related push="yes" attribute.

The from= attribute allows the form maker to fill a field from other fields on the same form using literals between the fields.  For example: 

<fullname type="text" 
      index="yes" 
      indextag="name" 
      from="LAcontact_title::text 
            ' '::literal 
            LAcontact_forename::text 
            ' '::literal 
            LAcontact_surname::text" 
      subject="yes" 
></fullname>

In the above example, the title, forename and surname are pulled with a space between to make the full name.  If the field is enterable and the user enters data, then the user data overrides the from= instruction.  If the literal is all whitespace, it needs to be enclosed in single quotes.

A sort= attribute on the document root specifies a sort field up to 22 characters long.  For example :  

sort="LAevent_date::date 
         LAevent_timefrom::time"

In the example, note the namespace prefix and the "date" and "time" formats. The date and time formats put the date into yyyymmdd format and the time into 24 hour hhmm format so the sort will work.  Formats "text" and "textarea" simply bring in the text without reformatting. 

Documents with a sort= attribute can be sorted in "special" order on the Search page.

• required="yes" - if field data is not entered, error box is displayed

 
• subject="yes" - when adding a new item, if the "subject" line is left blank,  then the subject is taken from this field

 
• index="yes" - field data will be indexed 

 
• indextag="xxx" will cause the field values to be indexed also with "xxx_" prepended to each value

 
• ifempty="zzz" on a field level element will cause the item to be indexed with "zzz" if the field is empty 

 
• keywordtype="AREA_" on a select field will cause the item to show up under selected discussion groups.  To work, the value of the selected option(s) must be the same as the name of the group, and there must not be two discussion groups of the same name. On a modify, though, a change of selected areas will add the new areas, but not remove the old.  Also if you use the MOVE command to change areas, the select field(s) will not stay in sync automatically.  This is clearly a fault, not a feature, but is too minor and time consuming to fix for now. 

Note - select field only.  One use of this feature is to force every item type into its particular database area.  For instance, calendar events can be made to show up in an "Events" discussion group by adding an xml select field that is populated from a hidden input element thus: 
 
  modify:    <input type="hidden" name="eventarea" value="Events"> 
  xml:    <eventarea type="select" keywordtype="AREA_" ></eventarea> 

doctype MiXmlForm: 
 
1)  Has 2 major required subelements: MiXmlFormHtml, 
    and MiXmlFormXml.  An optional third subelement is 
    MiXmlFormExtList, which contains builtin or added 
    extensions.  Each extension is wrapped in a 
    MiXmlFormExt subelement of MiXmlFormExtList. 

    Every MiXmlFormExt element is assumed to be a 
    complete MiXmlForm, minus its header -- i.e., a 
    root element of another MiXmlForm.  Extensions may 
    themselves contain builtin extensions.  Using 
    builtin extensions is a quick way of combining two 
    or more existing MiXml forms to make a new form. 

    In order to avoid name clashes, MiXml forms which 
    could be used as extensions should employ the 
    namespace= attribute in the root of the document. 
    The namespace value is automatically prefixed to 
    all names in the document.  Normally namespace 
    values are short, unique and end in an underscore: 
    namespace="LAorg_" for example.  If a form that has 
    no namespace is used to extend a document, then a 
    randomly generated namespace is provided.  Ditto if 
    a document with a namespace is used as an extension 
    more than once. 

2)  MiXmlFormHtml has two subelements: 
    a) MiXmlFormModifyHtml 
    b) MiXmlFormDisplayHtml. 

3)  The FormXml elements may be nested to any depth. 
    This allows for extensions and repeats.  Generally 
    only the lowest level elements will be "field" 
    elements. 

4)  The html and xml field elements relate to each other 
    via tags of format: *[[%tagname%]]*. 
 
5)  Each xml field element either has a tag attribute 
    or the tagname is automatically created from the 
    name of the element.  For Radio and Selected 
    values in the modify html, the automatically 
    created tagname is name+value. 

6)  Xml field elements must have a type attribute with 
    a valid value: "text" "radio" "checkbox" "select" 
    "textarea" - must be lower case as shown. 

7)  If you have a textarea, then the user will be 
    given the "formatted/unformatted" option.  If 
    you say the textarea is type="text" instead of 
    type="textarea" in the xml, the user will not 
    get the option to set formatted/unformatted. 

8)  Optional attribute index="yes" will cause the 
    contents of this field to be parsed and indexed. 
    Checkboxes will be indexed: checkboxname_value, 
    or checkboxname_NO if not checked. 

9)  Optional field attribute indextag="xxx" will 
    cause the field values to be indexed also with 
    "xxx_" prepended to each value. 
 
10) Optional attribute keyword="yyy" on any field 
    level element will be applied to the document 
    if the value of the field is not null.  The 
    same element on the MiXmlFormXml element or any 
    subelement above field level will cause the doc 
    to be indexed with "yyy" regardless of content. 
    As a suggestion, use: rootname+'_item on the 
    MiXmlXml element and in the upper right corner 
    of the display show: "search for rootname_item". 

11) Optional attribute ifempty="zzz" on a field 
    level element will cause the item to be indexed 
    with "zzz" if the field is empty. 

12) Optional attribute valid="value1 value2..." 
    on radio, select & checkbox fields is recommended 
    for data that may someday be exported to non- 
    InterMix systems. 

13) Optional attributes new_title, display_title and 
    modify title on the document root govern the 
    title displayed in the html header section. 

14) "Repeats" may be built in to the form by wrapping 
    a section of the form in an element with the 
    following required attributes: 
       type="repeat" 
       max="n" where n is max number of repeats to 99999 
       min="n" where n is number of empty instances 
               to display on create or modify 

    Only the first (template) instance of the repeat 
    is built into the xml and the two html sections. 
 
    The name of the xml repeat wrapper is used in an 
    html comment to delimit the template html for 
    both modify and display html: 

      <!--repeatname--> 
      template html 
      <!--repeatname--> 
 
    Each instance of an xml repeat may consist of one 
    or many elements, and repeats may be nested to any 
    depth. 
 
    On display, a repeat is skipped entirely if there 
    is no data.  This feature can be used to suppress 
    display of an empty section using min and max="1". 

15) Another way to skip a section on display when 
    the section has no data is to wrap the section in 
    html comments consisting just of the element name. 
    For instance <--elemname-->this section will be 
    deleted if the elemname element has no data 
    <--elemname-->.  Unfortunately because of the way 
    InterMix handles repeats, a repeated section cannot 
    be handled by this method, except if the repeat is 
    itself a max="1" repeat, in which case the following 
    wrapper will work to remove an empty section: 
    <--elemname_1-->.  The good thing about this 
    method vs using max="1" repeats is that the active 
    comments are needed only in the display html section, 
    so the xml and the input html are cleaner. 

16) Optional attribute required="yes" will cause an 
    error message if no data is entered.  Use this 
    attribute only for text and textarea fields. 
    In a repeat, required="yes" has no effect if the 
    entire repeat is empty.  The name of the xml 
    field is mentioned in the error message. 

17) Attributes pull="itemKeyword::indextag::fieldname" 
    and link="yes" and push="yes" are optional.  With the 
    pull= attribute, either #itemnumber or a text value may 
    be entered into the text field.  If #itemnumber is 
    entered, then the corresponding item is located and 
    if link="yes" is true, then the value of "fieldname" 
    is pulled into the target field - i.e. the field that has 
    the pull= attribute.  Note that without the link="yes" 
    the source record is located, but the value of 
    "fieldname" is not pulled unless a copyfields 
    attribute causes the data to be pulled. 

    If a text value is supplied instead of a #itemnumber 
    then the itemKeyword and the indextag is used in 
    conjunction with the supplied text to retrieve the 
    first item that matches.  Normally text value is used 
    with the link="yes" attribute as well, which will 
    cause an automatic link to the matched item. 

    push="yes" used with the copyfields attribute copies 
    data from the fromfield to the tofield in the same 
    document, provided the fromfield has data and the 
    tofield does not.  If the fromfield is not the same field 
    that has the push="yes" attribute, the results may 
    differ depending on the order of the fields in the 
    document -- best always to put the push="yes" on the 
    the field that is going to be pushed. 

18) Attribute copyfields="fromfield1::tofield1 
                                         fromfield2::tofield2" 
    is optional on a field that also has the pull= or push= 
    attribute.  Any number of from/to field pairs 
    may be specified in the copyfields attribute. 
    From/to pairs must be separated by whitespace 
    (spaces, tabs, carriage return etc).  Copyfields is 
    used only when an item is being added.  Field 
    names must be specified with namespace prefix. 
    It is ok for fields to be in extensions. 

19) Two special tags control wordwrap in textarea 
    input: *[[[%messagewrap%]]]* is replaced by 
    'wrap="physical"' and *[[[%messagewrap2%]]]* is 
    replaced by 'WRAP' unless the user has turned off 
    wordwrap in personal settings.  See examples in 
    provided xml templates.  Explorer always wraps, 
    but Netscape will only wordwrap if one of these 
    attributes is set.  Note that we have [[[ and ]]] 
    instead of the usual [[ and ]]. 

20) Attribute from="fromfield1::format1 
                                fromfield2::format2" 
    is optional, used to pull data in the order specified 
    into the current field from other fields in the same 
    document.  Note that the fromfield names must have 
    the namespace prefix for the document.  Available 
    formats are "date" "time" "text" "textarea" and 
    "literal".  The "literal" format treats the fromfield 
    name as a literal, optionally enclosed in apostraphes. 
    For instance  from="LAcontact_forename::text 
                                    ' '::literal 
                                    LAcontact_surname::text" 
    will put a space between the first and last names. 

    The from= attribute replaces any data in the field, 
    so it does not make sense for the user to be able to 
    input data into a field that has a from= attribute. 

21) Optional attribute datatype= has three valid values, 
       "date", "time" and "calendardate".  "Calendardate" 
       is the same as "date" except multiple dates are 
       expected for "calendardate", with each date on its 
       own line.  The data is validated and normalized. 
       If optional attribute dateformat= is present, then 
       the given format governs the field display.  For 
       instance, dateformat="MMM DD, YYYY". 

D = day with one digit for 1 to 9 
DD = day with two digits always 
DDD = three position day abbreviation: eg MON 
DDDD = fully spelled out day name 
M = month with one digit for 1 to 9 
MM = month with two digits always 
MMM = three postion month abbrev eg AUG 
MMMM = fully spelled out month 
YY = 2 digit year 
YYYY = 4 digit year

Note 1: < and & are never valid in an xml attribute. 
Because of the way the InterMix keyword parser works, 
only the following special characters are ok for 
use in an indextag or keyword attribute value: 
 
                 @#$%*-_=+/\ 

Similarly, for the value of a radio button or select 
list, stay away from special characters and from the 
use of character entities, such as &amp;.  The &amp; 
entity can be made to work for radio and select lists 
by always using the bare ampersand sign itself in the 
tagname, for instance: *[[%this_&_that%]]*, and using 
&amp; in the value="this_&amp;_that" specification. 
In the xml data, use this_&amp;_that for the default 
or you will run into an "XML format error 2". 

Note 2: All MiXml attribute names are lowercase. 

Note 3: Using the align attribute for tables in the 
DisplayHtml can make problems if the item is quoted. 

Note 4: Text or textarea fields that may include an 
email address or url may need a space in the 
display html before & after their *[[%tag%]]*. 

Note 5: Testing the form is easier if you set the 
required="yes" attributes last. 

Note 6: Text and textarea fields should generally be 
built with no whitespace (i.e. no carriage return/new 
lines or spaces or tabs) between the start tag and 
the end tag.  The reason for this is that whitespace for 
formatting purposes can be confused with leading or 
trailing whitespace that is data.