XML Template
NOTE: The information in this section will be most useful to advanced MindModel users.
An XML Template is an XML file used to customize some aspect of a MindModel feature.
"XML" stands for "eXtensible Markup Language".
A discussion of XML's features and rules is beyond the scope of this documentation. There are many good XML references available, both on the Web and in print.
Note for power-users: The root XML elements in XML Templates use the tag "<mmxml>", so you may hear us refer to XML Templates as "<mmxml> elements" in various places in this documentation.
Another note for power-users: After you've read this section, if you'd like more information on <mmxml>, you can refer to the section: Key Concepts: <mmxml> Reference.
Why do I have to learn XML?
You may wonder why we've included XML features in MindModel. MindModel's goal is to empower non-programmers to be able to create relational databases, so why bring a programmer's tool such as XML into MindModel?
First of all, you can create complex and powerful relational databases without using MindModel's XML features.
However, some users need to be able to create reports, emails, or displays that contain precisely the information those users need to see. For MindModel to create these reports, the user has to specify exactly which information should be included, and in what order.
XML Templates are a straightforward way to tell MindModel which information you want to see in your reports. XML Templates may have many parts, but only as many as MindModel needs to know what you want in your reports.
Why can't you create a graphical user-interface (GUI) for the templates?
If we were to create a graphical user-interface (windows, icons, etc.) for creating the templates, the process would be more confusing than XML. For example, what kind of icon could we use to indicate an object noun? How about a statement type?
So if we're not going to create a graphical user-interface for our templates, they will have to be based on some sort of text file.
If we're going to base our templates on text files, we could create our own language, or we could use XML, which is the global standard for doing the sort of job we need to do.
So if you already know XML, you're on your way to creating XML Templates. If you don't know XML, at least you'll be learning a skill that you can use outside of MindModel.
So how much XML will I have to learn?
Not much. If you keep the following three XML rules in mind, you'll be most of the way there.
1) Your XML Template must begin with an XML declaration
such as:
<?xml version="1.0" encoding="utf-8"?>
2) All nested elements must be properly nested
so:
<a>parent<b>child</b></a>
is acceptable
but:
<a>parent<b>child</a></b>
is not.
By "nested elements" we mean elements within elements.
"<a>parent</a>" is an element.
"<a>" and "</a>" are called "tags". The whole thing is called an "element".
"<b>child</b>" is also an element.
"<a>parent<b>child</b></a>" is called a nested element because the "child" element is within the "parent" element.
"<a>parent<b>child</b></a>" is legal XML because the "child" element is completely within the "parent" element. The tags of one element don't cross the tags of another element.
"<a>parent<b>child</a></b>" is not legal XML, because the closing tag of the parent element ("</a>") interrupts the child element.
So a pattern like "abba" is OK, but "abab" is not.
3) Case matters
so:
<a>parent</a>
is not the same as:
<A>parent</A>
Is there any way I can make the process of learning XML easier?
Yes, there is.
Don't try to learn everything there is to learn about XML. Don't even try to learn everything XML can do. Just focus on learning enough to get the job done. If you're still interested, you can learn more later.
For example, it should take less than an hour for someone who knows XML to explain enough about XML to an experienced computer user so he or she can start creating XML Templates.
How long it will take before that person is creating useful XML Templates on his or her own depends on that person's comfort level with XML and the MindModel Grammar.
For example, if you are completely comfortable using MindModel's "File Menu: Import Statements from Excel by Column" command, you won't have too much trouble creating XML Templates.
What if I get stuck?
As with anything else, if you've done your homework (read the MindModel documentation, read an XML tutorial book or web site, asked a friend) and you're still stuck, feel free to contact us and we'll be happy to help you.
Once I learn how to create XML Templates, what can I do with them?
1) You can use XML Templates to customize the Noun Summary Window.
2) You can use XML Templates to create reports with these commands:
Reports Menu: Create Report for Selected Noun from XML Template
Reports Menu: Create Report for Nouns in the Nouns List from XML Template
3) You can print custom mailing labels using:
Reports Menu: Mailing Labels via XML Template
4) You can send customized emails using these commands:
Email Menu: Send Email to Members of a Collection via Outlook
Email Menu: Send Email to Members of a Collection via SMTP
5) You can create your own checklist templates for this command:
Nouns Menu: Add Statement for Selected Noun via Checklist
6) You can create Model Summary Window Templates (MSWT's) to customize the Model Summary Window.
The Model Summary Window is a very powerful MindModel feature that can display reports with a wide variety of formats and contents.
OK, I'm ready. I know the basics of XML. How do I create an XML Template?
Let's take a look at a simple XML Template, so we can understand how it works.
Before we look at the XML Template, though, let's take a quick look at the output it produces, so we know what we're trying to accomplish.
The picture above shows the Noun Summary Window.
The user has added an XML Template to the Noun Summary Window, and has selected the XML Template.
How do I add an XML Template to the Noun Summary Window?
To add an XML Template to the Noun Summary Window, click on the small black triangle in the upper left-hand corner of the window. When you click the arrow, MindModel displays a menu which allows you to add, delete, or choose an XML Template.
The following picture shows the drop-down menu that appears when you click the black triangle.
The top part of the menu (above the line) allows you to add or delete an XML Template.
The bottom part of the menu (below the line) allows you to choose one of the XML Templates you've added, or choose not to use an XML Template.
The menu pictured above mentions a "Summary Window Template". What's the difference between an XML Template and a Summary Window Template?
A Summary Window template is an XML Template that has been added to the Summary Window using this menu.
There are other uses for XML Templates other than as Summary Window Templates. For example, you can use XML Templates to create mailing labels, reports, or emails. In this section, we show you how to use XML Templates to customize the Summary Window.
So what should I be looking at in the picture of the Noun Summary Window?
When you look at the picture of the Noun Summary Window, you'll see that the window shows the name, phone number and email address for Kent Ortiz, as well as his languages, skills, and the software packages he knows how to use.
MindModel chooses which information to display in the Noun Summary Window based on the contents of the selected XML Template.
In this section of the documentation, you're learning how to create your own XML Templates, so you can customize the Noun Summary Window and other MindModel features.
The XML Template
The following text shows the contents of the "employee summary" XML Template.
If you'd like to work with a copy of this XML Template, you can use the "Templates Menu: Export Summary Window Template to a Text File" command to do so.
First, open the "AcmeTech.min" sample model (located in the "C:\Program Files\MindModel\Sample Models" folder), then choose "Export Summary Window Template to a Text File" from the Templates Menu. When MindModel asks which Summary Window template to export, choose "people: employee summary".
The Contents of the XML Template
<?xml version="1.0" encoding="utf-8"?>
<mmxml>
<title>employee summary</title>
//
// this is the definition section
//
<definition>
<name>bizPhone</name>
<operator>statementNoun</operator>
<anchor>subject</anchor>
<target>object</target>
<statementPattern>person|has the business phone number|business phone number</statementPattern>
<showStaticIfBlank>(none)</showStaticIfBlank>
</definition>
<definition>
<name>email</name>
<operator>statementNoun</operator>
<anchor>subject</anchor>
<target>object</target>
<statementPattern>person|has the email address|email address</statementPattern>
<showStaticIfBlank>(none)</showStaticIfBlank>
</definition>
<definition>
<name>skills</name>
<operator>statementNounList</operator>
<anchor>subject</anchor>
<target>object</target>
<statementPattern>person|has the skill|skill</statementPattern>
<between>,#nbsp#</between>
<showStaticIfBlank>(none)</showStaticIfBlank>
</definition>
<definition>
<name>software</name>
<operator>statementNounList</operator>
<anchor>subject</anchor>
<target>object</target>
<statementPattern>person|knows how to use|software package</statementPattern>
<between>,#nbsp#</between>
<showStaticIfBlank>(none)</showStaticIfBlank>
</definition>
<definition>
<name>languages</name>
<operator>statementNounList</operator>
<anchor>subject</anchor>
<target>object</target>
<statementPattern>person|speaks the language|language</statementPattern>
<between>,#nbsp#</between>
<showStaticIfBlank>(none)</showStaticIfBlank>
</definition>
//
// this is where we produce the report.
//
<value>
<operator>concatenate</operator>
<value>
<operator>nounName</operator>
<after>#newline#</after>
</value>
<value>
<name>bizPhone</name>
<operator>definedInXML</operator>
<before>phone:#nbsp#</before>
<after>#newline#</after>
</value>
<value>
<name>email</name>
<operator>definedInXML</operator>
<before>email:#nbsp#</before>
<after>#newline#</after>
</value>
<value>
<operator>staticText</operator>
<before>#newline#</before>
<after></after>
</value>
<value>
<name>languages</name>
<operator>definedInXML</operator>
<before>languages:#nbsp#</before>
<after>.#newline#</after>
</value>
<value>
<name>skills</name>
<operator>definedInXML</operator>
<before>skills:#nbsp#</before>
<after>.#newline#</after>
</value>
<value>
<name>software</name>
<operator>definedInXML</operator>
<before>software:#nbsp#</before>
<after>.#newline#</after>
</value>
</value>
</mmxml>
What the heck was all that?
Let's take the XML Template apart piece by piece, and you'll see that it makes sense.
You may want to print out the previous section containing the XML Template, so you an refer to it as we discuss its individual parts.
The XML Declaration
The XML Template begins with an XML declaration, which looks like this:
<?xml version="1.0" encoding="utf-8"?>
The XML declaration tells MindModel that the template is an XML file.
XML Templates must begin with an XML declaration.
The <mmxml> Element
The rest of the XML Template (after the XML declaration) is enclosed in a pair of <mmxml></mmxml> tags.
This element tells MindModel that the XML is XML that MindModel can understand.
XML Templates must contain an <mmxml> element.
The Title Element
The next element is the title element, which looks like this:
<title>employee summary</title>
The title element tells MindModel which title to display when referring to this XML Template.
In our example, MindModel displays "employee summary" as the title of the XML Template when displaying the drop-down menu pictured earlier in this section.
XML Templates must contain a <title> element.
The Definition Section
The next section of the XML Template contains five <definition> elements.
Definition elements are optional in XML Templates. You can use them, but they are not required.
Definition elements allow you to define and name your own macros, which you can then refer to later in the XML Template.
An Example of a Definition Element
Let's take a look at the first <definition> element in our XML Template:
<definition>
<name>bizPhone</name>
<operator>statementNoun</operator>
<anchor>subject</anchor>
<target>object</target>
<statementPattern>person|has the business phone number|business phone number</statementPattern>
<showStaticIfBlank>(none)</showStaticIfBlank>
</definition>
The <name> element of the <definition> element provides the name that you will use when referring to the macro later in the XML Template. This element is named "bizPhone" because it defines the person's business phone number.
The next element is the <operator> element.
MindModel provides many options for the different types of information you can display using an XML Template. The <operator> element allows you to specify which type of information you want to display.
The "statementNoun" Operator
The value for this <operator> element is "statementNoun".
The "statementNoun" operator is used when you want to display the name of a noun related to the current noun by the fact that they occur in the same statement.
In our example, the "current noun" is the noun selected in the Nouns List. This is the noun which is being summarized in the Noun Summary Window.
There is a statement in the AcmeTech.min sample model that reads:
person: Kent Ortiz <has the business phone number> business phone number: 216-111-0601
If you look back at the picture of the Noun Summary Window above (showing the summary of Kent Ortiz), you'll see this phone number displayed there.
Kent Ortiz is our current noun.
Our goal is to define a macro that allows us to return the business phone number of the current noun.
We know that the current noun (Kent Ortiz) and our target (business phone number: 216-111-0601) are found in the statement:
person: Kent Ortiz <has the business phone number> business phone number: 216-111-0601
So we create a <definition> element named "bizPhone" which uses the "statementNoun" operator to return the phone number.
The rest of the contents of the <definition> element provide the remaining details we need to return that phone number.
Let's take a look at those other elements.
The <anchor> Element
The <anchor> element tells MindModel which part of the statement contains the current noun (Kent Ortiz).
The current noun could be the subject, the object, or the object of a preposition in the statement.
In our case, the current noun is the subject, since Kent Ortiz is the subject of the statement:
person: Kent Ortiz <has the business phone number> business phone number: 216-111-0601
We use the word "anchor" because the current noun anchors the statement, like a boat anchor does for a boat.
So now MindModel knows that we want to define a macro called "bizPhone", that we want a noun from a statement, and that the current noun is the subject of that statement.
The <target> Element
The next thing MindModel needs to know is which part of the statement will be returned by the macro.
Since the anchor is the subject, the part of the statement returned by the macro in our case will be the object.
So the <target> element reads:
<target>object</target>
The <statementPattern> Element
MindModel needs to know one more thing about the statement, its statement type.
All statements about business phone numbers are of the type:
person|has the business phone number|business phone number
so the <statementPattern> element reads:
<statementPattern>person|has the business phone number|business phone number</statementPattern>
Now MindModel knows all it needs to know to find and display Kent Ortiz's business phone number.
The <showStaticIfBlank> Element
The remaining element, <showStaticIfBlank>, is optional.
The element:
<showStaticIfBlank>(none)</showStaticIfBlank>
tells MindModel to display the word "(none)" if there is no business phone number for Kent Ortiz.
Huh?
We realize that this section of the documentation contains quite a bit of new information, which may be confusing at first.
Take your time and read through it. Once you understand how it works, you'll see that it's not as complicated as it appeared to be when you first encountered it.
If you've read through this section carefully, and it still doesn't make sense, feel free to contact us and we'll be happy to answer any questions you may have.
The Next Definition Element
The next definition element ("email") is similar to the first one ("bizPhone") but with different details.
The "email" element defines a macro which returns the email address of the current noun.
Notice which elements of the "email" definition are the same as the previous definition, and which are different.
<definition>
<name>email</name>
<operator>statementNoun</operator>
<anchor>subject</anchor>
<target>object</target>
<statementPattern>person|has the email address|email address</statementPattern>
<showStaticIfBlank>(none)</showStaticIfBlank>
</definition>
You'll notice that the <name> and <statementPattern> elements are different from the corresponding elements in "bizPhone". The other elements are the same in both definitions.
The "statementNounList" Operator
The next definition element ("skills") introduces a new operator: statementNounList.
<definition>
<name>skills</name>
<operator>statementNounList</operator>
<anchor>subject</anchor>
<target>object</target>
<statementPattern>person|has the skill|skill</statementPattern>
<between>,#nbsp#</between>
<showStaticIfBlank>(none)</showStaticIfBlank>
</definition>
What does the statementNounList operator do?
The "statementNounList" operator is similar to the "statementNoun" operator.
The difference is that "statementNoun" returns the name of a single noun, and "statementNounList" returns a list of noun names.
For example, in MindModel each person can have up to one email address, but each person can have many skills.
If you search the AcmeTech.min sample model, you'll find the following statements for Kent Ortiz:
person: Kent Ortiz <has the skill> skill: financial reporting
person: Kent Ortiz <has the skill> skill: Red Cross C.P.R.
Since we want to display more than one noun ("financial reporting" and "Red Cross C.P.R.") we use the "statementNounList" operator instead of the "statementNoun" operator.
The <anchor>, <target> and <showStaticIfBlank> elements are similar to those in the previous definitions, so we won't explain them again here.
The <between> Element
The <between> element is new, however.
This operator allows you to specify which characters you want to see between the noun names in the list.
The ",#nbsp#" means that you want to see a comma and a space between each noun name.
We use "#nbsp#" (which stands for "non-breaking space") instead of just putting a space (" ") there, because XML ignores spaces in element values.
The next two definition elements ("software" and "languages") are similar to "skills" but with different statement types, so we won't discuss them in detail.
The Value Section
If you've made it this far in this section, and you've understood what you've read, you're almost there.
The next section of the XML Template contains one <value> element, with many sub-parts (one <operator> and seven <value> elements).
The value section is where we actually produce the results of the XML Template.
You can have as many <definition> elements in your XML Template as you want. You can choose to use all of them in your value section, or you can choose to use none of them.
No matter how many <definition> elements your XML Template contains, it will not produce any results unless you have a <value> section.
The <value> section in our example uses the "concatenate" operator.
The "concatenate" Operator
The concatenate operator allows you to append the results of a number of <value> elements into one result.
So, in our example, each of the seven <value> elements in the <value> section produces a result.
Each result is appended to the next one, to produce the noun summary seen in the picture below.
This picture is identical to the one earlier in this section. It is repeated here for your reference.
As you look at the picture, you can see how the seven <value> elements correspond to the seven sections of the noun summary:
1) name
2) business phone
3) email
4) blank line
5) languages
6) skills
7) software
Let's take a look at each of the seven sections.
1) name
The name section looks like this:
<value>
<operator>nounName</operator>
<after>#newline#</after>
</value>
The "nounName" operator tells MindModel to return the name of the current noun as the result of this <value> element.
2) business phone
The business phone section looks like this:
<value>
<name>bizPhone</name>
<operator>definedInXML</operator>
<before>phone:#nbsp#</before>
<after>#newline#</after>
</value>
The <name> element tells MindModel which <definition> to use, in this case "bizPhone".
You'll remember that the "bizPhone" definition looks like this:
<definition>
<name>bizPhone</name>
<operator>statementNoun</operator>
<anchor>subject</anchor>
<target>object</target>
<statementPattern>person|has the business phone number|business phone number</statementPattern>
<showStaticIfBlank>(none)</showStaticIfBlank>
</definition>
The "definedInXML" Operator
The <operator>definedInXML</operator> element tells MindModel that "bizPhone" is defined in the XML Template.
The <before> Element
The <before>phone:#nbsp#</before> element tells MindModel to add the word "phone: " before the value returned by the "bizPhone" definition.
If you look at the picture of the Noun Summary Window above, you'll see the word "phone: " before the phone number.
Remember that "#nbsp#" tells MindModel to add a space to the results.
The <after> Element
The <after>#newline#</after> element tells MindModel to start a new line after the phone number. If we didn't include this <after> element, the email address would end up on the same line as the phone number, which would make the summary difficult to read.
3) email
The email section looks like this:
<value>
<name>email</name>
<operator>definedInXML</operator>
<before>email:#nbsp#</before>
<after>#newline#</after>
</value>
The email section works basically the same way as the business phone section described above, so we won't go into detail about the email section.
4) blank line
The blank line section looks like this:
<value>
<operator>staticText</operator>
<before>#newline#</before>
<after></after>
</value>
The <operator>staticText</operator> element means that this <value> element always returns the same value.
The value it returns is the contents of the <before> element, followed by the contents of the <after> element.
In this case, the <before> element is a new line, and the <after> element is blank.
So this section produces a blank line.
5) languages
The languages section looks like this:
<value>
<name>languages</name>
<operator>definedInXML</operator>
<before>languages:#nbsp#</before>
<after>.#newline#</after>
</value>
Since "languages" is defined in the XML Template, we use <operator>definedInXML</operator> here.
The <name> element gives the name of the "languages" definition, which you'll remember looks like this:
<definition>
<name>languages</name>
<operator>statementNounList</operator>
<anchor>subject</anchor>
<target>object</target>
<statementPattern>person|speaks the language|language</statementPattern>
<between>,#nbsp#</between>
<showStaticIfBlank>(none)</showStaticIfBlank>
</definition>
6) skills
The skills section works basically the same way as the languages section described above, so we won't go into any more detail about the skills section.
7) software
The software section works basically the same way as the skills section and the languages section.
That's It!
You may find it helpful to export the XML Template discussed in this example.
You can use the "Templates Menu: Export Summary Window Template to a Text File" command.
The XML Template in this example is called "people: employee summary".
Then try modifying parts of the XML Template, and add it to the Noun Summary Window.
Remember, you'll click the triangle in the upper left-hand corner of the window to display the menu, then choose "Add a Summary Window Template for People" to add the XML Template to the model.
As always, read the documentation first, try it out, and if you get stuck, contact us.