jsxmlRPC Introduction

jsxmlRPC consists of Javascript classes that enable easy interaction with
XML-RPC based webservices. These classes allow webdevelopers to access
webservices just like he or she would access native Javascript functions.

Quick Introduction

This example assumes only a rough understanding of XML-RPC. The mechanisms
provided by XML-RPC are explained in more detail elsewhere.

Starting with a "hello world" example, we'll assume the very useful "hello world"
webservice is located at /webservice.cgi on your server. It provides XML-RPC
a service with the methodname hello and the function returns the much loved
"hello, world" string. The Javascript code to use the webservice would look as follows:

retValue = helloWorld.hello() // returns "hello, world"

That's it! The variable retValue will contain the string
returned by the webservice. That's a bit easier than having to
deal with the following XML being passed around:

Next we'll assume /webservice.cgi script also provides a
function called hello2, a far more advanced webservice that
takes a string (probably containing your name) as a parameter and
returns an XML-RPC struct containing the members
helloworld, the archetypical "hello, $name",
length, an integer value containing the length of the
string that was passed in as a parameter, and finally date
an XML-RPC dateTime.iso8601 type that returns the current
date. Below is the necessary code:

So where did this helloWorld object come from all of the sudden, and who taught it to speak XML-RPC?

There are two things you need to do before transparently using XML-RPC in
Javascript. First, you need to include the library providing the XML-RPC
functionality:

<script src="all_scripts.js" type="text/javascript"></script>

Second, you'll need to create a stub object for the webservice you need
to access. Don't worry, it's only one line of code:

helloWorld = XmlRpc.getObject("webservice.cgi")

The parameter passed to XmlRpc.getObject is the URL of the
webservice. The function automatically creates a stub object with
Javascript functions for every XML-RPC method provided by the
webservice. jsxmlRPC determines what methods are available at the url
using the system.listMethods introspection extension to the XML-RPC
standard. In case your webservice doesn't provide introspection
capabilities, you need to find out the methodnames through other means
and pass them in an array as a second parameter, like this:

helloWorld = XmlRpc.getObject("webservice.cgi", ["hello", "hello2"])

All marshaling between
Javascript and XML-RPC data types is handled transparently. See the
reference for more information about how datatypes are mapped to one
another.

"Don't you know what AJAX is, idiot? I want to everything to be asynchronous?"

Nothing would be easier. If you'd like your calls to the webservice methods to
be asynchronous, all you have to do is to add a callback function after the
last parameter when calling the method. When the answer is received
from the webservice, it gets converted to Javascript as before and is passed to
the callback function you provided:

f = function (x) {
// do something spectacular here
// and become richer than Google.
alert (x.helloworld)
alert (x.length)
alert (x.date)
}
retValue2 = helloWorld.hello2("your name here", f)
alert ("You'll see this before you see the response from the server")

That's right, no if (req.readyState == 4) or if (req.status == 200)
or any other of that tedium.