Saturday 2 March 2013

Programming the KwaMoja API - A simple client part1

The Client:

For this tutorial we will build a small PHP application that will first interrogate KwaMoja for a full list of available stock locations, build them into an HTML drop down list and then allow a user to input a stock item code and return the quantity of stock of that item at the selected location. We will use PHP for simplicity but any language that has an xmlrpc library (just about every language) can be used to write a client. It is a lengthy post, so I am splitting it into two parts. This is part 1.

Firstly we need the xmlrpc library, so we copy the xmlrpc sub-directory from KwaMoja to this new project.

The basic code will look like this, and be saved into a file called index.php:


<html>
    <head>
        <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
            "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
    </head>
    <body>
        <form action="index.html" method="post">
            Stock Code:<input type="text" name="StockID" /><br />
            Location:<select name="location">
            <?php // Here will go the available stock locations from KwaMoja?>
            </select><br />
            <input type="submit" name="submit" value="Submit" />
        </form>
    </body>
</html>



As it’s name suggests, the xmlrpc function calls are made by sending an XML file with the function name and the parameters to the server, and receive an XML file back from the server.

To assist with this, the phpxmlrpc library that KwaMoja uses (and we will use as well for our client) contains methods to encode our function call as XML, and to decode the XML that we receive back.

First off we need to include the xmlrpc library in our file, so immediately above the HTML, we need the following:

<?php
    include 'xmlrpc/lib/xmlrpc.inc';
    $xmlrpc_internalencoding='UTF-8';
    include 'xmlrpc/lib/xmlrpcs.inc';

?>

Running this page in our browser looks like this:
Not very pretty but you can see the idea.

Now the next thing we need is the code to populate the drop down box with the stock locations in it. Looking at the API function reference in the manual we see a function called kwamoja.xmlrpc_GetLocationList(). Obviously this is the function we require. Looking at the reference, the function takes two parameters, a valid userid for the KwaMoja instance, and the password for that user. In my case that is admin/kwamoja as in the standard demo setup, you must change yours to be whatever the name of the database is on your target KwaMoja installation.

We require a PHP function to return a list of locations to populate the drop down list. The function will look like this, and be at the bottom of the file, within a PHP code section (ie <?php ?>).

   function GetLocations() {

        //Encode the user/password combination
        $UserID = php_xmlrpc_encode("admin");
        $Password = php_xmlrpc_encode("kwamoja");

        //Create a client object to use for xmlrpc call
        $Client = new xmlrpc_client("http://localhost/KwaMoja/api/api_xml-rpc.php");


        //Create a message object, containing the parameters and the function name
        $Message = new xmlrpcmsg('kwamoja.xmlrpc_GetLocationList', array($UserID, $Password));

<

No comments:

Post a Comment