XMLParser Objects |
Active Web |
 |
|
XMLParser Objects |
Active Web |
|
The XMLParser object will map an XML document to a script object model.
For details on using the XMLParser see Parsing XML in Scripts.
|
Property |
Description |
|
error |
An error message If an error has occurred. If no error has occurred then it will be null. The error messages are explained below: Function not found for pattern - The addHandler function has been called and the function specified could not be found. XPath error - The addHandler function has been called with an invalid pattern. While accessing files the operating system can generate various other error messages. While accessing URLs the operating system can generate various other error messages. |
|
ignoreWhiteSpace |
This is a boolean property that is set to true by default. This has the effect of removing all white space at the start and end of any element text. White space include spaces, tabs and newline characters. To include white space set this false. |
|
validating |
This is a boolean property that is set to false by default. When set true, this has the effect of checking the validity of the document to the scheme specified by the Uri in the document. |
|
om |
Object model returned by the built in handler. This will be the XML element identified by the built in handler pattern in one of the parse functions. If a parse function has not been run or no pattern was supplied to the parse function then this property will be null. |
|
prototype |
A reference to the Object Prototype. This property does not enumerate and can not be deleted, but it can be changed. |
|
Function |
Description |
|
addHandler(pattern, function[,arg1[, . . .]]) |
Adds a handler function that will be called if an element is encountered during a parse that matches the pattern. The optional arguments are given to the handler function when it is called. |
|
parseFile(name[, pattern]) |
Parses the XML document in the file identified in the name. The name uses the script file reference to identify the file. File references outside the document root are allowed. The pattern identifies the root in the XML of the object model to be built in the om property (see above). If the pattern is not present then no object model is built and the om property will be null. If an error occurs then this function returns false and the error property will be set. Tip: Using the pattern "/" will match the root of the XML being parsed. |
|
parseURL(url[, pattern]) |
Parses the XML document returned by the URL. The pattern identifies the root in the XML of the object model to be built in the om property (see above). If the pattern is not present then no object model is built and the om property will be null. If an error occurs then this function returns false and the error property will be set. Tip: Using the pattern "/" will match the root of the XML being parsed. |
|
parseString(string[, pattern]) |
Parses the XML document in the string. The pattern identifies the root in the XML of the object model to be built in the om property (see above). If the pattern is not present then no object model is built and the om property will be null. If an error occurs then this function returns false and the error property will be set. Tip: Using the pattern "/" will match the root of the XML being parsed. |
|
removeHandler(pattern) |
Removes all handlers that match the pattern string. |
The source must be well formed XML. The parser does a 'non validating' parse and so will not use a DTD (Document Type Definition), but if the XML includes a reference to a DTD this must be available.
If there have been any handler functions defined prior to parsing (see addHandler() function) or the built in handler pattern is supplied, then the handlers will be called during parsing for any elements that are found to match the handler pattern.
A pattern is a string which consists of one or more element names and optional selection criteria enclosed in square brackets separated by forward slashes.
e.g.
"/" will match the root element of the XML data.
"/a/b/c" will match all "c" elements whose parent is a "b" element and whose grandparent is the root element "a"
"a/b/c" will match all "c" elements whose parent is a "b" element and grandparent is the element "a" irrespective of where they occur in the document.
"c" will match all "c" elements irrespective of where they occur in the document.
"b/c[2]" will match all the second c that has a parent of b
"b/c[2][@warning = 'true'] " will match all the second c that has an attribute named warning whose value is 'true' that has a parent of b
When a pattern is matched the handler function will be called. The function is passed two or more parameters , the first is a script object that represents the child elements of the matching node, the second is a reference to the XMLParser that is being used to perform this parse, the remaining parameters are the optional parameters given at the end of the addHandler method call.
The XMLParser constructor is used to create new XMLParser objects.
var myXMLParser = new XMLParser();
A new XMLParser object is created. No arguments are required.
var myXMLParser = new XMLParser(shouldValidate);
A new XMLParser object is created using the argument supplied to determine whether the parse should be validating or not.
Shown below is the XMLParser object prototype chain.
When the constructor is run as a function without the new operator it has exactly the same behaviour as using the new operator.
Constructor properties are read only (they can not be changed or deleted) and it is not possible to add new properties to the Constructor.
|
Property |
Description |
|
prototype |
A reference to the Object Prototype. This property does not enumerate and can not be changed or deleted. |
The XMLParser constructor has no predefined functions.
Topic ID: 150117