11.6 Handling Posted Data with ARGS and args

11.6 Handling Posted Data with `%ARGS` and `<%args>`

Mason handles posted form data similarly to Embperl. All form data widget names and their values are stored in the hash %ARGS . Let's say a form is posted to a Mason page with the form widget named city . To obtain the value of the form widget, include this code in a Mason page:

 <%perl>      my $city;      if (!exists $ARGS{city}) {          die "no value sent for required parameter city";      } else {          $city = $ARGS{city});      }  </%perl>

Using this code, the my() variable $city contains the value posted in the form for the widget named city .

In practice, %ARGS is generally not used. Instead, Mason programmers use <%args> ... </%args> .

11.6.1 The `<%args> ... </%args>` Tag

The following tag, included anywhere in the Mason page, is used to grab posted data:

 <%args>  $city  </%args>

This tag checks for the existence of the posted city parameter and calls the die() function if it doesn't exist, otherwise assigning the value to $city . Thus, using the <%args> ... </%args> block is a convenient shorthand for declaring variables and assigning them the value of posted form data.

The next example shows the passing of form data using this tag. Put this form in the file /var/www/html/mason/form.html . This is just pure HTML, no Mason code. However because this file is under the /mason/ directory, it is processed by Mason even though there is no Mason code within it.

 <html>  <head>  <title>Mason Form Example</title>  </head>  <body bgcolor="#ffffff">  <h3>Mason Form Example</h3>  <form action="/mason/handleform.html">  Name:    <input type="text" name="name"> <br>  Address: <input type="text" name="address"> <br>  City:    <input type="text" name="city"> <br>  State:   <input type="text" name="state" size="2"> <br>  Zip:     <input type="text" name="zip" size="10"> <br>  <input type="submit"> <input type="reset">  </form>  </body>  </html>

Load this form in the browser by going to either one of these URLs: http://localhost/mason/form.html or www.opensourcewebbook.com/mason/form.html. An example of this page with example data entered can be seen in Figure 11.6.

Figure 11.6. Mason form example

graphics/11fig06.gif

When the form is submitted, it invokes the action specified in the form: /mason/handleform.html . This corresponds to the file /var/www/html/mason/handleform.html , which has the following contents:

 <html>  <head>  <title>Mason Form Handling Example</title>  </head>  <body bgcolor="#ffffff">  <h3>Mason Form Handling Example</h3>  You entered the following in the form:  <br><br>  Name: <b><% $name %></b> <br>  Address: <b><% $address %></b> <br>  City: <b><% $city %></b> <br>  State: <b><% $state %></b> <br>  Zip: <b><% $zip %></b> <br>  </body>  </html>  <%args>      # within this block we "declare" all our variables      # that will contain the posted data - the name of      # the variable is the name of the widget in the form -     # for instance the city widget is named "city", so      # the corresponding variable is $city      # the location of this block is arbitrary - it can      # be at the top of the page or at the bottom or      # anywhere in between - by convention it is at the      # bottom      $name      $address      $city      $state      $zip  </%args>

The important addition to this HTML page is the <%args> tag. This tag can occur anywhere within the HTML file. Here it is placed at the bottom of the page, but it could be at the top or anywhere else. By convention, most Mason programmers place this tag at the bottom of the HTML page, because this puts the programming stuff, which is less likely to be altered , at the bottom of the page and leaves the graphic design stuff (which, experience has proved, is more likely to be tinkered with) at the top.

Within this tag are listed several variables, all of which are assigned their respective form data values. For example, $address is assigned the value from the form for the widget named address . We then include the variable's value in the HTML with <% $address %> .

If you enter the information as shown in Figure 11.6 and click Submit Query, you should see a result much like Figure 11.7.

Figure 11.7. Mason form handling example

graphics/11fig07.gif

In the next section, you will see that the <%args> ... </%args> block is also used with Mason components . If a variable listed in the <%args> tag has not been posted to the Mason program, the program will die() . For instance, in the form.html example, there was no widget named phone , so if we include that in the <%args> tag:

 <%args>  $city  $phone  </%args>

Mason will complain with a runtime error indicating that $phone is not set. Feel free to try this: Change handleform.html by adding $phone to the <%args> tag and resubmit the form data ”the related Mason error should show up.

Not so good, eh? Having an error occur by default is bad behavior. This error can be prevented by providing defaults for elements that may not be supplied by the browser. Providing defaults may not be necessary in all instances, but it's usually good practice to think about the consequences of incorrectly posted data. Here's an example:

 <%args>  $city  $phone => 847-555-1234  </%args>

The default is indicated by the => 847-555-1234 syntax. If the parameter named phone is posted to the program, that value is used; otherwise, the default 847-555-1234 is used. So any or all of the variables declared can be made defaults within the <%args> tag:

 <%args>  $name  $address  $city  => Chicago  $state => IL  $zip   => 60601-0001  $phone => 847-555-1234  </%args>

This example provides defaults for the last four variables. The default values are overridden when the values for those parameter names are posted.

Now we have the basics of Mason ”embedding Perl code into our pages and retrieving the posted form data ”and we can move on to one of the more powerful features of Mason: components.