Define Your Application's New Data Model

Table of Contents Overview LandscapeGuide's Basic Types Define the Data Types in XSD Modify SchemaLoader Generate a Schema Stub Class File Topics in this section

Overview

Most applications have a data model, because a typical application allows a user to create, modify, and save some kind of data, whether it's plain text or graphic objects in a scene. If your application works with data, you need to define its data model, that is, specify the types of the data it uses. The new LandscapeGuide application allows a user to enter data, so this is a necessary step.

ATF provides a Document Object Model (DOM) framework for managing application data. For details of using the ATF DOM, see the ATF Programmer's Guide: Document Object Model (DOM), downloadable from ATF Documentation.

In ATF, the simplest way to define the data model is to create a type definition file in the XML Schema Definition (XSD) language (or XML schema for short), because ATF provides built-in support for XSD. SimpleDomEditor uses XSD and provides its type definition in the eventSequence.xsd schema file, and LandscapeGuide also takes this approach.

If you are not familiar with XSD, see the W3 Schools tutorial at http://www.w3schools.com/schema/.

LandscapeGuide's Basic Types

Define LandscapeGuide's data model by specifying the data types it uses. LandscapeGuide uses mainly two kinds of data objects: plant and ornamentation items. Both these items have attributes associated with them: a name, notes, and rating, and each type has distinct attributes as well. These items are similar enough that they can be considered variants of a single type. Because these types have attributes, they are complex types.

Applications often have a data type that represents a collection of data items in the application. In this case, a second data type represents a list of plant and ornamentation items, which display in a list view. This type is also complex, since it has child items.

Define the Data Types in XSD

The next step is to formally define the types in XSD in a type definition file, items.xsd. The following describes each section of this file.

First, set the namespace for the schema:

<xs:schema
  elementFormDefault="qualified"
  targetNamespace="itemList_1_0"
  xmlns="itemList_1_0"
  xmlns:xs="http://www.w3.org/2001/XMLSchema">

The following simple type defines an integer between 1 and 10, which describes the rating attribute of an item:

<!--Simple type for number in a range-->
<xs:simpleType name="ratingType">
  <xs:restriction base="xs:integer">
    <xs:minInclusive value="1"/>
    <xs:maxInclusive value="10"/>
  </xs:restriction>
</xs:simpleType>

The "ratingType" type places restrictions on the minimum and maximum bounds for an integer of this type.

Both plant and ornamentation items are items, so define an abstract "itemType" that fits both, containing their common attributes. This subtype approach simplifies development.

<!--Abstract base type for items-->
<xs:complexType name="itemType" abstract="true">
  <xs:attribute name="name" type="xs:string" use="required"/>
  <xs:attribute name="notes" type="xs:string"/>
  <xs:attribute name="rating" type="ratingType" default="5"/>
</xs:complexType>

The three common item attributes are defined here. Note that the type of the "rating" attribute is "ratingType", defined above. The "rating" attribute also has a default value of 5.

Now that the general "itemType" for an item has been defined, specify its subtypes, first plant:

<!--Plant, with botanical name and other attributes-->
<xs:complexType name ="plantItemType">
  <xs:complexContent>
    <xs:extension base="itemType">
      <xs:attribute name="botanicalName" type="xs:string"/>
    </xs:extension>
  </xs:complexContent>
</xs:complexType>

The type "plantItemType" extends "itemType", adding the "botanicalName" attribute. Next, ornamentation:

<!--Ornamentation, with color and other attributes-->
<xs:complexType name ="ornamentationItemType">
  <xs:complexContent>
    <xs:extension base="itemType">
      <xs:attribute name="color" type="xs:string"/>
    </xs:extension>
  </xs:complexContent>
</xs:complexType>

The "ornamentationItemType" type extends "itemType", adding the "color" attribute.

Finally, the item list:

<!--Landscape item list, a list of items-->
<xs:complexType name ="itemListType">
  <xs:sequence>
    <xs:element name="item" type="itemType" maxOccurs="unbounded"/>
  </xs:sequence>
</xs:complexType>

Note that this type contains "itemType" children — not "plantItemType" or "ornamentationItemType". It allows an unlimited number of children.

The ATF DOM stores application data in a tree of nodes, and each node has a type that is one of the data model's defined types. You can specify the root node of this tree, which is of "itemListType" type:

<!--Declare the root element of the document-->
<xs:element name="itemList" type="itemListType"/>

As you are defining types, you can either edit the existing file eventSequences.xsd and rename it items.xsd, or remove eventSequence.xsd and add the new one, items.xsd.

Make sure that items.xsd has these properties set, especially if you add a new file:

• Build Action: Embedded Resource
• Copy to Output Directory: Copy if newer

These are not the default values for an added file, so you must set them. The schema file must be embedded in the application. Otherwise the application gets an exception when it tries to load the schema file.

Modify SchemaLoader

Now that you have created a new schema file items.xsd, modify the SchemaLoader to load it:

public SchemaLoader()
{
    // set resolver to locate embedded .xsd file
    SchemaResolver = new ResourceStreamResolver(Assembly.GetExecutingAssembly(), "LandscapeGuide/schemas");
    Load("items.xsd");
}

Generate a Schema Stub Class File

Given a type definition file in XML schema, the ATF DomGen utility generates a stub class that defines the metadata classes for the data types. Using this stub class, conventionally called Schema, allows you to avoid using string names for types and attributes from the type definition file and instead use the DomGen generated names. This allows the compiler to check for name correctness.

The easiest way to run DomGen is from the Schema/GenSchemaDef.bat file. Edit this file to something like this, and then run it:

{source} \DomGen.exe items.xsd Schema.cs "itemList_1_0" LandscapeGuide {source}

These parameters provide the input file items.xsd, the output file Schema.cs, the XML target namespace of the types within the schema "itemList_1_0", and the C# namespace "LandscapeGuide".

The type and attribute names in Schema.cs determine many of the changes you need to make in your application, because the type and attribute names are frequently used.

Topics in this section