Howto: Use XML Files

The purpose of this chapter is to help you get started with Text Control Enterprise and its XML features. It will show you how to open an XML file, and how to use it in conjunction with a CSS stylesheet and a DTD.

There is a more detailed description of the XML related propertiesand methods in the Technical Articles section, see Working with XML Files.

The source code for this example is contained in the following directories:

  • %USERPROFILE%\Documents\TX Text Control 32.0.NET for Windows Forms\CSharp\Howto\XMLBasics
  • %USERPROFILE%\Documents\TX Text Control 32.0.NET for Windows Forms\VB.NET\Howto\XMLBasics

Used TX Text Control controls:

  • TXTextControl.TextControl
  • TXTextControl.ButtonBar

Relevant API links:

The Sample Program

The sample program has only one menu item, which is Open File.... Looking at the source code reveals nothing unusual: The main difference to the Open File routine in other Text Control sample programs is the Load method being called with the StreamType value XMLFormat as a parameter, so that the Open File dialog box will only display XML files:

private void Open_Click(object sender, EventArgs e) {
        m_txTextControl.Load(TXTextControl.StreamType.XMLFormat);
}
Private Sub Open_Click(ByVal sender As Object, ByVal e As EventArgs) Handles m_tmiOpen.Click
        m_txTextControl.Load(TXTextControl.StreamType.XMLFormat)
End Sub

There is quite a bit happening behind the scenes, however. If you load the address.xml sample file, Text Control will not only load the xml file, but will

  • automatically validate it using the enclosed DTD, and
  • format it according to the CSS stylesheet provided.

Let us take a closer look at the 3 files involved.

The XML File

The XML file contains a simple list of addresses:

<?xml version="1.0"?>
<?XML:stylesheet type="text/css" href="address.css"?>
<!DOCTYPE address SYSTEM "address.dtd">
<address>
   <address_record>
      <name>Paul</name>
      <street>Baker Street</street>
      <city>London</city>
      <email>paul@hotmail.com</email>
   </address_record>
   <address_record>
      <name>George</name>
      <email>george@hotmail.com</email>
   </address_record>
</address>

Note that, unlike an HTML or RTF file, an XML file does not contain any information about how the text is to be displayed or formatted.

The CSS File

In line 2 of the XML file (above), you can see a reference to a stylesheet file called address.css. This CSS file tells Text Control that an address entry should be displayed as a table, and that the individual elements are table cells, having a 1 pixel wide border and a font size of 1 point:

address { display: table }
address_record { display: table-row}
name, street, city, email { display: table-cell; border: 1px; font-size: 11pt }

When you load address.xml with the sample program, Text Control will display it according to this stylesheet.

Image

Changing the CSS file can make the text appear in a completely different way. For instance, a list can be used instead of a table, as in this example:

name {display: block; font-size: 14pt; color: blue }
street, city, email { display: list-item; font-size: 11pt}

This is how Text Control will display the XML data (address_list.xml) using the new stylesheet (address_list.css):

Image

The DTD File

The DTD specifies which elements may occur in an XML file, and in which way the elements should be ordered or nested. The sample DTD specifies that an address contains one or more address_record elements, which in turn can contain a name, street, city, and email. street and city are defined as optional elements.

<!ELEMENT address ( address_record+ )>
<!ELEMENT address_record ( name, street?, city?, email )>
<!ELEMENT name (#PCDATA )>
<!ELEMENT street (#PCDATA )>
<!ELEMENT city (#PCDATA )>
<!ELEMENT email (#PCDATA )>

When loading an XML file, Text Control checks whether the XML code is valid according to the DTD. If it is invalid, an XmlInvalid event is fired, that provides data about it. In this example the required <name> has been removed from the address_invalid.xml file:

<?xml version="1.0"?>
<? XML:stylesheet type="text/css" href="address.css"?>
<!DOCTYPE address SYSTEM "address.dtd">
<address>
    <address_record>
        <street>Baker Street</street>
        <city>London</city>
        <email>paul@hotmail.com</email>
    </address_record>
</address>

When loading this XML file, the XmlInvalid event is fired and handled by displaying a MessageBox that informs the user about the reason of the error.

Editing in XML Mode

This chapter looks at some of the differences between normal text editing and editing an XML file.

The source code for this example is contained in the following directories:

  • %USERPROFILE%\Documents\TX Text Control 31.0.NET for Windows Forms\Samples\WinForms\CSharp\Howto\XMLEditing
  • %USERPROFILE%\Documents\TX Text Control 31.0.NET for Windows Forms\Samples\WinForms\VB.NET\Howto\XMLEditing

Used TX Text Control controls:

  • TXTextControl.TextControl
  • TXTextControl.ButtonBar

Relevant API links:

The Sample Program

Run the sample program and load the demo file address_list.xml. You will notice that there is now a button bar with 3 combo boxes:

Image

You don't need to create the combo boxes yourself, they are built into Text Control's ButtonBar.

The first combo box displays the style of the current XML field. If you move down the caret by pressing the down arrow key, the display will change from name to street, city and email, depending on what type of field you are in.

With the second combo box, additional XML fields can be inserted.

Image

You can select to either insert a complete address record, or one of the optional elements, which are street and city. Depeding on the DTD, not all elements can be inserted at all positions. For instance, if you click on the name Paul in the first line of the document, and try to insert a street, an error will occur, because this record already contains a street. Try again with Ringo, and it will work.

The third combo box is for deleting XML fields. Again, every action is checked with the DTD, so that you can be sure not to invalidate your document by, for instance, deleting a required field.