The demo from the previous step is cool because it take very little code. But it's also very limited because it's all static. We're running a static SQL statement that's returning all records. It would be nice to actually be able to specify a 'parameter' to search for, right.

Using parameters via the QueryString

Ok, let's change the code above as follows to allow us to specify a 'parameter' via the QueryString.

*** Retrieve the Company from the QueryString
lcCompany = Request.QueryString("Company")

*** Run a static query - this time with the Company parameter
SELECT company, careof as Name, address, phone ;
   FROM wwDemo\TT_CUST ;
   WHERE UPPER(Company) = UPPER(lcCompany) ;   
   ORDER BY Company ;
   INTO CURSOR TQuery

Now try the following URLs in your browser:

http://localhost/WebDemo/CustomerList.wp?Company=A
http://localhost/WebDemo/wc.dll?WebProcess~CustomerList~&Company=A

Note that we're passing the parameter Company on the URL. The syntax is slightly different whether you use the full path or the script map syntax. In the full syntax the ~ character is used to separate positional parameters and an & is used to separate named parameters. Note the ~& to signal the end of the positional parameters and moving into named parameters.

In both cases the result from this request is now only the A's of the customer list. We now have a limited form of user input - we can simply change the URL to pass the Company A down to your request method to run. You can add this into URLs like I did above, or you can have users type this stuff directly into the browser.

The QueryString() method retrieves parameters from the query string and it can do so both for postional parameters and named parameters:

lnMethod = Request.QueryString(1)
lcCompany = Request.QueryString("Company")

You can pass parameters either way. Multiple named parameters must be separated by &'s. For example:

CustomerList.wp?Company=Brim+Healthcare&Action=Delete

Here two named parameters are passed Company and Action. BTW, notice that the first parameter looks a little weird. Instead of a space it has a + sign instead. This is because a query string must be UrlEncoded. UrlEncoding replaces any non keyboard characters with encoded characters. Spaces turn to + and any non-keyboard characters are turned into hex values like %0D for CHR(13) for example.

Note that when you need to embed URL information into HTML output you can use the UrlEncode() method (in wwUtils.prg) to turn a string into a URLEncoded string:

lcValue = UrlEncode(lcValue)

to encode a URL so it is properly formatted when clicked on.

The QueryString is useful for 'parameterized' queries - you will utilize querystring parameters primarily for embedded links that get generated by code. They're a great programmatic tool to send users to specific links. Usually a querystring parameter will be a primary key or other identifier that uniquely identifies what you want to lookup.

Posting the data

But for user interaction querystrings are a bit clumsy. After all you wouldn't want to have your visitors to the Web Site key in their search parameters on querystring, right? Instead you probably want to present users with fields to input the data into. Although you can get data from HTML fields returned on the querystring, in general data from HTML Forms are 'POST'ed to the Web Server. POST data doesn't go on the querystring, but is instead sent to the server in a special HTTP buffer in an encoded format that the browser generates for you.

Using HTML forms then is a mutli-step process:

1. Setting up the HTML form
   
2. Having the user fill out the form and submit it
   
3. Capturing the Form data and do something with it
   

Depending on the situation, this process can be handled by multiple pages or a single one. In the simple example, of providing a single Company Search box we're going to use a single Web Connection request method to both generate the form and also retrieve the value.

Let's modify the CustomerList method one more time by adding the following to the top:

************************************************************************
* WebDemo :: CustomerList
****************************************
FUNCTION CustomerList()

lcCompany = Request.QUeryString("Company")
IF EMPTY(lcCompany)
   lcCompany = Request.Form("txtCompany")
ENDIF

*** Run a static query - this time with the Company parameter
SELECT company, careof as Name, address, phone ;
   FROM wwDemo\TT_CUST ;
   WHERE UPPER(Company) = UPPER(lcCompany) ;   
   ORDER BY Company ;
   INTO CURSOR TQuery

Response.HTMLHeader("CustomerList")

TEXT TO lcHtml NOSHOW TEXTMERGE
<form action="CustomerList.wp" method="POST">
Company Name: <input name="txtCompany" value="">
<input type="Submit" name="btnSubmit" value="Search">
</form>
ENDTEXT

Response.Write(lcHtml)

*** Generate the Cursor HTML Display
loSC = CREATEOBJECT("wwShowCursor")
loSC.lAlternateRows = .T.
loSC.ShowCursor()

*** Write the HTML into the HTTP stream
Response.Write( loSC.GetOutput() )

Response.HTMLFooter()

RETURN

This code generates the following output that now lets you filter your list:

Take a look at the Form code. First notice that we are 'posting back' to the same page that we're coming from. We started on CustomerList.wp and we're going back to it when we post back. If you look at the TEXTMERGE block you can see that the lcCompany value is expanded into the value field of the textbox, which forces the value to be displayed.

This is an important point about HTML - it doesn't automatically retain its value, so something has to explicitly set the values of controls when the page returns. Note that the Web Control Framework manages these semantics for you automatically - but if you're writing low level code like this you are responsible for making the HTML work using raw HTML generation code in all its gory details.