Embperl - building dynamic websites with Perl

Everything following the if metacommand until the else, elsif, or endif is only output if the Perl expression given in Arg is true. else and elsif work similarly.

Example:

 [$ if $ENV{REQUEST_METHOD} eq 'GET' $]
 Method was GET<BR>
 [$ else $]
 Method other than GET used<BR>
 [$ endif $]

This will send one of the two sentences to the client, depending on the request method used to retrieve the document.

Executes a loop until the Arg given to while is false.

Example: (see eg/x/loop.htm)

 [- $i = 0; @k = keys %ENV -]
 [$ while ($i < $#k) $]
 [+ $k[$i] +] = [+ $ENV{$k[$i]} +]<BR>
 [- $i++ -]
 [$ endwhile $]

This will send a list of all environment variables to the client.

Executes a loop until the Arg given to until is true.

 Example:

 [- $i = 0 -]
 [$ do $]
     [+ $i++ +] <BR>
 [$ until $i > 10 $]

Executes a loop for each element of the second Arg, setting the first Arg accordingly.

 Example:

 [- @arr = (1, 3, 5) -]
 [$ foreach $v (@arr) $]
     [+ $v +] <BR>
 [$ endforeach $]

Inside of looks same as Perl next statement. You could also use the following syntax, which allows you to add an additional condition (or any other Perl code):

    [* next if ($foo) *]

Inside of looks same as Perl last statement. You could also use the following syntax, which allows you to add an additional condition (or any other Perl code):

    [* last if ($foo) *]

Inside of looks same as Perl redo statement. You could also use the following syntax, which allows you to add an additional condition (or any other Perl code):

    [* redo if ($foo) *]

Arg consists of zero, one or two names of hashes (with or without the leading %) and an optional array as third parameter. The hidden metacommand will generate hidden fields for all data contained in the first hash but not in the second hash. The default used for the first hash is %fdat, %idat is used for the second.

If the third parameter is specified, the fields are written in the order they appear in this array. That is, all keys of the first hash must be properly sorted in this array. This is intended for situations where you want to pass data from one form to the next, for example, two forms which should be filled in one after the other. (Examples might be an input form and a second form to review and accept the input, or a Windows-style "wizard"). Here you can pass along data from previous forms in hidden fields. (See eg/x/neu.htm for an example.) If you use just the 'hidden' command without parameters, it simply generates hidden fields for all form fields submitted to this document which aren't already contained in another input field.

Example:

    <FORM ACTION="inhalt.htm" METHOD="GET">
	<INPUT TYPE="TEXT" NAME="field1">
    [$ hidden $]
    </FORM>

If you request this with http://host/doc.htm?field1=A&field2=B&field3=C

the output will be

    <FORM ACTION="inhalt.htm" METHOD="GET">
	<INPUT TYPE="TEXT" NAME="feld1" VALUE="A">
	
    <INPUT TYPE="HIDDEN" NAME="field2" VALUE="B">
    <INPUT TYPE="HIDDEN" NAME="field3" VALUE="C">
    </FORM>

NOTE: This should only be used for a small amount of data, since the hidden fields are sent to the browser, which sends it back with the next request. If you have a large amount of data, store it in a file with a unique name and send only the filename in a hidden field. Be aware of the fact that the data can be changed by the browser if the user doesn't behave exactly as you expect. Users have a nasty habit of doing this all of the time. Your program should be able to handle such situations properly.

The var command declares one or more variables for use within this Embperl document and sets the strict pragma. The variable names must be supplied as a space-separated list.

Example: [$var $a %b @c $]

This is the same as writing the following in normal Perl code:

use strict ; use vars qw($a %b @c) ;

NOTE 1: `use strict' within an Embperl document will only apply to the block in which it occurs.

(Only Embperl 1.2b5 and above)

Defines a Embperl subroutine. Example:

  [$ sub foo $]
    <p> Here we do something </p>
  [$ endsub $]

You can call this subroutine either as a normal Perl subroutine

  [- foo -]

or via the Embperl::Execute function.

  [- Execute ('#foo')           # short form -]
  [- Execute ({ sub => 'foo'})  # long form  -]

The difference is that the Execute function will reset the internal states of Embperl like they were before the subrountine call, when the subroutine returns.

You may also pass Parameters to the subroutine:

  [$ sub foo $]
    [- $p = shift -]
    <p> Here we show the first parameter [+ $p +]</p>
  [$ endsub $]

  
  [- foo ('value') -]

In Embperl 2.0.2 and up you can use a shortcut syntax for passing parameters:

    [$ sub foo ($p) $]
     <p> Here we show the first parameter [+ $p +]</p>
    [$ endsub $]

This behaves the same as the example above, but in addition the parameters defined in this way are lexcialy scoped and therefore only available inside the subroutine.

In addtion you can define some initial Perl code for the subroutine:

   [$ sub foo ($a, $b)
   my $c = $a + $b ;
   $]
     <p> The result is [+ $c +]</p>
   [$ endsub $]

If you have a couple of commonly used subroutines you can define then in one file and import them into the modules where they are necessary:

  [- Execute ({ inputfile => 'mylib.htm', import => 1 }) -]

This will import all subroutines from the file mylib.htm into the current page where they could call just as a normal Perl subroutine.

Embperl 2.1.1 and above.

dump can be used to output the values of variables either to the output or to logfiles. The first parameter specifies the output channel:

	out
	Output to the page output
	pre
	Same as out, but surrounded with a <pre> tag. This is the default, if the output parameter is omitted.
	log
	Output to embperl log file
	err
	Output to stderr, which normally goes to the httpd error log.

If the output parameter is omitted, pre is assumed.

The following parameter can be a literal text (in quotes) or a list of variables.

Example:

  [$ dump err 'dump test', %fdat $]

  [$ dump %fdat, $i, @array $]

Embperl can generate dynamic tables (one- or two-dimensional). You only need to specify one row or column.

Embperl generates as many rows or columns as necessary. This is done by using the magic variables $row, $col, and $cnt. If you don't use $row/$col/$cnt within a table, Embperl does nothing and simply passes the table through.

Embperl checks if any of $row, $col, or $cnt is used. Embperl repeats all text between <table> and </table>, as long as the expressions in which $row or $cnt occurs are defined.

Embperl repeats all text between <tr> and </tr>, as long as the expressions in which $col or $cnt occurs are defined.

See also $tabmode (below) for end-of-table criteria.

Examples: (see eg/x/table.htm for more examples)

 [- @k = keys %ENV -]
 <TABLE>
     <TR>
         <TD>[+ $i=$row +]</TD>
         <TD>[+ $k[$row] +]</TD>
         <TD>[+ $ENV{$k[$i]} +]</TD>
     </TR> 
 </TABLE>

This will show all entries in array @k (which contains the keys from %ENV), so the whole environment is displayed (as in the while example), with the first column containing the zero-based index, the second containing the content of the variable name, and the third the environment variable's value.

This could be used to display the result of a database query if you have the result in an array. You may provide as many columns as you need. It is also possible to call a 'fetch' subroutine in each table row.

Lists and dropdowns or list boxes are treated exactly as one- dimensional tables. Only $row, $maxrow, $col, $maxcol and $tabmode are honored. $col and $maxcol are ignored. See eg/x/lists.htm for an example.

Embperl checks if there is a value from the form data for a specific option in a menu. If so, this option will be pre-selected.

Example:

<FORM METHOD="POST"> <P>Select Tag</P>

  If you request this document with list.htm?SEL1=x
  you can specify that the element which has a value
  of x is initially selected

  <P><SELECT NAME="SEL1">
     <OPTION VALUE="[+ $v[$row] +]">
        [+ $k[$row] +]
     </OPTION>
  </SELECT></P>
</FORM>

The INPUT tag interacts with the hashes %idat and %fdat. If the input tag has no value and a key exists with the same text as the NAME attribute of the input tag, Embperl will generate a VALUE attribute with the corresponding value of the hash key. All values of <INPUT> tags are stored in the hash %idat, with NAME as the hash key and VALUE as the hash value. Special processing is done for TYPE=RADIO and TYPE=CHECKBOX. If the VALUE attribute contains the same text as the value of the hash the CHECKED attribute is inserted, else it is removed.

So, if you specify, as the ACTION URL, the file which contains the form itself, the form will be redisplayed with same values as entered the first time. (See eg/x/neu.htm for an example.)

The TEXTAREA tag is treated exactly like other input fields.

<meta http-equiv= ... > will over-ride the corresponding http header. This keeps Netscape from asking the user to reload the document when the content-type differs between the http header and the meta http-equiv.

This can also be used to set http headers. When running under mod_perl http-headers can also be set by the function header_out

    Example of how to set a http header:

    <META HTTP-EQUIV="Language" CONTENT="DE">

    This is the same as using the Apache function

    [- $req_rec -> header_out("Language" => "DE"); -]

The output of perl blocks inside the HREF attribute of the A Tags and the SRC attribute of the other Tags are URL escaped instead of HTML escaped. (see also $escmode). Also, when inside such a URL, Embperl expands array and hash references to URL parameter syntax. Example:

  [-
  $A = { A => 1, B => 2 } ;  # Hashreference
  @A = (X, 9, Y, 8, Z, 7)
  -]

  <A HREF="http://localhost/tests?[+ $A  +]">  
  <A HREF="http://localhost/tests?[+ \@A +]">

is expanded by Embperl to

  <A HREF="http://localhost/tests?A=1&amp;B=2">
  <A HREF="http://localhost/tests?X=9&amp;Y=8&Z=7">