The XML files used to store our contact details are called address books. Here is an example
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 | <?xml version="1.0" encoding="UTF-8"?>
<addressbook name="Sample Address Book">
<person id="1" name="Sample Person">
<category>friend</category>
<name>
<first>Sample</first>
<surname>Person</surname>
</name>
<address>
12 Main Street
<city>Metropolis</city>
<state>Metropolis</state>
<postalcode>90210</postalcode>
<country>Australia</country>
</address>
<phone type="work">+61 9 1233 4555</phone>
<phone type="mobile">+61 400 133677</phone>
<email type="home">sample.person@gmail.com</email>
</person>
<person id="2" name="Second Person">
<name>
<first>Sample</first>
<surname>Person</surname>
</name>
</person>
<organisation id="3" name="A Company">
<category>work</category>
<name>A Company Pty Ltd</name>
<address>
123456 Adventure Boulevard
<city>Metropolis</city>
<state>Metropolis</state>
<postalcode>90000</postalcode>
<country>Australia</country>
</address>
<phone type="work">+61 9 1200 0000</phone>
<fax type="work">+61 9 1200 0001</fax>
<web type="work">http://www.acompany.com.au</web>
</organisation>
</addressbook>
|
This is the top level element in a whoswho file. There should only be one instance of this element in each address book file.
It must contain the “name” attribute. This will be used as the page title when generating an HTML representation.
Each addressbook element can contain 0, 1 or more person elements. Each addressbook element can contain 0, 1 or more organisation elements.
This element contains all of the details we want to record about an individual.
Each person element must have an “id” attribute and this value must be unique through all of your address books. Each person element may have a “name” attribute. This can be the commonly used name of the person rather than their full name that is recorded in the name element.
The first sub element of a person is 0, 1 or more category elements. These allow you to ‘tag’ the person with labels that can then be used in searches. You can use whatever text you like in category elements.
A person’s name is recorded in a specific element (with the tag “person”). Each person must have “first” and “surname” sub-elements. They can optionally have “title” and “middle” sub-elements as well. The simplest name will look like this:
<name>
<first>Andrew</first>
<surname>Todd</surname>
</name>
The full version will look something like this:
<name>
<title>Mr.</title>
<first>Andrew</first>
<middle>J.</middle>
<surname>Todd</surname>
</name>
The order of the sub-elements is important, they must be title (if used), then first, then middle (if used) and finally surname.
The simplest person entry will just have the name containing first and surname within the person element as shown in the first example above.
After a person’s name you can indicate where they work and their job title in a company element:
<company>
<name>Acme Corporation</name>
<role>Widget Wrangler</role>
</company>
The name sub-element is required but the role is optional.
You can then include a date-of-birth. The format of the text between these tags is up to you. There is no strict format enforced.
Next you can include an address For person elements you can only specify one address.
After the address you can have 0, 1 or more phone elements.
After phone numbers you can have 0, 1 or more instantmessage elements. The format of the text between these tags is up to you.
Next you can have 0, 1 or more email elements.
For nostalgia’s sake you can then have 0, 1 or more fax elements.
Then you can have 0, 1 or more web elements defining URLs associated with this person.
The last element is a notes tag. This can contain any text you would like to store about this person.
This element contains all of the details that we want to record about a company or other organisation.
Each organisation element must have an “id” attribute and this value must be unique amongst all person and organisation entries through all of your address books. Each organisation element may have a “name” attribute. This can be the commonly used name of the organisation rather than their full name that is recorded in the name element
The first sub element of an organisation is 0, 1 or more category elements. These allow you to ‘tag’ the organisation with labels that can then be used in searches. You can use whatever text you like in category elements.
The next sub element is the name. This is a simple tag (unlike the person name tag) and should just contain the organisation’s name between the tags.
Next comes the address of the organisation. Only one may be defined in this format.
After the address you can have 0, 1 or more phone elements.
Next you can have 0, 1 or more email elements.
For nostalgia’s sake you can then have 0, 1 or more fax elements.
Then you can have 0, 1 or more web elements defining URLs associated with this organisation.
The last element is a notes tag. This can contain any text you would like to store about this organisation.
All sub elements of an organisation are optional.
An address is a postal or street address identifying a location. The format is somewhat flexible but is mainly designed for UK, US or Australian addresses as these are the ones that I have the most experience with. Each of the sub elements is optional and if necessary you can put the full address as text between the start and end address tags.
The first part of the address should be stored as text immediately after the opening address tag. You can then add one or more of the following (optional) sub elements
- city (or town)
- state (or county)
- postalcode
- country
Simply put the appropriate contents between the start and end tags. There is no pre-determined format for the contents of any one.
You can place phone numbers for person or organisation entries between phone tags. There is no specific format required.
Each phone element must have a type attribute that is one of;
- home
- mobile
- work
A fax element is fundamentally the same as a phone element. It must also have a type attribute. For fax elements this must be one of;
- home
- work
An email element is a way of storing an email address. Just put the address as text between the start and end tags. It must also have a type attribute that is one of;
- home
- work
This element contains the URL of a web site associated with an address book entry.
The URL is contained between the start and end tags. It should usually refer to a web URL but there is no restriction on other types of address or prefixes such as ‘ftp’ or other web protocols. A web element must have a type attribute. It must be one of;
- personal
- work
The whoswho application has a module that you can use to validate your address books. Just run:
$ python validate_whoswho.py
This will validate the address books defined in your Configuration file and tell you if they are valid. If any address book fails validation the XML parser error messages will be displayed on the command line.
<?xml version="1.0" encoding="UTF-8"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0">
<start>
<element name="addressbook">
<attribute name="name" />
<optional>
<oneOrMore>
<element name="person">
<attribute name="id" />
<optional>
<attribute name="name" />
</optional>
<optional>
<oneOrMore>
<element name="category"><text /></element>
</oneOrMore>
</optional>
<element name="name">
<group>
<optional>
<element name="title"><text /></element>
</optional>
<element name="first"><text /></element>
<optional>
<element name="middle"><text /></element>
</optional>
<element name="surname"><text /></element>
</group>
</element>
<optional>
<element name="company">
<group>
<element name="name"><text /></element>
<optional>
<element name="role"><text /></element>
</optional>
</group>
</element>
</optional>
<optional>
<element name="date-of-birth"><text /></element>
</optional>
<optional>
<ref name="address" />
</optional>
<optional>
<oneOrMore>
<ref name="phone" />
</oneOrMore>
</optional>
<optional>
<oneOrMore>
<element name="instantmessage"><text /></element>
</oneOrMore>
</optional>
<optional>
<oneOrMore>
<ref name="email" />
</oneOrMore>
</optional>
<optional>
<oneOrMore>
<ref name="fax" />
</oneOrMore>
</optional>
<optional>
<oneOrMore>
<ref name="web" />
</oneOrMore>
</optional>
<optional>
<element name="notes"><text /></element>
</optional>
</element>
</oneOrMore>
</optional>
<optional>
<oneOrMore>
<element name="organisation">
<attribute name="id" />
<optional>
<attribute name="name" />
</optional>
<optional>
<oneOrMore>
<element name="category"><text /></element>
</oneOrMore>
</optional>
<optional>
<element name="name"><text /></element>
</optional>
<optional>
<ref name="address" />
</optional>
<optional>
<oneOrMore>
<ref name="phone" />
</oneOrMore>
</optional>
<optional>
<oneOrMore>
<ref name="email" />
</oneOrMore>
</optional>
<optional>
<oneOrMore>
<ref name="fax" />
</oneOrMore>
</optional>
<optional>
<oneOrMore>
<ref name="web" />
</oneOrMore>
</optional>
<optional>
<element name="notes"><text /></element>
</optional>
</element>
</oneOrMore>
</optional>
</element>
</start>
<define name="address">
<element name="address">
<text />
<optional>
<choice>
<element name="city"><text /></element>
<element name="town"><text /></element>
</choice>
</optional>
<optional>
<choice>
<element name="state"><text /></element>
<element name="county"><text /></element>
</choice>
</optional>
<optional>
<element name="postalcode"><text /></element>
</optional>
<optional>
<element name="country"><text /></element>
</optional>
</element>
</define>
<define name="phone">
<element name="phone">
<attribute name="type">
<choice>
<value>home</value>
<value>mobile</value>
<value>work</value>
</choice>
</attribute>
<text />
</element>
</define>
<define name="fax">
<element name="fax">
<attribute name="type">
<choice>
<value>home</value>
<value>work</value>
</choice>
</attribute>
<text />
</element>
</define>
<define name="email">
<element name="email">
<attribute name="type">
<choice>
<value>home</value>
<value>work</value>
</choice>
</attribute>
<text />
</element>
</define>
<define name="web">
<element name="web">
<attribute name="type">
<choice>
<value>personal</value>
<value>work</value>
</choice>
</attribute>
<text />
</element>
</define>
</grammar>