Welcome to jQuery XML-RPC’s documentation!¶
This is a small library that sits on top of jQuery for communicating with XML-RPC services - without worrying about the horrible bloat of XML-RPC. Using this library, you can pass JSON parameters to the library, and receive responses in JSON. Encoding the JSON document is handled for you, intelligently mapping types between the two languages.
Contents:
Installing¶
Simply include the jQuery library, and this library in your page:
<script src="jquery-1.8.1.js"></script>
<script src="jquery.xmlrpc.js"></script>
This was built upon jQuery 1.8.1. It will probably work with old versions, and will probably continue to work with new versions.
Using¶
The jQuery.xmlrpc function is the main work-horse of this library. Call it like so:
$.xmlrpc({
url: '/RPC2',
methodName: 'foo',
params: ['bar', 1, 4.6, true, [1, 2, 3], {name: 'value'}],
success: function(response, status, jqXHR) { },
error: function(jqXHR, status, error) { }
});
It takes all of the same arguments as jQuery.ajax, so refer there for more documentation. The two new keys added are:
- methodName
- This is method put in the <methodName> element from XML-RPC. It should be a string. The XML-RPC service you are communicating with will determine valid method names you can call.
- params
An array of parameters to send. Specify an empty array, or do not supply this key at all if you do not want to send any parameters.
See the docs section on [Encoding and Decoding XML-RPC Documents][encoding] for more information.
Getting data back¶
When the XML-RPC call returns, the contents of the <params> element are parsed into JSON and supplied to the success callback of the AJAX call as the first parameter, much like a JSON request.
Handling errors¶
If any HTTP errors occur during transport, the normal jQuery AJAX error handling will be used. If the XML-RPC service successfully replies, but replies with a <fault> response, an $.xmlrpc.XmlRpcFault is thrown. This error will be sent as the third parameter to the error callback of the AJAX call, as with other errors.
Types¶
JSON and XML-RPC are two unrelated markup languages, so converting between the types requires a small understanding of both languages. Luckily, most of the types have a direct mapping between the two languages.
Encoding and Decoding XML-RPC Documents¶
Use the following table to see how XML-RPC types are mapped to JavaScript types:
XML-RPC | JavaScript |
---|---|
<nil> | null |
<array> | Array |
<struct> | Object |
<string> | String |
<boolean> | Boolean |
<int> | Number |
<i4> | |
<i8> | |
<i16> | |
<double> | Number |
<dateTime.iso8601> | Date |
<base64> | ArrayBuffer |
Note
JavaScript does not have separate types for integers and floats, it simply has Number. As such, it is impossible to tell if 4 really means <int>4</int> or <double>4</double>. If this is an issue for you, read on.
Forcing types¶
Some times, the automatic type guessing going from JSON to XML-RPC may not work for you. The most common source of this problem is in encoding numbers. The library may sometimes encode a Number as a <int> instead of a <float>, as there is no reliable way of determining what was actually desired.
To force a type, wrap the value in a call to $.xmlrpc.force. The types are named after their XML-RPC equivalents, as mentioned in the above table.
To force a floating point JavaScript Number to be encoded as an <i8> and sent as a parameter, use the following:
var forcedValue = $.xmlrpc.force('i8', 4.5)
$.xmlrpc({
url: '/RPC2',
methodName: 'foo',
params: [forcedValue]
});
Adding and Extending Types¶
You can add your own types to XML-RPC by adding a member to $.xmlrpc.types, combined with the $.xmlrpc.makeType function. See $.xmlrpc.makeType() for more information
API¶
The following API is exposed in case you need to extend this library. You should not have to use this API in everyday use of the library.
$.xmlrpc()¶
Call a remote procedure. This is a small wrapper around jQuery.ajax() so see the documentation for that for more information. It takes the following arguments:
- url
- The URL of the service to call. Optional. If not specified, this is pulled from the options dict
- options
Options for the request. Most options are passed straight through to jQuery.ajax(), with the exception of two keys.
The methodName key must always be supplied, and must be a string. It is used as the <methodName> for the call
The params key can be used to send parameters. This must be an array of values. Leave this blank, or supply and empty array to send no parameters.
See Types for more information on how JavaScript types are translated to XML-RPC types
Getting data back¶
When the XML-RPC call returns, the contents of the <params> element are parsed into JSON and supplied to the success callback of the AJAX call as the first parameter, much like a JSON request.
Handling errors¶
If any HTTP errors occur during transport, the normal jQuery AJAX error handling will be used. If the XML-RPC service successfully replies, but replies with a <fault> response, an $.xmlrpc.XmlRpcFault is thrown. This error will be sent as the third parameter to the error callback of the AJAX call, as with other errors.
$.xmlrpc.document()¶
Make an XML-RPC document from a method name and a set of parameters. It takes the following arguments:
- methodName
- This is method put in the <methodName> element from XML-RPC. It should be a string. The XML-RPC service you are communicating with will determine valid method names you can call.
- params
- An array of parameters to send. Specify an empty array if you do not want to send any parameters.
Example¶
The JavaScript call:
$.xmlrpc.document('foo', ['bar, true, [1, 2, 3]]);
produces the following XML document (with out the whitespace):
<methodCall>
<methodName>foo</methodName>
<params>
<param>
<value><string>bar</string></value>
</param>
<param>
<value><boolean>1</boolean></value>
</param>
<param>
<value><array><data>
<value><int>1</int></value>
<value><int>2</int></value>
<value><int>3</int></value>
</data></array></value>
</param>
</params>
</methodCall>
$.xmlrpc.toXmlRpc()¶
Take a value, and encode it as an XML-RPC node. Because the XML nodes must be created by the XML documents own createElement, this can not be used outside of a call to $.xmlrpc.document. It takes the following arguments:
- value
- The value to encode
- $xml
- A helper function to create an XML node on the document. It is then returned, wrapped by jQuery.
$.xmlrpc.parseDocument()¶
Parse an XML-RPC document, and return its contents. If the document represents an XML-RPC fault, an $.xmlrpc.XmlRpcFault is thrown. It takes the following arguments:
Example¶
The following XML document:
<?xml version="1.0"?>
<methodResponse>
<params>
<param>
<value><string>foo</string></value>
</param>
<param>
<value><int>3</int></value>
</param>
<param>
<value><struct>
<member>
<name>foo</name>
<value><i4>1</i4></value>
</member>
<member>
<name>bar</name>
<value><i4>2</i4></value>
</member>
</struct></value>
</param>
</params>
</methodResponse>
parsed by:
$.xmlrpc.parseDocument(doc);
would result in the JSON document:
[
'foo',
3,
{
foo: 1,
bar: 2
}
]
$.xmlrpc.parseNode()¶
Take a single XML element, and return the JSON equivalent of it. It takes one argument:
- node
- The XML node to decode. It should be be one of the types registered with $.xmlrpc.makeType(). If the type can not be found, and error is thrown.
Example¶
The XML element:
<struct>
<member>
<name>foo</name>
<value><i4>1</i4></value>
</member>
<member>
<name>bar</name>
<value><i4>2</i4></value>
</member>
</struct>
would be parsed by calling:
$.xmlrpc.parseNode(node)
resulting in the JSON:
{
foo: 1,
bar: 2
}
$.xmlrpc.makeType()¶
Add a XML-RPC type to the library. The library will then know how to decode elements of this type when they are returned. It takes the following arguments:
- tag
- The name of the XML-RPC element this represents. Example: 'boolean'
- simple
- If the element is a simple type or not. All standard elements except <struct> and <array> are simple types. The encoding a decoding functions of simple types are simplified, as they just deal with the text content of the elements.
- encode
Take a JavaScript value, and encode it to an XML-RPC element. Receives the value to be encoded, and a helper function used to create XML nodes on the correct document - This helper MUST be used to create XML nodes for child elements.
Simple types need only return the text of the node, creating the node is handled for you.
- decode
Take an XML element, and decode it to a JavaScript representation.
Simple types receive the text of the node instead of the node itself.
Example¶
A simple boolean node:
// Boolean type. True == '1', False == '0'
$.xmlrpc.makeType('boolean', true, function(value) {
return value ? '1' : '0';
}, function(text) {
return text == '1';
});
A complex, custom element:
/**
* Convert
* {foo: 1, bar: "hello"}
* into
* <custom><foo>1</foo><bar><string>hello</string></bar></custom>
* Note the call to `$.xmlrpc.toXmlRpc`` to recursively encode the `bar` element.
*/
$.xmlrpc.makeType('custom', false, function(value, $xml) {
return $xml('custom').append([
$xml('foo').text($.xmlrpc.toXmlRpc(value.foo, $xml)),
$xml('bar').text($.xmlrpc.toXmlRpc(value.foo, $xml))
]);
}, function(node) {
return {
foo: parseInt($(node).find('> foo').text()),
bar: fromXmlRpc($(node).find('> bar > *').get(0)),
}
});
$.xmlrpc.force()¶
Force a value to be encoded as a certain type in XML-RPC. It takes the following arguments:
- type
- The type to force the value to. One of the XML-RPC types named in the [types documentation][types], or one of the custom types added with $.xmlrpc.makeType.
- value
- Any value that will be encoded as the type.
Example¶
Force a float to be encoded as an i8, to send as a parameter:
var forcedValue = $.xmlrpc.force('i8', 4.5)
$.xmlrpc({
url: '/RPC2',
methodName: 'foo',
params: [forcedValue]
});