ABSTRACT

RestStyle has the same functionality for REST scripts as VipStyle has for CGI scripts: it contains a error handler (with methods error_msg and focus) and as success message handler success_msg.

Responses to request are generated with a page_header and terminated with a page_footer; the scripts print the contents of their reply between this two method calls. This response is usually a table of data. RestStyle contains methods (similar to VipStyle for CGIs) to generate such a table.

page_header generates HTTP headers with an apropriate status: 200 followed by a success_msg (defaulting to 'ok') or 500 followed by a focus and the error_msg.


SYNOPSIS

 #!/usr/bin/perl -w
 use strict;
 use vars qw($cgi, $style);
 use CGIsession;
 use RestStyle;
 $cgi = CGIsession->connect();
 $style = RestStyle->new( -cgi=>$cgi );
 &handle_request() unless $cgi->request_is_redirected();
 $cgi->save_session;
 sub handle_request {
     if (...) {      # -- return an error
         $style->error_msg("...");
         $style->focus('...');
         print $style->page_header;
         print $style->page_footer;
     } else {        # -- return any number of data rows.
         my @labels = qw( ... );
         print $style->page_header;
         my $t = $style->table( -labels=>\@labels );
         foreach ... {
               my @values = ...;
               print $t->row( \@values );
         }
         print $style->page_footer;
     }
 }


DESCRIPTION

RestStyle methods never write anything to standard output. Your scripts must print the results of method calls like page_header and page_footer.

Object Constructor

$style = RestStyle->new( -cgi=>$cgi )
The constructor needs a reference to the CGIsession object.

Page Header and Footer

print $style->page_header( ... )
The page_header method returns HTTP-headers. This is returned as a string. For best results, your scripts should print it to STDOUT.

print $style->page_footer( )
Returns the page footer. At the moment, this is just an empty string, but may be a checksum or signature in the future.

Error und Success Messages

A normal REST script first checks the input of the current request; If the input passes plausibility checks, an action is performed and a reply with status 200 is returned, otherwise a status 500 reply will be generated.

The following methods support error handling and success messages in a compatible way to VipStyle.pm. The goal is, to give other classes a common interface to report errors and success.

$style->error_msg( $html_string )
Stores a message which will be included in the next page_header status field. The message can be any iso-8859-1 string.

Only one error should be reported, then focus may be set to the offending input field (see focus below) and then reply writing routine should be called.

$style->focus( $form_element_name )
$style->focus( $form_element_name, $form_name )
Most errors concern the input of an argument. Name the offending argument here. It should be a name: =~ /^\w+$/. The $form_name is defined for compatibility with VipStyle.pm. The idea is, that th focus may be set to one of several forms on a page. This is not used with REST interfaces.

$style->success_msg( $string )
A short success message. iso-8859-1.

Error messages have precedence over success messages. If there is a success_msg and an error_msg, the success_msg will be lost.

Tables

There is a similar interface for tables as in VipStyle.pm. Table objects can be generated from a RestStyle object.

There are two table classes:

-class => 'multi_rows' (the default)
This is a TAB separated file: each line represents a row of data. Lines are separarted by end of lines. Data fields are separated by TAB (horizontal tabs, HT, \t); If data contains a TAB, it is escaped to '\t' (backslash t); end of lines are converted to '\n' (backslash n); a backslash is ecaped to '\\' (two backslashes).

The first line should be column headings. This should be words (follow Perl name conventions).

-class => 'single_row'
In this format, only one dataset is returned. Each line consists of a column name and a value, separated by a TAB. The value can contain more TABs, they should be treated as data. end of lines in the value are translated to '\n' (backslash n); a backslash ist translated to '\\' (two backslashes). The label should be a ward (should follow Perl name conventions).

Table Methods.

$table = $style->table( -class=>'single_row' );
$table = $style->table
$table = $style->table( -class=>'multi_row' );
$table = $style->table( -labels=>\@labels );
$table = $style->table( -class=>'single_row', -labels=>\@labels );
Returns a table object. -class=>'single_row' requires that excactly one row of data is returned. -class=>'multi_rows' can return zero to any number of rows. The -labels=>\@array can be used to specify labels for the columns of the table. If the labels are not given here, they can be specified with method $table->labels.

Labels should be defined before the first data row is written. Labels should be names which conform with Perls naming conventions.

$table->labels( @labels );
Defines the labels for the data columns. There can be any number of arguments (as long as the number corresponds to the number of datas in each row). Each argument can be a label or a reference to an array of labels. A label should conform to Perls naming conventions: a name beginning with a letter or an underline followed by more letters, underlines and digits; no interpunctations, no Umlaute, just plain vanilla ASCII.

$string = $table->row;
$string = $table->row( @cells );
Starts a new data row. The data for the cells can be passed as an argument to the row method or by cell or cells method calls.

$string = $table->cell( $data );
$data can be a single data or a reference to an array, in which case method cell will make separate cell for each array element.

$string = $table->cells( @cells );
Any number of arguments can be passed here. each argument can be a data field or a reference to an array of data fields. Each data gets its own cell.

$string = $table->etable;
Terminates a table. Flushes internal buffers.

Table Examples

 my @labels = qw ( name address email phone )
 my @values = ( 'Thedi', 'ETHZ WEP-J13', 'gerber@id.ethz.ch', '044 632 3492' );
 # -- step by step
 my $table = $style->table;
 $table->labels (\@labels );
 print $table->row;
 foreach my $v (@values) {
     print $table->cell($v);
 }
 print $table->etable;
 # -- the same a bit more compact
 my $table = $style->table( -labels=>\@labels );
 print $table->row;
 print $table->cells(\@values);
 print $table->etable;
 #-- the shortest version
 my $table = $style->table( -labels=>\@labels );
 print $table->row(\@values);
 print $table->etable;


SEE ALSO

CGIsession.pm is the class to access session data; it is an extension of CGI.pm (from CPAN).

The REST client could use class VipInterface.pm to access the Vip application.


COPYRIGHT

Copyright 2004-2013 Thedi gerber@id.ethz.ch