GAMBAS BOOK 3.19.5

The XmlExplorer (gb.xml) class is special because it is a combination of XmlReader and XmlDocument: The SAX interface is the same as for XmlReader, but the class works internally like the DOM API. When you open a document, it is loaded and parsed via XmlDocument. If you call the Read() method, then an (internal) pointer is moved to the next node. You can then access the current node using the Node property as with XmlReader.

If you realise while working with the XmlReader API in one of your projects that you should better use the DOM API for performance reasons, then you only have to replace all XmlReader occurrences in the source code with XmlExplorer. This way you are not forced to rewrite your source code completely, but to change it only partially.

If for some reason you want to examine your XML documents linearly - from the first node to the last - and keep the entire document in memory, then using the XmlExplorer class might be a good solution for you.

You can create a new XmlExplorer object like this:

Dim hXmlExplorer As XmlExplorer
hXmlExplorer = New XmlExplorer ( [ Document As XmlDocument] )

The XmlExplorer class has the following properties and methods, which have already been described in the previous chapters:

Property Document As XMLDocument
Property Read Eof As Boolean
Property Read Node As XmlNode
Property Read ReadFlags As .XmlExplorerReadFlags
Property Read State As Integer
Sub Load ( Document As XmlDocument )
Sub Open ( Path As String )
Function Read ( ) As Integer

In the example presented, selected data is to be read from contact data - stored in an XML file - and then displayed in a TextArea. The data read out, processed and saved in a text file could, for example, serve as the basis for printing address labels:

Figure 27.7.2.1: GUI of the example project

The example project is an adaptation of a project → Chapter 27.3 XMLReader with the same task, but using the class XmlExplorer instead of XmlReader.

The source code is given in full:

' Gambas class file
 
Public hXMLExplorer As XmlExplorer
Public sXMLPath As String = "files/list.xml"
 
Public Sub Form_Open()
  ShowXMLContent()
  txaXML.Pos = 0
  HSplit1.Layout = [3, 2]
End
 
Public Sub btnShowRecords_Click()
 
  Dim i, j As Integer
  Dim asMatrix As String[]
  Dim avRecords As New Variant[]
  Dim sSpace As String = String$(4, " ")
 
  avRecords = GetRecords()
 
  For i = 0 To avRecords.Max
    asMatrix = New String[]
    asMatrix = avRecords[i]
    txaList.Insert(sSpace & asMatrix[0] & gb.NewLine)
    txaList.Insert(sSpace & asMatrix[1] & " " & asMatrix[2] & gb.NewLine)
    txaList.Insert(sSpace & asMatrix[3] & gb.NewLine)
    txaList.Insert(sSpace & asMatrix[5] & " " & asMatrix[4] & gb.NewLine)
    txaList.Insert(gb.NewLine)
  Next
 
  File.Save(Application.Path &/ "files/addresslist.txt", txaList.Text)
 
End
 
Private Sub ShowXMLContent()
  hXMLExplorer = New XmlExplorer
  hXMLExplorer.Open(sXMLPath)
  txaXML.Text = hXMLExplorer.Document.Content
End
 
Private Function GetRecords() As Variant[]
 
  Dim asRecord As String[]
  Dim avRecords As New Variant[]
 
  txaList.Clear()
  asRecord = New String[]
 
  hXMLExplorer = New XmlExplorer
  hXMLExplorer.Open(sXMLPath)
 
  While Not hXMLExplorer.Eof
    Select Case hXMLExplorer.Node.Type
      Case XMLReaderNodeType.Element
        If hXMLExplorer.Node.Name = "mw" Then
           If hXMLExplorer.Node.Value = "w" Then
              asRecord.Add("Frau", 0)
           Else
              asRecord.Add("Herr", 0)
           Endif
           avRecords.Add(asRecord)
           asRecord = New String[]
        Endif
        If hXMLExplorer.Node.Name = "vorname" Then
           asRecord.Add(hXMLExplorer.Node.Value, 1)
        Endif
        If hXMLExplorer.Node.Name = "nachname" Then
           asRecord.Add(hXMLExplorer.Node.Value, 2)
        Endif
        If hXMLExplorer.Node.Name = "strasse" Then
           asRecord.Add(hXMLExplorer.Node.Value, 3)
        Endif
        If hXMLExplorer.Node.Name = "wohnort" Then
           asRecord.Add(hXMLExplorer.Node.Value, 5)
           For Each hXMLExplorer.Node.Attributes
             Select Case hXMLExplorer.Node.Attributes.Name
               Case "plz"
                 asRecord.Add(hXMLExplorer.Node.Attributes.Value, 4)
             End Select
           Next
        Endif
    End Select
    hXMLExplorer.Read()
  Wend
 
  Return avRecords
 
End

Comment:

• The presented parser reads the content of the XML file completely and filters out only the data that the user wants to process further. These data are each captured in records and stored in a variant array.
• In the process, these raw data are prepared for the application purpose. Thus, depending on the value for the mw element, it is decided whether the salutation should be man or woman.
• The data prepared in this way are then displayed → Figure 27.7.2.1 in a TextArea.
• The address list is saved in the file addresslist.txt.
• A special feature becomes apparent when filtering the original data by place of residence and postcode, as the postcode is contained in an attribute with the attribute name 'plz', while the place is read out as an element value (text node).