Karoo project web client forms

Introduction

Since writing this documentation, we have created a proper set of HTML widgets.

The Karoo Project HTML Widgets

Unfortunately, HTML gets a little messy with forms, but they work, and it is not difficult to get them working so they can submit information to the database via The Karoo system.

I will describe the simplest type of button in a web page which calls Javascript. This example does not have anything to do with The Karoo Project, but it just explains how a button can be created in HTML.

I will be "misusing" a HTML FORM element, because the form was intended to be used only to submit data to a CGI server. I don't want to do that though, I just want it to call some Javascript. So, I will abuse the system, and get what I want. Basically, the "abuse" will come in the form of me causing it to -NOT- submit the data to anything. There is an "onsubmit" attribute that calls some javascript just before it actually does the submit. If this Javascript returns false, then it is effectively telling the browser that the javascript preparation - before sending - failed. So then it does not submit data to the URL. In fact, my javascript will succeed, but I'll get it to return false, because I don't actually want it to submit anything, and in fact the URL I am setting up in the FORM is invalid.

Following is the HTML code:

 <form action="#" method="post" onsubmit="return myFunction();">
   <p>
     <input type="submit" value="do something"/>
   </p>
 </form>

Note that the "#" action is the (invalid) URL. If it actually got submitted, the web server would return an error, which we don't want happening. We just want the function to be called. Following is the function:

 function myFunction()
 {
    try {
      // ... do something
    catch (e) { alert(e); }
    return false;
 }

The reason for the try ... catch and alert, is that if something throws an exception in the function, you don't want it to exit the function due to an uncaught exception... because this will result in the return of false -not- happening, and then the browser will post the data to the web server, which will result in an error page being shown with a very confusing error. Not really what we want to happen.

An example of a form

 <form id="desc" action="#" method="post" onsubmit="return sendDetails(1);">
    <p class="property-description-form">
      Property title:
      <input id="desc-location" type="text" size="25" name="location" tabindex="1" value=""/><br/>
      Short Description<br/>
      <textarea id="desc-short" rows="4" cols="40" name="short_desc" tabindex="2">
      </textarea>
      <br/>
      <input type="submit" value="Save" />
    </p>
 </form>

Note that the ID attributes are important so that the elements can be accessed from the Javascript:

 function sendDetails(id)
 {
   try {
     var location_field = document.getElementById("desc-location");
     var short_field = document.getElementById("desc-short");
     if (!caveQueryInProgress("desc")) {
       var params = new Array();
       params[0] = new caveParam("location", DB_DATA_TYPE_STRING, location_field.value);
       params[1] = new caveParam("short", DB_DATA_TYPE_STRING, short_field.value);
       params[2] = new caveParam("id", DB_DATA_TYPE_INT_32, id);
       sendCaveQuery("desc", "set-details", params, doneDetailsCallback, "ke-cave");
     }
   } catch (e) { alert(e); }
   return false;
 }

... and the corresponding cave configuration:

 <service name="set details" id="set-details">
   <sql transaction="commit">
     update property set location=<parameter name="location"/>,
     short_desc=<parameter name="short"/>
     where id=<parameter name="id" type="integer"/>;
   </sql>
 </service>

Karoo project web client forms

Introduction

A simple example of a button

An example of a form