Chapter 5: Using XML to Set Parameters

5.1 XML as a Way to Represent Hierarchies

AspGrid's object model has a hierarchical structure. Writing ASP code for AspGrid is essentially describing a hierarchy: we set certain properties for the top-level object (Grid), then for the second-level objects such as Table and Column, then for the third-level objects (Cell, Header and Footer), etc.

There is a language (or strictly speaking, meta-language) that, among other things, was designed to describe hierarchical information. This language is, of course, XML (Extensible Markup Language).

Consider the following ASP code:

Grid.CanEdit = False
Grid.Cols(1).CanSort = True
Grid.Cols(1).Cell.BGColor = "#FF0000"
Grid.Cols(1).Cell.Font.Face = "Couirer"
Grid.Cols(1).Cell.Font.Size = "2"

Now, the same information XML-style (notice how child objects are represented by nested XML tags):

In case you have not mastered XML yet, here are a few important things to know about an XML document:

You can make up your own tags.
Every opening tag requires a matching closing tag.
If an element has no content (such as <FONT> is the above example), the opening and closing tags may be combined into a single "shortcut" tag such as <TAG/>.
XML is case-sensitive.
The character " (double quote) in a string constant must be denoted as ".
An XML document may be subject to a set of rules called "document type definition" (DTD). More about it later.

5.2 Using XML with AspGrid

If you use XML to set AspGrid parameters, your ASP script can be reduced to as little as 3 lines of code:

<%
Set Grid = Server.CreateObject("Persits.Grid")
Grid.LoadParameters "params.xml"
Grid.Display
%>

The XML approach has the following advantages over the traditional script-based approach:

Cleaner, simpler code. Your AspGrid-related scripts will only contain 3 lines of code instead of potentially dozens of lines.
Reusability. You can place your favorite color/font scheme in an XML file and re-use it from multiple ASP scripts.
Simplified deployment and maintenance. Several servers may share a single XML file. Changes in that file will immediately propagate to all servers at once.
More intuitive development. Instead of VB script, you will be dealing with tags and attributes which you may find more intuitive.
Use an XML editor of your choice. You are no longer tied to a development environment such as VID. Use any XML editor you want.

5.3 ASP-XML "Rosetta Stone"

The Rosetta Stone is a stone slab on which parallel inscriptions in Egyptian hieroglyphic, Greek and demotic characters were found, making possible the decipherment of ancient hieroglyphics.

We will use the Rosetta Stone approach to demonstrate the usage of XML for setting AspGrid parameters. The table below presents the ASP code sample which we examined in the previous chapter, and its XML equivalent, shown side by side. This XML document used in this sample can be found in the file \Samples\05_xml\employees.xml. Click here to view it.

ASP

XML

Set Grid = Server.CreateObject("Persits.Grid")

<Grid>

Grid.SQL = "select id, dept_id, name, salary,
hiredate, maritalstatus, fullyvested from employees"

<SQL>select id, dept_id, name, salary,
hiredate, maritalstatus, fullyvested from employees</SQL>

Grid("id").Hidden = True

Grid("dept_id").AttachForeignTable "select id, name from departments", 1, 2
Grid("dept_id").Caption = "Department"

<Cols Index="dept_id">
<AttachForeignTable SQL="select id, name from departments" KeyCol="1" DispCol="2"/>
<Caption>Department</Caption>
</Cols>

Grid("name").Caption = "Full Name"

Grid("salary").Caption = "Salary"
Grid("salary").FormatNumeric 2, True, True, True, "$"
Grid("salary").Cell.Align = "RIGHT"

<Cols Index="salary">
  <FormatNumeric Decimal="2" Prefix="$"/>
  <Caption>Salary</Caption>
  <Cell Align="RIGHT"/>
</Cols>

Grid("hiredate").FormatDate "%b %d, %Y" ' Mon DD, YYYY
Grid("hiredate").Caption = "Hire Date"
Grid("hiredate").DefaultValue = CDate("5/18/2000")

Grid("maritalstatus").Array = Array("Single", "Married", "Divorced")
Grid("maritalstatus").VArray = Array(3, 2, 1)
Grid("maritalstatus").Caption = "Marital Sts"

<Cols Index="maritalstatus">
  <Array>
    <Item Value="Single" DBValue="3"/>
    <Item Value="Married" DBValue="2"/>
    <Item Value="Divorced" DBValue="1"/>
  </Array>
  <Caption>Marital Sts</Caption>
</Cols>

Grid("fullyvested").Caption = "Vested"
Grid("fullyvested").AttachCheckbox "Yes", "No"

<Cols Index="fullyvested">
<AttachCheckbox Checked="Yes" Unchecked="No"/>
<Caption>Vested</Caption>
</Cols>

Grid(0).Header.BGColor = "#B0B0FF"

Grid(999).Header.BGColor = "#B0B0FF"

Grid.ColRange(2, 7).CanSort = True
Grid.ColRange(2, 7).Header.BGColor = "#B0B0FF"
Grid.ColRange(2, 7).Header.Font.Face = "Arial Narrow"
Grid.ColRange(2, 7).Cell.Font.Face = "Arial Narrow"
Grid.ColRange(2, 7).InputSize = 10

Grid.ImagePath = "../images/"

