Overview

With the jParse jQuery plugin, you can parse XML that is returned from an jQuery Ajax request. jQuery .ajax method does not allow for cross domain Ajax requests, so the XML that you would like to parse must be on the same domain from which you are working. You can pull many types of information from an XML document like the value of an XML node, the value of an attribute of an XML node, or the number of <items> in an XML document.

Basic Usage

The basic syntax for the plugin is as follows:

$('#item-cont').jParse({
    ajaxOpts: {url: 'digg-feed.xml'},
    count: '#item-count'
});
                        

In the first line, '#item-cont' is the HTML elements that will be filled (with the jQuery append method) with the XML content. The second and third lines contain options for jParse. The only requires option is the 'url' option for 'ajaxOpts'.

To see a working example, please visit the Demo page. The table below is a list of all the options that are currently built into jParse.

Option Listing

jParse Options
Name Type Example Default

ajaxOpts

object

{url: 'data.xml'}

{dataType: ($.browser.msie) ? "text" : "xml", contentType: 'text/xml'}

This object has all of the settings that the jQuery .ajax method has. The only required jQuery .ajax method option is 'url' (as shown in the example above). The default 'dataType' can be overwritten, but it is not recommended because it resolves issues with Internet Explorer and local Ajax calls.

output

string

<div><h2><a href="jpet01">jpet00</a></h2><p>jpet02</p></div>

<h1><a href="jpet01">jpet00</a></h1>

This option will determine how each 'item' in your xml is displayed after being parse per the settings you define. The phrase 'jpet00' will output the value of the first xml node (or attribute) you defined in your array in the 'elementTag' setting. 'jpet01' will output the second selected xml node.

Note: As of jParse 0.3.3 you will need to include a 0 before any number lower than 10. For example: jpet00, jpet01, jpet02, jpet03, jpet04, jpet05, jpet06, jpet07, jpet08, jpet09, jpet10, jpet11, etc.

limit

number

5

Limit the amount of 'items' that is outputted.

precallback

function

starter

This option allows you to run a function before jParse is run. Note that in jParse Beta 0.01, this option accepted a string instead of a function.

callback

function

finish

This option allows you to run a function after jParse finishes running. Note that in jParse Beta 0.01, this option accepted a string instead of a function.

count

string

'#count'

This option will output the number of 'items' jParse found in the xml feed to the HTML element with the specified ID as text using the jQuery .append method.

elementTag

array

['title', 'description', 'link']

Use this option to select the value of the xml nodes you would like to include in the output. There are two options for each xml node: 'exclude' and 'attr'. 'Exclude' allows you to exclude that contain specific text. In the example above, any entries with the word 'dog' in the title would be excluded from the output. The 'attr' option lets you choose the value of an xml nodes attribute rather than the value of the node. If you do not wish to use any of these options, you can just select the node as a string rather than an object as shown above with the selected 'dc:creator' xml node.

The order of each xml node name matters. See the output option below for more information.

attr

string

[{elem: 'guid', attr: 'isFalse'}]

This is an option of an 'elementTag' object. It allows you to pull the value of a node's attribute. In the example above, jParse will use the value of the the 'isFalse' attribute of the 'guid' node.

For example above: http://kylerush.net/?p=416 jParse will use 'false' as the value.

exclude

string

[{elem: 'title', exclude: 'dog'}]

This is an option of an 'elementTag' object. It allows you to exclude an <item> that has any of the specified content within it.

For example above jParse will exclude any <item>'s who's title node contains the word 'dog'.

format

function

[{elem: 'description', format: formatDescription}]

This is an option of an 'elementTag' object. It allows you to create a custom format function and run the function on the node or attribute's value. The function is passed one variable: the value of the node/attribute you have selected.

For the example above, the following custom format function will truncate anything anfter the 90th character and affix '[...]' at the end.

        function formatDescription(string) {
            if ( string.length >= 90 ) {
                return string.substr(0,90) + '[...]';
            } else return string;
        }
                                    

This feature was provided by Mathew Brewer. Mathew Brewer on Twitter.

select

number

[{elem: 'category', select: 1}]

This is an option of an 'elementTag' object. It allows you to select nodes that have multiple names.

For example above, if there are multiple nodes named 'category', jParse will pull the value of the second 'category' node (numbers are javascript numbers, which start at 0).

parentElement

string

parentElement: 'item'

parentElement: 'item'

This option allows you to define the parent element of your XML node entries.