Back Previous Next
4.1 The 'new customer' form
We're now going to build a customer record entry form. To keep it simple, we'll only hold a minimum of information, as follows:
*MESSAGE*
Name:
Street address:
Town/City:
Telephone:
* = required field
The form contains four input fields, each able to hold up to 40 characters. There are also two hidden fields, one called id (not used for a new customer) and the other ScreenID . When we send this form to the client all the *???* substitution parameters will be replaced by suitable values. The string *FUNCTION*, for example, is replaced by the word Add. When the "Add this customer" button is clicked, the form is submitted to the server and all the fields are available as parameters, the values being the contents of the fields.
When the servlet receives a request it looks up the value of the ScreenID parameter. Now the first time we enter the customer module we'll be arriving from the main menu, and ScreenID will have the value "CNew". (It can't presently be anything else; this is the only value currently known to the dispatcher, but that's shortly going to change.)
So the first thing we need to do is send this form back to the browser. Here's the code to do it, along with everything else associated with the helper module:
! Customer.ls import buffer Website ! my directory path on message begin if the message is "new" gosub to NewCustomer end stop !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ! Show the New Customer screen. NewCustomer: prompt "New Customer" set the title to "New Customer" add template Website cat "servlets/templates/cnew.html" where "*MESSAGE*" is "" and "*NAME*" is "" and "*STREET*" is "" and "*CITY*" is "" and "*TELEPHONE*" is "" and "*SCREENID*" is "CAdd" and "*FUNCTION*" is "Add" return
Ignoring comments, the first thing is to declare the variables we expect to import from the caller. They must match those used in Library.ls - in type, that is. The names can be anything you like but I've chosen to use the same ones.
Next is an instruction that tells the script what to do when a message is received (from the send command in Library.ls). If you have a lot of commands you can set up a dispatcher, but for only a few it's OK to do string comparisons. So far there's only one to check for.
The NewCustomer subroutine is where we add the template file cnew.html, substituting the name of our host as before. Take a look at the file; it contains several preloaded substitution strings. The string *MESSAGE* has a purpose I shall explain later. For now we just set its value to an empty string. Each of the text fields also contains a substitution string; these we also set to empty strings. The last two items, *SCREENID* and *FUNCTION*, allow us to use the form for editing records as well as for adding new customers, as we'll see later. Here we substitute values relevant to adding a customer.
There are two other new features; the first is the prompt instruction. This will output its string on the console and is invaluable for debugging. The second new feature is the instruction set the title, which controls the text that will appear in the title bar of the page. I should explain at this point that only the body of a template file is used; the head is ignored. This enables multiple templates to be strung together but also requires the script to provide a page title.
Save the script as Customer.ls (it's in the scripts folder as Customer-1.ls). You can now recompile, but before doing so, remove the comment in front of the run instruction for Customer in Library.ls. Compile Library.ls and you will find that you don't need to separately compile Customer.ls; it's done automatically, the compiler detecting the need when it encounters the run instruction. Re-initialize the servlet, point your browser at the main menu again and click the first active link. You should see the customer form.
4.2 More advanced debugging
There are many occasions where things don't go according to plan. Debugging inside a server is a tricky business, so we've added a couple of features to avoid the need. The idea is to be able to run the servlet outside of the server environment, and to have it write its output to an HTML file on disk. There are a few steps to take to get this all working.
First I must explain that the command line for Linguist allows you to add an extra parameter, and also to run the script after compiling. The complete command line looks like this:
java LS Library.ls -r -adebug
Up till now we've used the -o option which compiles to the runtime file Library.lrun. Here we use -r, which compiles and runs (without creating an output file for Library, although any helper scripts do get runtime modules created).
The extra option is -a followed by a compile-time parameter debug. This is available inside the script, and we use it to detect that we're running outside the server in debug mode. Here's some extra code for Library.ls:
variable Debug if the arg is "debug" begin set Debug put "d:\server/" into Website parameter "ScreenID" "CNew" do post end
This creates a variable - a 64-bit numeric value - called Debug, which is initially set to zero. The script looks to see if it has a command-line argument called "debug"; if so it sets Debug, puts the address of the server into Website (in this mode the current directory is the servlet folder) and creates a psuedo-parameter "ScreenID". This is not a real HTTP parameter but the script will treat it as one. Finally it invokes the POST callback, just as if a real request had been received.
One more thing is needed. Instead of writing the output to a client browser it must go to a disk file. So here's how:
StartHere: clear document send parameter "ScreenID" to Dispatch if Debug begin write document to "test.html" exit end else write document stop
This is a complete replacement for the previous StartHere code. The script tests the Debug flag; if set the output goes to a disk file. You can then load this into a browser and check if it's OK.
This new version of the script is called Library-3.ls.
4.3 Processing the new customer
Once the form has been filled in the user clicks the form button and the servlet will receive a new request. All of the fields of the form will be present as HTTP parameters, and one of these is the hidden field ScreenID. In our HTML template this has the value "CAdd". So our library main script needs to know how to deal with it. Add another entry to the dispatcher setup:
case "CAdd" send "add" to Customer
and resave Library.ls. Now add another line to the on message handler in Customer.ls:
else if the message is "add" gosub to AddCustomer
Also add a new subroutine to deal with this message when it arrives:
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ! Add a new customer. AddCustomer: prompt "Add Customer" set the title to "Add Customer" return
OK so far, but this subroutine doesn't actually do anything yet. Here's where we get into the database side of things.