/ 
Embperl-2.0b10
River stage one • 3 direct dependents • 3 total dependents
/ Embperl

NAME

Embperl - Building dynamic Websites with Perl

SYNOPSIS

DESCRIPTION

Embperl is a framework for building websites with Perl.

For the beginner it's any easy to setup and use way of embedding Perl code in HTML pages.

It delivers several features that ease the task of creating a websites, including dynamic tables, formfield-processing, escaping/unescaping, session handling, caching and more.

If your demands grows it gives you the power to make your Web site object-oriented and build it out of small reusable components. If you don't like the idea of mixing up all your layout and code Embperl supports separating it in different objects (e.g. createing an MVC application). Of course Embperl doesn't ties you to HTML, it allows components to be from different source formats (e.g. HTML, WML, XML, POD, ...) and if necessary transforms it (for example via XSLT) to other output formats. This is achieved by diving the output generation in small steps, where each is processed by a plugable provider.

Advanced user can create their own syntax definitions (for example tag libraries) and extent Embperl by writing their own providers and much more

SYNTAX

Embperl understands two categories of commands. The first one are special Embperl commands, and the second category consists of some HTML tags which can trigger special processing. Embperl commands can span multiple lines and need not start or end at a line boundary.

Before the special Embperl commands are processed, and for the VALUE attribute of the INPUT tag (see below), all HTML tags are removed and special HTML characters are translated to their ASCII values (e.g., `&lt;' is translated to `<'). You can avoid this behavior by preceding the special character or HTML tag with a backslash. This is done in case your favorite (WYSIWYG) HTML editor inserts tags like line breaks or formatting into your Embperl commands where you don't want them.

VERY IMPORTANT NOTE: If you do use an ASCII editor to write your HTML documents, you should set the option optRawInput so that Embperl does not preprocess your source. You can also HTML-escape your code (i.e. write `&lt;' instead of `<'), to avoid ambiguity. In most cases it will also work without the optRawInput and HTML-escaping, but in some cases Embperl will detect an HTML tag were there isn't one.

If you have any trouble with your code, especially with HTML tags or filehandles in your Perl code, be sure to understand input- and output- escaping and unescaping. Read the section "Inside Embperl" to see what's going on!!

All Embperl commands start with a `[' and end with a `]'. To get a real `[' you must enter `[['.

Embperl does not use SGML comments (i.e., <! ... !> or similar things) because some HTML editors can't create them, or it's much more complicated. Since every HTML editor takes (or should take) `[' and `]' as normal text, there should be no problem.

[+ Perl code +]

Replace the command with the result you get from evaluating the Perl code. The Perl code can be anything which can be used as an argument to a Perl eval statement. (See "(Safe-)Namespaces and opcode restrictions" below for restrictions.) Examples:

[+ $a +]        Replaces the [+ $a +] with the content of
                the variable $a

[+ $a+1 +]      (Any expression can be used)

[+ $x[$i] +]    (Arrays, hashes, and more complex
                expressions work)

NOTE: Whitespace is ignored. The output will be automatically HTML-escaped (e.g., `<' is translated to `&lt;') depending on the value of the variables $escmode. You do not have to worry about it.

[- Perl code -]

Executes the Perl code, but deletes the whole command from the HTML output.

Examples:

[- $a=1 -]            Set the variable $a to one.
		       No output will be generated.

[- use SomeModule ;  -]  You can use other modules. NOTE the semicolon!

[- $i=0; while ($i<5) {$i++} -]  Even more complex
                                 statements or multiple
                                 statements are possible.

NOTE: Statements like if, while, for, etc., must be contained in a single Embperl command. You cannot have the if in one command block and the terminating `}' or else in another.

NOTE: To define subroutines, use "[! Perl Code !]" (see below) instead of [- ... -] to avoid recompilation of the subroutine on every request.

[! Perl Code !]

Same as [- Perl Code -] with the exception that the code is only executed at the first request. This could be used to define subroutines, or do one-time initialization.

[* Perl code *]

(only version 1.2b2 or higher) EXPERIMENTAL!

This is similar to [- Perl Code -]. The main difference is, while [- Perl Code -] always has its own scope, all [* Perl code *] blocks runs in the same scope. This allows you to define "local" variables with a scope of the whole page. Normally, you don't need to use local, because Embperl takes care of separate namespaces of different documents and cleanup after the request is finished, but in special cases it's necessary. For example, if you want to recursively call an Embperl document via Execute.

There is a second reason to use the [* Perl code *] instead of the [- Perl Code -]. If you like to use perl's control structures. Perl's if, while, for etc. can not span mulitple [- Perl Code -] blocks, but it can span multiple [* Perl Code *].

Example:

[* foreach $i (1..10) { *]
  
  [- $a = $i + 5 -]
  loop count + 5 = [+ $a +] <br>

[* } *]

The following B<won't> work:

[- foreach $i (1..10) { -]
  some text here <br>
[- } -]

The same can be done with Embperl meta commands (see below)

[$ foreach $i (1..10) $]
  
  [- $a = $i + 5 -]
  loop count + 5 = [+ $a +] <br>

[$ endforeach $]

NOTE 1: [* ... *] blocks _must_ always end with a ;,{ or }

NOTE 2: [* ... *] cannot apear inside a html tag that is interpreted by Embperl (unless you disable the interpretation of such tags like table, input etc.)

NOTE 3: There are still benefits of using [- ... -] and metacommands: - much better debugging in the log file. - no restriction on where they can be used. You can use them anywhere; even inside html tags that are interpreted by Embperl.

[# Some Text #] (Comments)

(only version 1.2b2 or higher)

This is a comment block. Everything between the [# and the #] will be removed from the output.

NOTE 1: The [* ... *] blocks are interpreted before the comment block, so they are executed also inside a comment.

NOTE 2: Everything (except [* ... *]) is really removed from the source, so you can also use the [# ... #] block to take a part out of your document.

[$ Cmd Arg $] (Meta-Commands)

Execute an Embperl metacommand. Cmd can be one of the following. (Arg varies depending on <Cmd>).

if, elsif, else, endif

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.

while, endwhile

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

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

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

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

NOTE: The `&lt;' is translated to `<' before calling Perl eval, unless optRawInput is set.

do, until

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

Example:

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

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 $]
next

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

[* next if ($foo) *]
last

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

[* last if ($foo) *]
redo

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

[* redo if ($foo) *]
hidden

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.

var

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.

sub

(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. Also Execute could handle recursive call, which currently not work when calling it as a Perl subroutine.

You may also pass Parameters to the subroutine:

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


[- foo ('value') -]

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 neccesary:

[- 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.

HTML Tags

Embperl recognizes the following HTML tags in a special way. All others are simply passed through, as long as they are not part of a Embperl command.

TABLE, /TABLE, TR, /TR

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.

TH, /TH

The <TH> tag is interpreted as a table heading. If the whole row is made up of <TH> </TH> instead of <TD> </TD>, it is treated as a column heading. Everything else will be treated as row headings in the future, but are not now: everything else is ignored in the current version.

DIR, MENU, OL, UL, DL, SELECT, /DIR, /MENU, /OL, /UL, /DL, /SELECT

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.

OPTION

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>
INPUT

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.)

TEXTAREA, /TEXTAREA

The TEXTAREA tag is treated exactly like other input fields.

META HTTP-EQUIV=

<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"); -]
A, EMBED, IMG, IFRAME, FRAME, LAYER

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">

Variable scope and cleanup

The scope of a variable declared with my or local ends at the end of the enclosing [+/- ... -/+] block; the [+/- ... -/+] blocks act much like Perl's { ... } in that regard.

Global variables (everything not declared with my or local) will be undef'ed at the end of each request, so you don't need to worry about any old variables laying around and causing suspicious results. This is only done for variables in the package the code is eval'ed in -- every variable that does not have an explicit package name. All variables with an explicit package name (i.e., in modules you use) will stay valid until the httpd child process dies. Embperl will change the current package to a unique name for every document, so the influence between different documents is kept to a minimum. You can set the name of the package with EMBPERL_PACKAGE. (See also "(Safe-)Namespaces and opcode restrictions".)

Since a CGI script is always a process of its own, you don't need to worry about that when you use Embperl as a CGI script.

If you need to declare variables which need to live longer than just one HTTP request (for example, a database handle), you must either put it's name in the hash %CLEANUP or declare them in another package (i.e., $Persistent::handle instead of $handle).

If you want to use the strict pragma, you can do this by using the var metacommand to declare your variables.

NOTE: Bacause Apache::DBI has its own namespace, this module will work together with Embperl to maintain your persistent database connection.

You can disable the automatic cleanup of global variables with EMBPERL_OPTIONS or the cleanup parameter of the Execute function.

You can define exceptions to the cleanup rule with the hash %CLEANUP.

If you like to do your own cleanup you can define a subroutine CLEANUP in your document. This will be called right before the variables are cleaned up, but after the connection to the client is closed.

EXAMPLE:

 [! sub CLEANUP { close FH ; } !]

Predefined variables

Embperl has some special variables which have a predefined meaning.

%ENV

Contains the environment as seen from a CGI script.

$epreq

Contains a reference to the Embperl request object. This is the same as adding $epreq = shift at the top of each page.

$epapp

Contains a reference to the Embperl application object. This is the same as $epreq - app> would return.

%fdat

Contains all the form data sent to the script by the calling form. The NAME attribute builds the key and the VALUE attribute is used as the hash value. Embperl doesn't care if it is called with the GET or POST method, but there may be restrictions on the length of parameters using GET -- not from Embperl, but perhaps from the web server, especially if you're using Embperl's CGI mode -- it is safer to use POST.

If multiple fields with the same name are sent to a Embperl page, they will put in the same hash element and separated be tabs. You can split it up in an array, by writting:

@array = split (/\t/, $fdat{'fieldname'}) ;

Embperl also supports ENCTYPE multipart/form-data, which is used for file uploads. The entry in %fdat corresponding to the file field will be a filehandle, as with CGI.pm. (Embperl uses CGI.pm internally to process forms encoded with multipart/form-data.)

File upload example:

  HTML page:

    <FORM METHOD="POST" ENCTYPE="multipart/form-data">
      <INPUT TYPE="FILE" NAME="ImageName">
    </FORM>

  Embperl ACTION:

    [- if (defined $fdat{ImageName}) {
         open FILE, "> /tmp/file.$$";
	 print FILE $buffer
           while read($fdat{ImageName}, $buffer, 32768);
         close FILE;
       }
    -]

When you have installed CGI.pm 2.46 or above, you may also retrieve the filename (local filename, as it was on the browser side) and the information provided by the CGI.pm uploadInfo function. To get the filename, simply print out the value of the corresponding %fdat entry, instead of using it as a filehandle. To get the uploadInfo use the fieldname with a dash in front of it:

Example:

# ImageName is the NAME of the field, you must replace it with whatever 
# name is given in your HTML code
Filename:      [+ $fdat{ImageName} +] <br>
Content-Type:  [+ $fdat{-ImageName} -> {'Content-Type'} +] <br>

NOTE: The way uploadInfos are accessed before 1.2b11 is not supported anymore.

NOTE: This works the other way as well: any input fields with names that are %fdat keys, and without values, will have their values automatically set to the appropriate %fdat value. See "HTML Tags" INPUT/OPTION/TEXTAREA.

@ffld

Contains all the field names in the order in which they were sent by the browser. This is normally -- but not necessarily -- the order in which they appear in your form.

%idat

Contains all the values from all input tags processed so far.

%udat (only 1.2b1 or higher)

You can use %udat to store per user data. As long as you don't use %udat, nothing happens, but as soon as you write anything to %udat, Embperl creates a session id and sends it via a cookie to the browser. The data you have written to %udat is stored by Apache::Session. The next time the same user request an Embperl page, the browser sends the cookie with the session id back and Embperl fills the %udat hash from Apache::Session with the same values as you have stored for that user. (See also "Session handling")

%mdat (only 1.2b2 or higher)

You can use %mdat to store per module/page data. As long as you don't use %mdat, nothing happens, but as soon as you write anything to %mdat, Embperl creates a session id and stores the data via Apache::Session. The next time any user hits the same Embperl page, Embperl fill the %mdat hash from Apache::Session with the same values as you have stored within the last request to that page. (See also "Session handling")

$row, $col

Row and column counts for use in dynamic tables. (See "HTML tag table".)

$maxrow, $maxcol

Maximum number of rows or columns to display in a table. To prevent endless loops, $maxrow defaults to 100 and $maxcol to 10. (See "HTML tag table".)

$cnt

Contains the number of table cells displayed so far. (See "HTML tag table".)

$tabmode

Determines how the end of a dynamic table is detected. Tables are always limited to the size specified in $maxrow and $maxcol, but can be ended early when the row ($row) and column ($col) variables become undefined. $tabmode operates as follows:

$tabmode = 1

End table looping when any one of the expressions in the table row using $row returns undefined. The row containing the undefined expression is not displayed. Only those expressions are observed which contain an access to the variable $row.

$tabmode = 2

End when an expression with $row becomes undefined. The row containing the undefined expression is displayed.

$tabmode = 4

End when $maxrow rows have been displayed.

end of row

$tabmode = 16

End table column looping when any one of the expressions in the table column using $col returns undefined. The column containing the undefined expression is not displayed. Only those expressions are observed which contain an access to the variable $col.

$tabmode = 32

End when an expression with $col becomes undefined. The column containing the undefined expression is displayed.

$tabmode = 64

End when $maxcol columns have been displayed.

The default is 17, which is correct for all sort of arrays. You should rarely need to change it. The two values can be added together.

$escmode

Turn HTML and URL escaping on and off. The default is on ($escmode = 3).

NOTE: Normaly you can disable escaping by preceeding the item that normaly is escaped with a backslash. While this is a handy thing, it could be very dangerous in situations, where content that is inserted by some user is redisplayed, because they can enter arbitary HTML and preceed them with a backslash to avoid correct escaping when their input is redisplayed again. To avoid this problem, add 4 to the values below. This will cause Embperl to ignore the backslash when it does output escaping at all. (only 1.3b4 and above)

NOTE 2: If you want to output binary data, you must set the escmode to zero. (only 1.3b6 and above)

$escmode = 8 (or 15) (2.0b4 and above)

The result of a Perl expression is always XML-escaped (e.g., `>' becomes `&gt;' and ' become &apos;).

$escmode = 3 (or 7)

The result of a Perl expression is HTML-escaped (e.g., `>' becomes `&gt;') in normal text and URL-escaped (e.g., `&' becomes `%26') within of A, EMBED, IMG, IFRAME, FRAME and LAYER tags.

$escmode = 2 (or 6)

The result of a Perl expression is always URL-escaped (e.g., `&' becomes `%26').

$escmode = 1 (or 5)

The result of a Perl expression is always HTML-escaped (e.g., `>' becomes `&gt;').

$escmode = 0

No escaping takes place.

$req_rec

This variable is only available when running under control of mod_perl. It contains the request record needed to access the Apache server API. See perldoc Apache for more information.

LOG

This is the filehandle of the Embperl logfile. By writing `print LOG "something"' you can add lines to the logfile. NOTE: The logfile line should always start with the pid of the current process and continue with a four-character signature delimited by a ':', which specifies the log reason.

Example: print LOG "[$$]ABCD: your text\n" ;

If you are writing a module for use under Embperl you can say

tie *LOG, 'Embperl::Log';

to get a handle by which you can write to the Embperl logfile.

OUT

This filehandle is tied to Embperl's output stream. Printing to it has the same effect as using the [+ ... +] block. (See also optRedirectStdout)

@param

Will be setup by the 'param' parameter of the Execute function. Could be used to pass parameters to an Embperl document and back. (see Execute for further docs)

%http_headers_out (only 1.2b10 and above)

You can put any http headers you want to send into this hash.

If you set a location header, Embperl will automaticly set the status to 301 (Redirect). Example:

[- $http_headers_out{'Location'} = "http://www.ecos.de/embperl/" -]

however, it is possible to specify a two element array for Location, the second element of which gives the desired HTTP status:

[- $http_headers_out{Location} = [ "http://www.ecos.de/embperl/", 303 ]; -]

Starting with version 1.3.2 all headers with the exception of "Content-Type" can take multiple values. For instance, if you wanted to set two cookies, you can proceed as follows:

[- $http_headers_out{'Set-Cookie'} = 
    ['name=cook1;value=2;','name=cook2;value=b'] ; -]

If you supply multiple values for "Location" or "Content-Type" via an array reference, then Embperl will simply use the first in the list. Empty arrays will be ignored. For instance, the following will neither change the status to 301 nor create a Location: line in the HTTP headers:

[- $http_headers_out{'Location'} = [] ; -]

see also META HTTP-EQUIV=

$optXXX $dbgXXX

All options (see "EMBPERL_OPTIONS") and all debugging flags (see "EMBPERL_DEBUG") can be read and set by the corresponding variables.

Example:

  [- $optRawInput = 1 -] # Turn the RawInput option on
  
  Now write something here

  [- $optRawInput = 0 -] # Turn the RawInput option off again


  [+ $dbgCmd +] # Output the state of the dbgCmd flag

There are a few exceptions, where the variables can only be read. Setting of such options must be done via the config-files. Read-only variables are:

$optDisableVarCleanup
$optSafeNamespace
$optOpcodeMask
$optDisableChdir
$optEarlyHttpHeader
$optDisableFormData
$optAllFormData
$optRedirectStdout
$optAllowZeroFilesize
$optKeepSrcInMemory

%CLEANUP

Embperl cleanups up only variables with are defined within the Embperl page. If you want Embperl to cleanup additional variables you can add them to the hash %CLEANUP, with the key set to the variable name and the value set to one. The other way you could prevent Embperl from cleaning up some variables, is by adding them to this hash, with values of zero.

%CLEANUPFILE (1.2b6+)

Same purpose as %CLEANUP, but you may add filenames. All variables defined inside that file will be cleaned up.

Session handling

From 1.2b1 and higher Embperl is able to handle per user sessions for you. You can store any data in the %udat hash and if the same user requests an Embperl document again, you will see the same values in that hash again.

From 1.2b2 and higher Embperl is able to handle per module/page persistent data for you. You can store any data in the %mdat hash and if any request comes to the same Embperl document, you will see the same values in that hash again.

Session handling has changed from 1.3.3 to 1.3.4 and 2.0b3 to 2.0b4. You must either install Apache::SessionX or set

PerlSetEnv EMBPERL_SESSION_HANDLER_CLASS "Embperl::Session"

to get the old behaviour. If you have Apache::SessionX installed, you don't have to make addtional configuration, otherwise you must do the following things. You are also able to override the Apache::SessionX defaults, by using the following parameters:

To configure Embperl to do session management for you, you must have installed Apache::Session (1.53 or higher) and tell Embperl which storage and locker classes you would like to use for Apache::Session. This is done by setting the environment variable EMBPERL_SESSION_CLASSES. If you want to use a MySQL database for storing your sessions, you may have a startup.pl for your httpd which looks like this:

BEGIN
   {
   $ENV{EMBPERL_SESSION_CLASSES} = "MySQL Semaphore" ;
   $ENV{EMBPERL_SESSION_ARGS}    = "DataSource=dbi:mysql:session UserName=test" ;
   } ;

use Embperl ;

or you may put this in the httpd/srm.conf:

PerlSetEnv EMBPERL_SESSION_CLASSES "MySQL Semaphore"
PerlSetEnv EMBPERL_SESSION_ARGS "DataSource=dbi:mysql:session UserName=test"
PerlModule Embperl ;

Refer to the Apache::Session docs (e.g. Apache::Session::Store::MySQL) on how to setup your database tables.

EMBPERL_SESSION_ARGS is a space separated list of name/value pairs, which gives additional arguments for Apache::Session classes.

Here is an example for using a filesystem based storage:

PerlSetEnv EMBPERL_SESSION_CLASSES "File Semaphore" PerlSetEnv EMBPERL_SESSION_ARGS "Directory=/path/to/your/sessions"

Refer to the Apache::Session docs to find out which other storage/locker methods are available.

EMBPERL_SESSION_CLASSES can (optionally) take two more classnames, which specify the class for serialization (Default: Storable) and for generating the id (Default: MD5).

NOTE: The above configuration works only with Apache::Session 1.52 and Embperl 1.3b5 or above. Older versions of Embperl only support Apache::Session 1.0x, which has different parameters for EMBPERL_SESSION_CLASSES (e.g. $ENV{EMBPERL_SESSION_CLASSES} = "DBIStore SysVSemaphoreLocker" ; ) Apache::Session 1.0x still works with this Embperl version.

Now you are able to use the %udat and %mdat hashes for your user/module sessions. As long as you don't touch %udat or %mdat, Embperl will not create any session, and Apache::Session is not loaded. As soon as you store any value to %udat, Embperl will create a new session and send a cookie to the browser to maintain its id, while the data is stored by Apache::Session. (Further version may also be able to use URL rewriting for storing the id). When you modify %mdat, Embperl will store the data via Apache::Session and retrieve it when the next request comes to the same page.

Functions/Methods for session handling

Embperl::Req::SetupSession ($req_rec, $Inputfile) [1.3b6+]

This can be used from a script that will later call Embperl::Execute to preset the session so it's available to the calling script.

$req_rec

Apache request record when running under mod_perl, undef otherwise.

$Inputfile

Name of file that will be later processed by Embperl. It is used to setup %mdat. If you don't pass the $Inputfile, %mdat is not setup.

Returns a reference to %udat or, if call in an array context, a reference to %udat and %mdat. See also CleanupSession.

Embperl::Req::GetSession / $r -> GetSession [1.3b6+]

Returns a reference to %udat or, if called in an array context, a reference to %udat and %mdat. This could be used by modules that are called from inside an Embperl page, where the session management is already setup. If called as a method $r must be a Embperl::Req object, which is passed as first parameter to every Embperl page in @_ .

Embperl::Req::CleanupSession / $r -> CleanupSession [1.3b6+]

Must be called at the end of a script by scripts that use SetupSession, but do not call Embperl::Execute. If called as a method $r must be a Embperl::Req object, which is passed as first parameter to every Embperl page in @_ .

Embperl::Req::DeleteSession / $r -> DeleteSession [1.3b6+]

Deletes the session data and removes the cookie from the browser. If called as a method $r must be a Embperl::Req object, which is passed as first parameter to every Embperl page in @_ .

Embperl::Req::RefreshSession / $r -> RefreshSession [1.3b6+]

Triggers a resend of the cookie. Normaly the cookie is only send the first time. If called as a method $r must be a Embperl::Req object, which is passed as first parameter to every Embperl page in @_ .

Embperl::Req::SetSessionCookie / $r -> SetSessionCookie [1.3b7+]

Must be called by scripts that use SetupSession, but do not call Embperl::Execute. This is neccessary to set the cookie for the session id, in case a new session is created, which is normaly done by Embperl::Execute. If called as a method $r must be a Embperl::Req object, which is passed as first parameter to every Embperl page in @_ .

(Safe-)Namespaces and opcode restrictions

Since most web servers will contain more than one document, it is necessary to protect the documents against each other. Embperl does this by using Perl namespaces. By default, Embperl executes every document in its own namespace (package). This will prevent documents from accidentally overriding the other's data. You can change this behavior (or simply the package name) with the configuration directive EMBPERL_PACKAGE. NOTE: By explicitly specifying a package name, you can access data that is used by another document.

If Embperl is used by more than one person, it may be neccessary to protect documents from each other. To do this, Embperl gives you the option of using safe namespaces. Each document runs in its own package and can't access anything outside of this package. (See the documentation of Safe.pm for a more detailed discussion of safe namespaces.)

To make a document run in a safe namespace, simply add optSafeNamespace to EMBPERL_OPTIONS. The default package name used is the same as in normal operation and can be changed with EMBPERL_PACKAGE. NOTE: From the perspective of the document being executed, the code is running in the package main!

A second option to make Embperl more secure is the use of the opcode restriction mask. Before you can use the opcode mask, you must set up a safe compartment.

B<$cp = Embperl::AddCompartment($name);>

This will create a new compartment with a default opcode mask and the name $name. (The name is used later to tell Embperl which compartment to use.) Now you can change the operator mask. For example:

B<$cp->deny(':base_loop');>

In your configuration you must set the option optOpcodeMask in EMBPERL_OPTIONS and specify from which compartment the opcode mask should be taken by setting EMBPERL_COMPARTMENT.

Example (for use with mod_perl):

   B<srm.conf:>

   PerlScript startup.pl

   SetEnv EMBPERL_DEBUG 2285

   Alias /embperl /path/to/embperl/eg

   <Location /embperl/x>
   SetHandler perl-script
   PerlHandler Embperl
   Options ExecCGI
   PerlSetEnv EMBPERL_OPTIONS 12
   PerlSetEnv EMBPERL_COMPARTMENT test
   </Location>

   B<startup.pl:>

   $cp = Embperl::AddCompartment('test');
   $cp->deny(':base_loop');

This will execute the file startup.pl on server startup. startup.pl sets up a compartment named `test', which will have a default opcode mask and additionaly, will have loops disabled. Code will be executed in a safe namespace.

NOTE: The package name from the compartment is NOT used!

Look at the documentation of Safe.pm and Opcode.pm for more detailed information on how to set opcode masks.

Utility Functions

AddCompartment($Name)

Adds a compartment for use with Embperl. Embperl only uses the opcode mask from it, not the package name. AddCompartment returns the newly- created compartment so you can allow or deny certain opcodes. See the Safe.pm documentation for details of setting up a compartment. See the chapter about "(Safe-)Namespaces and opcode restrictions" for details on how Embperl uses compartments.

Example:

$cp = Embperl::AddCompartment('TEST');
$cp->deny(':base_loop');

MailFormTo($MailTo, $Subject, $ReturnField)

Sends the content of the hash %fdat in the order specified by @ffld to the given $MailTo addressee, with a subject of $Subject. If you specify $ReturnField the value of that formfield will be used as Return-Path. Usually, this will be the field where the user enters his e-mail address in the form.

If you specifiy the following example code as the action in your form

<FORM ACTION="x/feedback.htm" METHOD="POST"
      ENCTYPE="application/x-www-form-urlencoded">

The content of the form will be mailed to the given e-mail address.

MailFormTo uses "EMBPERL_MAILHOST" as SMTP server or localhost if non given.

Example:

<HTML>
<HEAD>
<TITLE>Feedback</TITLE>
</HEAD>
<BODY>
       [- MailFormTo('webmaster@domain.xy',
                     'Mail from WWW Form', 'email') -]
       Your data has been successfully sent!
</BODY>
</HTML>

This will send an email with all the form fields to webmaster@domain.xy, with the Subject 'Mail from WWW Form' and will set the Return-Path of the mail to the address which was entered in the field with the name 'email'.

NOTE: You must have Net::SMTP (from the libnet package) installed to use this function.

exit

exit will override the normal Perl exit in every Embperl document. Calling exit will immediately stop any further processing of that file and send the already-done work to the output/browser.

NOTE 1: If you are inside of an Execute, Embperl will only exit this Execute, but the file which called the file containing the exit with Execute will continue.

NOTE 2: If you called exit with an argument it exits the whole request.

NOTE 3: If you write a module which should work with Embperl under mod_perl, you must use Apache::exit instead of the normal Perl exit (as always when running under mod_perl).

Performance

To get the best performace from Embperl, it is necessary to restrict logging to a minimum. You can drastically slow down Embperl if you enable all logging options. (This is why `make test' takes a while to run.) You should never enable dbgFlushOutput or dbgFlushLog in a production environment. More debugging options are useful for development where it doesn't matter if the request takes a little bit longer, but on a heavily-loaded server they should be disabled. Additionally the options optDisableChdir, optDisableHtmlScan, optDisableCleanup have consequences for the performance.

Also take a look at mod_perl_tuning.pod for general ideas about performance.

Bugs

None known.

Under perl5.004 there are memory leaks. This is not an Embperl bug, but can cause your httpd to grow endlessly when running under mod_perl. Please upgrade to perl5.004_04 to fix this. You should also upgrade to a mod_perl version higher than 1.07_01 as soon as possible, because until 1.07_01 there is a memory leak in Apache->push_handler.

Compatibility

I have tested Embperl successfully

on Linux 2.x with

perl5.004_04
perl5.005_03
perl5.6.0
perl5.6.1
perl5.8.3
apache_1.3.0 - apache_1.3.27, apache 2.0.45
apache_ssl (Ben SSL)
Stronghold 2.2
Stronghold 2.4.1
Apache_1.3.x with mod_ssl 2.x.x

I know from other people that it works on many other UNIX systems

on Windows NT 4.0 with

perl5.004_04
perl5.005
perl5.6.1
apache_1.3.0 - apache_1.3.27

on Windows 95/98 with

perl5.004_02 (binary distribution, only Offline Mode)
perl5.005_02 + apache_1.3.6

Support

Feedback and Bug Reports

Please let me know if you use or test this module. Bugs, questions, suggestions for things you would find useful, etc., are discussed on the Embperl mailing list. If you have a site that is using Embperl, I would love to mention it in list of sites using Embperl. Please drop me a mail with a short description, if your site uses Embperl.

The Embperl mailing list (embperl@perl.apache.org) is available for Embperl users and developers to share ideas, solve problems and discuss things related to Embperl To subscribe to this list, send mail to embperl-subscribe@perl.apache.org. To unsubscribe send email to embperl-unsubscribe@perl.apache.org .

There is an archive for the Embperl mailing list at http://www.ecos.de/~mailarc/embperl/

For mod_perl related questions you may search the mod_perl mailing list archive at http://forum.swarthmore.edu/epigone/modperl

Commerical Support

You can get free support on the mod_perl mailing list (see above). If you need commercial support, ecos can provide it for you. We offer:

  • Consulting and assitance for you and your programmers

  • Planning of your dynamic website

  • Creating of parts or a whole website

  • Fixing bugs in Embperl (also available for mod_perl)

  • Adding new features

You can reach us via http://www.ecos.de or info@ecos.de For more information about our support see

http://www.ecos.de/x/index.htm/support/eng_r_support.htm

How to Support the Developement of Embperl

If you use and like Embperl and want to support it's ongoing developement you have two possibilities:

  1. Send me patches for things you like to see in Embperl

  2. Buy commercial support (see above). Also you may get the same answers to your questions on the mailing list, by buying the commercial support you not only buy support for yourself and can be sure you get an answer, you also give us the possibility to put more power in the further developement of Embperl.

Links and Download

Information

mod_perl http://perl.apache.org/

mod_perl FAQ http://perl.apache.org/faq

Embperl http://perl.apache.org/embperl/

Embperl (german) http://www.ecos.de/embperl/

DBIx::Recordset ftp://ftp.dev.ecos.de/pub/perl/dbi

apache web server http://www.apache.org/

ben-ssl (free httpsd) http://www.apache-ssl.org/

stronghold (commerical httpsd) http://www.c2.net/

europe http://www.eu.c2.net/

other Apache modules http://perl.apache.org/src/apache-modlist.html

Download

mod_perl http://www.perl.com/CPAN/modules/by-module/Apache

Embperl ftp://ftp.dev.ecos.de/pub/perl/embperl

DBIx::Recordset ftp://ftp.dev.ecos.de/pub/perl/dbi

Debian packages http://www.cse.unsw.edu.au/~gusl/embperl

PPM for ActiveState http://theoryx5.uwinnipeg.ca/ppmpackages/

Informations on how to install Embperl can be found in INSTALL.pod

CVS

The latest developments are available via CVS. Look at "perldoc CVS.pod" for a detailed description.

Syntaxmodes for various editors

Emacs

From: Erik Arneson [erik@mind.net]

Here's the amount of documentation I've got right now.

They need to get mmm.el from this URL: http://mmm-mode.sourceforge.net/

Then download my mmm-embperl.el from this one: http://www.aarg.net/erik/mmm-embperl.el

The documentation for using these is included in those two elisp files.

VIM

Vim Syntaxfile for Vim 5.x & 6.x from Lukas Zapletal with syntax highliting for JavaScript, VBScript, Perl+Embperl, CSS and HTML, yellow background for Perl`s code (like M$ Interdev) and working Perl folding can be found at http://vim.sourceforge.net/script.php?script_id=61

Vim Syntaxfile from Steve Willer can be found at http://www.interlog.com/~willer/embperl.vim

Vim Syntaxfile from Kee Hinckley can be found at http://www.somewhere.com/software/

Dreamweaver

Dreamweaver extension which tells Dreamweaver not to touch Embperl code can be found at http://www.somewhere.com/software/

Author

G. Richter (richter@dev.ecos.de)

See Also

perl(1), mod_perl, Apache httpd

1 POD Error

The following errors were encountered while parsing the POD:

Around line 519:

Non-ASCII character seen before =encoding in '-> header_out("Language"'. Assuming CP1252