<ImagePath>../images/</ImagePath>

Grid.ShowLeftSideButtons

Grid.Table.CellSpacing = 0
Grid.Table.CellPadding = 1

Grid.Table.Caption = "Employees"
Grid.Table.Caption.Font.Face = "Arial"
Grid.Table.Caption.Font.Bold = True

</Table>

Set Grid = Nothing

</Grid>

Here is what the file

http://localhost/aspgrid/Samples/05_xml/employees_xml.asp

looks like:

<%
' Build connection string to aspgrid.mdb
strConnect = "DRIVER={Microsoft Access Driver (*.mdb)};DBQ=" &_
Server.MapPath("..\db\aspgrid.mdb")

' Create instance 2 of AspGrid for the Employees table
Set Grid = Server.CreateObject("Persits.Grid")

' Connect
Grid.Connect strConnect, "", ""

' Load parameters from XML file
Grid.LoadParameters Server.MapPath("employees.xml")

' Display grid
Grid.Display

Grid.Disconnect
%>

There is a few things worth noting:

Not every AspGrid expression has an XML equivalent. Methods and properties such as Grid.Display, Grid.BuildForm, Grid.Disconnect, Grid.Connection and Grid.Recordset must be explicitly called by ASP script.
Dynamic expressions also need to be specified by ASP code and not XML. In our code sample we call the Connect method explicitly because one of its arguments is computed dynamically.
The LoadParameters method can be called multiple times on different XML files within the same ASP script.

5.4 Playing by the Rules - the DTD

The sample XML file employees.xml starts with the following two lines:

<?xml version="1.0"?>
<!DOCTYPE Grid SYSTEM "AspGrid.dtd">

The first line identifies the version of the XML specification to which this document conforms.

The second line points to a file that contains the Document Type Definition (DTD) for this XML document. Essentially, this line says: "I am an XML document that conforms to the rules set forth in the file AspGrid.dtd."

What rules are those? The DTD describes what the root element of the XML document should be (<Grid> in our case), what attributes are allowed for this element, and among those, which are required and which are optional. Also it describes the sub-elements for the root element, in what order they must appear, and, of course, their own attributes and sub-elements.

When are these rules enforced, and by whom? AspGrid internally uses the Microsoft XML processor, msxml.dll, that comes with IE 5.0. When your script calls LoadParameters, this method passes the specified XML document to msxml. The XML processor then parses the document and compares it against the file AspGrid.dtd to see if all the rules are conformed to. If not, an error will be thrown similar to this:

Persits.Grid.1 (0x800A002C)
XML Parse Error: Element content is invalid according to the DTD/Schema. Expecting: Cols, ColRange, DeleteButtonOnClick, ExtraFormItems, FileName, FormOnSubmit, ImagePath, SaveButtonOnClick, SQLAfterDelete, SQLAfterInsert, SQLAfterUpdate, SQLBeforeDelete, SQLBeforeInsert, SQLBeforeUpdate, ShowLeftSideButtons, Table. Source: file:///D:/MyProjects/AspGrid3/samples/05_xml/employees.xml. Line 8

This is what the beginning of the AspGrid.dtd file looks like:

<!ELEMENT Grid (Connect?, SQL?, Cols*, ColRange*,
   DeleteButtonOnClick?, ExtraFormItems?, FileName?,
   FormOnSubmit?, ImagePath?, SaveButtonOnClick?,
   SQLAfterDelete?, SQLAfterInsert?, SQLAfterUpdate?,
   SQLBeforeDelete?, SQLBeforeInsert?, SQLBeforeUpdate?,
   ShowLeftSideButtons?, Table?)>
<!ATTLIST Grid CanAppend CDATA #IMPLIED>
<!ATTLIST Grid CanDelete CDATA #IMPLIED>
<!ATTLIST Grid CanEdit CDATA #IMPLIED>
<!ATTLIST Grid MaxRows CDATA #IMPLIED>
<!ATTLIST Grid MethodGet CDATA #IMPLIED>
<!ATTLIST Grid NumberOnPage CDATA #IMPLIED>
<!ATTLIST Grid ReadOnly CDATA #IMPLIED>
<!ATTLIST Grid ShowHeader CDATA #IMPLIED>
<!ATTLIST Grid UseImageButtons CDATA #IMPLIED>

This portion of the DTD file states that the root element of our XML file (<Grid>) accepts the following optional attributes: CanAppend, CanDelete, CanEdit, MaxRows, etc. It also says that the Grid element accepts the following sub-elements: <Connect>, <SQL>, <Cols>, <ColRange>, etc (in this order). The ? sign indicates that the element can appear 0 or 1 times. The * (asterisk) sign means the element can appear 0 or more times. The rest of the DTD describes each individual sub-element (its own arguments and sub-elements).

The Microsoft XML processor is very strict about the order in which sub-elements appear within an element. For example, <Table> may not appear before, say, <SQL> within <Grid> When designing your XML document, always consult the AspGrid.dtd file.

Click here to view the file AspGrid.dtd.

Chapter 5: Using XML to Set Parameters

Contents

5.1 XML as a Way to Represent Hierarchies

5.2 Using XML with AspGrid

5.3 ASP-XML "Rosetta Stone"

5.4 Playing by the Rules - the DTD