To understand the declaration files used by the InterAction Application Server and the Web Client, you should understand the basics of the Extensible Markup Language (XML).
XML is a markup language similar to HTML. The key difference is that XML is more structured and is extendable – an XML document can use a custom set of markup tags.
This section covers the following topics:
- XML Declaration
- Elements and Tags
- Attributes and Values
- Comments
- Making an XML Document Well-Formed
- Using an XML Editor
This guide provides a very brief overview of XML files for the purposes of customizing the Web Client. For a more comprehensive look at XML, consult other resources, suggested in More XML Resources.
XML Declaration
The first line of an XML document is always the XML Declaration:
<?xml version="1.0" standalone="yes"?>
This provides information about the XML version and whether the document uses a document type definition (DTD). A DTD is a set of rules that define the allowable structure for an XML document. The XML files you need to edit for Application Server are considered standalone documents – this means that there is no corresponding DTD for these files.
Elements and Tags
XML is similar to HTML in that it is composed of elements. An element can mark up text, or it can just provide information used by Application Server. For example, a “menuItemDeclarations” element marks up text to be defined as menu items.
You specify elements in an XML document by placing them in tags. A tag is enclosed within less-than (<) and greater-than (>) signs and contains the name of the element, like the following:
<profileDeclarations>
This is an example of an opening tag for the element. All opening tags must be closed with a closing tag. A closing tag is identical to the opening tag, except that it has a forward slash (/) before the element name:
</profileDeclarations>
Anything between the opening and closing tags is considered part of the element. The element can contain text, other XML tags, or it can be empty.
An element may have specific requirements about what can be contained between the opening and closing tags. For example, an element may only allow text information. A different element may only allow other elements.
Unlike HTML, every opening tag must have a corresponding closing tag. If there is no text or other tags between the opening and closing tags, you can condense them into one by placing the forward slash before the closing greater-than sign. For example, note the difference shown below.
Empty XML Elements
|
<formControl type="label"> <controlLabel>Name:</controlLabel> </formControl> |
This element contains other elements. Note the separate opening and closing tags (<formControl> and </formControl>) that enclose the information. |
|
<field id="2/-10401"> </field> |
This element does not contain any text or other elements – there is nothing between the <field> and </field> tags. Therefore, the opening and closing tags can be condensed into a single tag. <field id="2/-10401" /> |
XML tags can be nested within each other. Nested tags must be opened and closed at the same level.
The elements available for use when configuring the Web Client depend on the type of XML file you are editing. For a reference to the elements used for the Web Client, see the following sections:
- Elements and Attributes for a Page Method Declaration
- Elements and Attributes for a Nugget List Declaration
- Elements and Attributes for a Search List Declaration
Attributes and Values
An element can also have attributes. An attribute provides additional information about the element.
You specify attributes in the start tag for an element, in the syntax of attribute_name = "value". For example, the field element has the following two attributes:
-
labelset to the value “Clients” -
labelClassset to the value “headline”
Attribute values must be enclosed with either single or double quotation marks. It does not matter which kind you use.
The allowed attributes and values for a particular element depend on the element. For a reference to the attributes allowed by the elements used for the Web Client, see the following sections:
- Elements and Attributes for a Page Method Declaration
- Elements and Attributes for a Nugget List Declaration
- Elements and Attributes for a Search List Declaration
Comments
An XML file can contain comments. These are ignored during the processing of the file. Comments are useful for including notes about what the various tags mean.
Comments use the same syntax as HTML – any text between <!-- and --> is a comment, for example:
<!-- This is a comment -->
Comments cannot be included within a tag. Also, a comment cannot contain double dashes (--).
The XML files installed with InterAction Application Server include comments.
Making an XML Document Well-Formed
An XML file is considered well-formed if it conforms to a certain set of rules. These rules include the following:
- The file begins with the XML declaration.
- All attribute values are enclosed within quotation marks. They can be single or double quotation marks.
- All opening element tags have corresponding closing tags.
- All element tags are properly nested.
For more information about well-formed XML files, see one of the XML resources listed in More XML Resources.
An XML file is considered valid if the file is both well-formed and conforms to a document type definition (DTD). A DTD is a set of rules that define the allowable structure for an XML document. The XML files you need to edit for InterAction Application Server are considered standalone documents – this means that there is no corresponding DTD for these files.
Application Server can only process well-formed XML files. Using an XML editor is a good way to ensure that your documents are well-formed.
Using an XML Editor
Although you can edit the InterAction Application Server XML files with a text editor, using a validating XML editor is strongly recommended. This is because Application Server can only process well-formed XML files. A validating XML editor can confirm that the file is well-formed before you save changes. The editor should also include features to help you find mistakes such as tags that have not been closed properly.
Some XML editors also use different colors for the tags, which can help you find the information to edit when changing the document.
See the documentation for your XML editor for details about how to use it and how to validate XML documents.
There are several freeware, shareware, and commercial XML editors available.