Documentation

Written by Sam Tsvilik

Documentation for version 2.0 can be downloaded here (pdf)

Documentation for version 1.0

Function

$.xmlToJSON(xml [, options])

• xml - accepts valid XML string, instance of DOMDocument or DOMNode object
• options - object that instructs converter to process XML in a more customizable way
  • nodeHandler (Function(xmlNode)) - this function allows custom handling of nodes before they are added to an output JSON object.
    This function will always get xmlNode argument of a node currently being processed. In order to customize your output node, this function must return an object representing a modified node or -1 to skip a node entirely. Output object looks like this:
    • { Text: "value of a node",
    • _nodeName: "new name of a node(no spaces)",
    • _processChildren: true | false,
    • _processAttributes: true | false }
      in addition you can just insert your custom attribute or fields.
  • outputType (int) - this value represents the type of JSON object you expect to get back. By default you will get a complex object further described on this documentation page (value = 0). if you want a slimmed down JSON object that only contains values, attributes, fields, etc. then choose a lite version (value = 1).
• returns - JavaScript Object populated with data from xml input parameter

Note: Returned object itself represents a root node of your XML document and is NOT an array, however all children objects of the root element are of the Array type. Array child elements contain special data processing helper functions such as sorting and filtering.

Important: XML nodes and attributes that contain dashes in the name (i.e. node-name) are automatically converted to underscores (i.e. node_name) to overcome JavaScript naming restrictions. This conversion does not impact any data values inside those elements.

Returned object has the following Methods and Properties:

• Properties
  • .typeOf <String> - hard coded value "JSXBObject" (present only at the root level)
    Used for checking if object is a product of xmlToJSON processing
  • ._children <Array> - lists all child node element names (if child nodes are present)
  • ._attributes <Array> - lists all attribute names belonging to this node
  • ._parent <Object> - contains a reference to a parent node
  • ._nodeName <String> - contanis a string value of a node name
  • .RootName <String> - name of the root node (depricated in BETA 2, but is still present for backwards compatibility)
  • .Text <String> - Contains a text node value or a CDATA within a current node
• Methods
  • .getNodesByAttribute(attr, obj) - Returns an array of all node elements that match attribute value
    
    • attr - String name of the attribute
    • obj - Value you are looking for inside an attribute specified in attr parameter
    • Returns - Array of objects that matches a criterea or null
  • .getNodesByValue(obj) - Returns an array of all node elements that match node value
    • obj - Value you are looking for inside a node
    • Returns - Array of objects that matches a criterea or null
  • .contains(attr, obj) - Returns True if matching attribute/value pair is found in the array of nodes
    • attr - String name of the attribute
    • obj - Value you are looking for inside an attribute specified in attr parameter
    • Returns - Boolean
  • .indexOf (attr, obj) - Returns an index position of a node with matching attribute/value pair or -1 if none found
    • attr - String name of the attribute
    • obj - Value you are looking for inside an attribute specified in attr parameter
    • Returns - Integer position or -1 if no match found
  • .SortByAttribute(attr, dir) - Sorts an array of nodes by specified attribute (example)
    • attr - String name of the attribute
    • dir - String direction of the sort options are "ASC" | "DESC"
  • .SortByValue(dir) - Sorts all the nodes in the array by node value (example)
    • dir - String direction of the sort options are "ASC" | "DESC"
  • .SortByNode(node, dir) - Sorts all nodes by their child node names (example)
    • node - String name of the child node
    • dir - String direction of the sort options are "ASC" | "DESC

Note: All Sort functions automatically determine sort type Numeric | Text

$.textToXML(textXML)

This simple and useful utility converts XML String into a DOMDocument object so it can be used to convert to JSON using xmlObjectifier or for any other purpose. One useful way to take advantage of this function is to include some XML data directly on your HTML page inside an invisible element and then use it for any type of data persistance.

• textXML - String containing valid XML
• returns - DOMDocument object if text String was successfully parsed or false if not