JIM Control Usage Manual : Using XML The Easy Way
[ To Table Of Contents ]

With the XML functions built into the JIM Control, you can easily import XML data from XML files on a web site. The JIM Control loads the contents of an XML file into two arrays, allowing you to dynamically present and modify XML data virtually anyway you want to. Because of this flexibility, you could even dump the contents of the two arrays into a form and update XML data files or another data source handled by a server-side application that runs on the web site.

Although you can directly access the contents of the two arrays with your own javascript, it is recommended that you use the prebuilt functions to help with many common tasks that you may need to perform with the XML data residing in the two arrays.

Loading An XML File
Loading an XML file using the JIM Control is a simple process (as shown below). After the XML data is loaded, the JIM Control will automatically extract all of the nodes and values and place them in the two arrays for dynamic use. Aside from the XML file that you want to load, you will need to specify the master node name (opening tag) of the XML file (typically the master node is the XML tag following the <?xml version="1.0"?>):

wxml_load('somefile.xml','BBLOCK');

You can use the onload function of the <body> tag, or if you end up needing to import a dynamically defined XML file, you can place the function inside of a javascript that you write.

Understanding The Arrays
For all XML data files, the JIM Control places the data into two arrays. xml_node_path is the array that holds the name of the node in the XML file. xml_node_value is the array that holds the value of the node in the XML file. If, for example, you want to know the value of a node in xml_node_path[2], then you would get the value from the second array by xml_node_value[2]. Notice that the two arrays are synchronized and separate to make working with the data easier.

Each block of data in an XML file is translated into a virtual "row", as it were. That is, many of the functions the JIM Control returns uses this methodology which is similar to working with Databases, Spreadsheets and so forth. Below is an example of what this means:

Example Raw XML Data Blocks:
<datachunk>
   <title>An Interesting Title</title>
   <description>This could be an area for a description</description>
   <popularity>33</popularity>
</datachunk>
<datachunk>
   <title>A Plain Title</title>
   <description>Something useful goes here</description>
   <popularity>57</popularity>
</datachunk>

How To Visualize The Data In Rows (such as in a database or spreadsheet):
Row ID Title Description Popularity
1 An Interesting Title This could be an area for a description 33
2 A Plain Title Something useful goes here 57


It is important to keep in mind that the row id (shown above) is actually something that is created by the JIM Control to assign a unique number to each block of XML data that it catalogs. The array, xml_node_path, maintains node names and keeps XML data blocks separate by using the text "new_xml_row" at the beginning of each new block of data. The array, xml_node_value simply holds the values of the nodes that have been cataloged.

XML Data Functions
Below is a list of functions built into the JIM Control to help you manipulate the XML data that is cataloged.

wxml_getrow(row_id)
-> Use this function to return the contents of one row of XML Data by specifying the Row ID

Hyper-Link Example (you could also call the function in your own javascript):
<a href="#" onmousedown="javascript:biff.innerHTML=wxml_getrow(1);">Get Row Of Data</a>

What The Fields Mean:
row_id Unique ID number assigned to the block of XML data by the JIM Control.
Function Return Value Function returns the node names and values in comma delimited format of the row of data such as:
title=An Interesting Title,description=This could be an area for a description,popularity=33


wxml_getrowcol(row_id, node)
-> Use this function to return the value of a node by specifying the node name and Row ID

Hyper-Link Example (you could also call the function in your own javascript):
<a href="#" onmousedown="javascript:biff.innerHTML=wxml_getrowcol(1, 'popularity');">Get Node/Column Value</a>

What The Fields Mean:
row_id Unique ID number assigned to the block of XML data by the JIM Control.
node Name of the node (or column in database/spreadsheet terms) for which you would like to get the value of.
Function Return Value Function returns the value found in the node specified.


wxml_getnumrows()
-> Use this function to return the number of rows of XML data cataloged

Hyper-Link Example (you could also call the function in your own javascript):
<a href="#" onmousedown="javascript:biff.innerHTML=wxml_getnumrows();">Get Number Of Rows</a>

wxml_getnumatches(name, integer)
-> Use this function to return the Row IDs of all rows in which a node value is equal to the integer value given

Hyper-Link Example (you could also call the function in your own javascript):
<a href="#" onmousedown="javascript:biff.innerHTML=wxml_getnumatches('popularity', 33);">Get Row IDs Whose Node Has This Value</a>

What The Fields Mean:
name Name of the node or column that you want to evaluate to see if it matches the integer value specified.
integer The match value. This value can be a string or number.
Function Return Value Function returns the Row ID of all rows (comma delimited) whose node / column you specified had the value.


wxml_getgrmatches(name, integer)
-> Use this function to return the Row IDs of all rows in which a node value is greater than the integer value given

Hyper-Link Example (you could also call the function in your own javascript):
<a href="#" onmousedown="javascript:biff.innerHTML=wxml_getgrmatches('popularity', 40);">Get Row IDs Whose Node Has A Greater Value</a>

What The Fields Mean:
name Name of the node or column that you want to evaluate to see if it matches the integer value specified.
integer The match value. This value must be a numeric value.
Function Return Value Function returns the Row ID of all rows (comma delimited) whose node / column you specified is greater than the value specified.


wxml_getlsmatches(name, integer)
-> Use this function to return the Row IDs of all rows in which a node value is less than the integer value given

Hyper-Link Example (you could also call the function in your own javascript):
<a href="#" onmousedown="javascript:biff.innerHTML=wxml_getlsmatches('popularity', 40);">Get Row IDs Whose Node Has A Lesser Value</a>

What The Fields Mean:
name Name of the node or column that you want to evaluate to see if it matches the integer value specified.
integer The match value. This value must be a numeric value.
Function Return Value Function returns the Row ID of all rows (comma delimited) whose node / column you specified is less than the value specified.


wxml_gettxtmatches(name, value)
-> Use this function to return the Row IDs of all rows in which a node value contains the text specified

Hyper-Link Example (you could also call the function in your own javascript):
<a href="#" onmousedown="javascript:biff.innerHTML=wxml_gettxtmatches('title', 'interesting');">Get Row IDs Whose Node Has The Text Specified</a>

What The Fields Mean:
name Name of the node or column that you want to evaluate to see if it contains the value text specified.
value The string match value.
Function Return Value Function returns the Row ID of all rows (comma delimited) whose node / column you specified contains the string value specified.