Understanding HTML Forms
GET and POST Methods

The form tag

It isn't too difficult to read a form tag in an HTML document to figure out how to form a valid argument list for submitting form data with a GET or POST method. First you want to examine the source code of the web page that has the form on it. The form tags look something like this:

<form action="http://url.here.com/" method = "POST" (or "GET")>
  - input elements go here -
</form>

The action= attribute tells you the URL to send the argument list to, and method= tells you whether to use GET or POST. The various input element types within the form will tell you what kinds of information you need to send to the URL to form a valid request. The most used tag within forms is the <input> tag. The type of input is specified with the type attribute.

Some common input types:

   Name: <input type="text" name="fullname" /> 
   
   Looks like this: 
   
   Name: 
   
   -------------------------------------
   <input type="radio" name="gender" value="male"> Male</input>
   <input type="radio" name="gender" value="female"> Female</input>
   
   Looks like this: 
   
	 Male
	 Female
	
   ------------------------------------
   <input type="checkbox" name="agree" value="true"> I agree to these terms.</input>
   Looks like this:
   
    I agree to these terms
 

Note: When a checkbox input is checked, a name=value pair is sent with the argument list. However, if it is not checked, no name=value pair is sent for the input.

  
   ------------------------------------
   <select name="color">  
      <option value="blue">blue</option>
      <option value="yellow">yellow</option>
      <option value="red">red</option>
      <option value="green">green</option>
   </select>
   
   Looks like this:
   
   
      blue
      yellow
      red
      green
   

Understanding name=value pairs

The key to finding the components you need to construct argument lists is to look for name="" and value="" elements inside form input tags to get name=value pairs. In fact the whole purpose of an HTML form is to create strings of name=value pairs. These essentially are made into arrays by the host server when it receives the data. Remember, an array is made up of a "key" (corresponding to the "name" attributes in the form) and the actual data (corresponding to the "value" attributes in the form).

So when trying to figure out what to GET or POST by reading an HTML form, look for the keywords name="xxxx" and value="yyyy". That will tell you what names and values to put into your argument list for either GET or POST.

An arg list is always in the form:

name1=value1&name2=value2&name3=value3

So if you wanted to pass on the name=value pair for the radio button input group shown above, you would look at the input type="radio" tag. You see name="gender" and value="male" or value="female". Whichever button the user chooses will be the value that gets submitted with the arguments list. So if the user clicked on Female you would find this string somewhere in the argument list string for either GET or POST:

gender=female

Let's consider a more complete example. Assume a user filled out the following form and clicked Submit:

The argument list string generated might look like this:

  fullname=Janet+Planet&gender=female&color=red

You can look at virtually any form element in an HTML source and, using this type of analysis, determine exactly what kind of argument list you need to construct in your LiveCode stack to send a valid argument string to a web service.

Screen snap of the lipsum.com web page form,
from https://lipsum.com/ ©lipsum.com.

Here is a step-by-step process for doing this, using as an example an online "lorem ipsum" text generator. Lorem ipsum is pseudo Latin text that is widely used in example texts where the focus is on the format rather than the content. The site lets you generate this nonsense text using a web service, which is not formally documented. You can visit lipsum.com using this link. When you go there, focus your attention on the form at the bottom of the right-hand column.

RESTful web services function by receiving parameter lists formatted as a series of name=value pairs, separated by & symbols. In websites that use the HTML "GET" method, that parameter list is appended to the end of a base URL, and you can see the parameter list in the browser's URL field. However, some web services, such as lipsum.com, use the HTML "POST" method for sending parameter strings to the web service. These parameter strings are formatted exactly like those for the "GET" method requests, but the parameter string is not shown in the browser's URL field.

Since there is no visible parameter list, we have to dive into the HTML source code of the page and read the FORM tag, as described in the section above.

First we have to find all of the required parameters, their names and the type of values they send. Look at the web page's source code (most browsers have a "View Source" or "Page Source" option in the View menu.) Scan down until you find the <form> tag. It looks something like this:

	<form method="post" action="/feed/html">
	<table style="width:100%">
	<tr>
	<td rowspan="2"><input type="text" name="amount" value="5" size="3" id="amount" /></td>
	<td rowspan="2"><table style="text-align:left">
	<tr>
	<td style="width:20px"><input type="radio" name="what" value="paras" id="paras" checked="checked" /></td>
	<td><label for="paras">paragraphs</label></td>
	</tr>
	<tr>
	<td style="width:20px"><input type="radio" name="what" value="words" id="words" /></td>
	<td><label for="words">words</label></td>
	</tr>
	<tr>
	<td style="width:20px"><input type="radio" name="what" value="bytes" id="bytes" /></td>
	<td><label for="bytes">bytes</label></td>
	</tr>
	<tr>
	<td style="width:20px"><input type="radio" name="what" value="lists" id="lists" /></td>
	<td><label for="lists">lists</label></td>
	</tr>
	</table></td>
	<td style="width:20px"><input type="checkbox" name="start" id="start" value="yes" checked="checked" /></td>
	<td style="text-align:left"><label for="start">Start with 'Lorem<br />ipsum dolor sit amet...'</label>
	</tr>
	<tr><td></td>
	<td style="text-align:left"><input type="submit" name="generate" id="generate" value="Generate Lorem Ipsum" /></td>
	</tr>
	</table>
	</form>
	

Notice the method="post" and action="/feed/html" attributes immediately inside the form tag. They tell us the request method, "POST", and the web page to submit the request to. In this case it is relative to the main page, so the request URL would be https://lipsum.com/feed/html.

Next we need to discover which name=value pairs we need to send to the URL. Examine the tags inside the form. You should see one that begins <input type="text". That's the text field where you type the number of units of text—paragraphs, words, etc.—that you want to generate. After that you see name="amount" value="5". In the next few lines you see a several instances of <input type="radio" tags, each with its own name= and value= attributes. These tags generate the radio buttons where the user can choose the type of text units—paragraphs, words, etc.—to be generated. Following the radio input types there is a <input type="checkbox" tag, again followed by its own name= and value= attributes. This checkbox determines whether the generated text should begin with the standard beginning, "Lorem ipsum dolor sit amet...", or not.

This set of input type tags tell us the name=value pairs that we need to send to the web service to get back the results we want. In each case, take the quoted values next to the name= and value= attributes to form the pairs. Thus the first pair should be amount=5 (or whatever value the user entered into that text field.)

The next name=value pair is taken from the radio style buttons. The name is obviously "what", and the value is taken from whatever radio button the user selected. In this example the "paras", or paragraphs, option was chosen. So the next name=value pair is what=paras.

Finally, we see next to the checkbox input type the name "start", with a possible value of "yes" or "no". Here, the user did check the box, so we send the name=value pair start=yes.

Now put all of the pairs together using the separator &, to get the complete parameter list:

	amount=5&what=paras&start=yes

This is the parameter string that should be posted to the URL. The function of the webpage form element is to assemble and POST this string to the URL for you.

In LiveCode you send a POST request to a web service using the post command, like this:

	post "amount=5&what=paras&start=yes" to URL "https://lipsum.com/feed/html"

There is a section below that will go into more detail about how to submit a REST request in LiveCode and how to process the results.