)
=item optDisableMetaScan = 4096
Disables processing of all meta tags. ( )
=item optAllFormData = 8192
This option will cause Embperl to insert all formfields in %fdat and @Z<>ffld, even if they
are empty. Empty formfields will be inserted with an empty string. Without this option
empty formfields will not be insert in %fdat and @Z<>ffld.
=item optRedirectStdout = 16384
Redirects STDOUT to the Embperl output stream before every request and resets it afterwards.
If set, you can use a normal Perl B inside any Perl block to output data.
Without this option you can only output data by using the [+ ... +] block, or printing
to the filehandle B.
=item optUndefToEmptyValue = 32768
Normally if there is no value in %fdat for a specific input field, Embperl will leave
it untouched. When this option is set, Embperl will handle the field as if an empty
string was stored in %fdat for the field.
=back
=head2 EMBPERL_DEBUG
This is a bitmask which specifies what should be written to the log.
The following values are defined:
=over 4
=item dbgStd = 1
Show minimum information.
=item dbgMem = 2
Show memory and scalar value allocation.
=item dbgEval = 4
Show arguments to and results of evals.
=item dbgCmd = 8
Show metacommands and HTML tags which are processed.
=item dbgEnv = 16,
List every request's environment variables.
=item dbgForm = 32
Lists posted form data.
=item dbgTab = 64
Show processing of dynamic tables.
=item dbgInput = 128
Show processing of HTML input tags.
=item dbgFlushOutput = 256
Flush Embperl's output after every write. This should only be set to
help debug Embperl crashes, as it drastically slows down Embperl's
operation.
=item dbgFlushLog = 512
Flush Embperl's logfile output after every write. This should only be
set to help debug Embperl crashes, as it drastically slows down
Embperl's operation.
=item dbgAllCmds = 1024
Logs all commands and HTML tags, whether or not they are really
excuted or not. (It logs a `+' or `-' to tell you if they are
executed.)
=item dbgSource = 2048
Logs the next piece of the HTML source to be processed. (NOTE: This
generates a lot of output!)
=item dbgFunc = 4096
This is only anvailable when Embperl is compiled with -DEPDEBUGALL,
and is normally only used for debugging Embperl itself. Records all
function entries to the logfile.
=item dbgLogLink = 8192
Inserts a link at the top of each page which can be used to view the
log for the current HTML file. See also L<"EMBPERL_VIRTLOG">.
Example:
SetEnv EMBPERL_DEBUG 10477
SetEnv EMBPERL_VIRTLOG /embperl/log
SetHandler perl-script
PerlHandler HTML::Embperl
Options ExecCGI
=item dbgDefEval = 16384
Shows every time new Perl code is compiled.
=item dbgCacheDisable = 32768
Disables the use of the p-code cache. All Perl code is recompiled
every time. (This should not be used in normal operation as it slows
down Embperl dramatically.) This option is only here for debugging
Embperl's cache handling. There is no guarantee that Embperl behaves
the same with and without cache (actually is does not!)
=item dbgHeadersIn = 262144
Log all HTTP headers which are sent from the browser.
=item dbgShowCleanup = 524288
Show every variable which is undef'd at the end of the request. For
scalar variables, the value before undef'ing is logged.
=back
A good value to start is C<2285> or C<10477> if you want to view the
logfile with your browser. (Don't forget to set EMBPERL_VIRTLOG.) If
Embperl crashes, add C<512> so the logfile is flushed after every line
is written and you can see where Embperl is when it crashes.
=head2 EMBPERL_INPUT_FUNC
This directive gives you the possiblity to specify a non-standard way
of fetching input. Normally, Embperl reads its input (source) from
a file (or gets it from a scalar if you use C). Here, you can
give the name of a Perl function which is called instead of reading the
input from a file. The function must look like the following:
InputFunc ($r, $in, $mtime, additional parameters...) ;
=over 4
=item B<$r>
Apache Request Record (see B for details)
=item B<$in>
a reference to a scalar, to which the input should be returned.
Example:
open F, "filename" ;
local $\ = undef ;
$$in = ;
close F ;
=item B<$mtime>
a reference to a scalar, to which the modification time should be returned.
Example:
$$mtime = -M "filename" ;
=back
You can give B (which must be comma-separated) to B
which will then pass them as a string.
Example:
PerlSetEnv EMBPERL_INPUT_FUNC "InputFunc, foo, bar"
will call
InputFunc ($r, $in, $mtime, 'foo', 'bar') ;
to get the input.
B
sub Input
{
my ($r, $in, $mtime) = @_ ;
open F, $r -> filename or return NOT_FOUND ;
local $\ = undef ;
$$in = ;
close F ;
$$mtime = -M $r -> filename ;
return 0 ;
}
See also L below,
for an input function which comes with Embperl.
=head2 EMBPERL_OUTPUT_FUNC
This directive allows you to specify a non-standard way
of dealing with output. Normally, Embperl sends its output (source) to
a file/the browser (or to a scalar if you use C). Here, you can
give the name of a Perl function which is called instead of sending the
output to a file/the browser. The function must look like the following:
InputFunc ($r, $out, additional parameters...) ;
=over 4
=item B<$r>
Apache Request Record (see B for details)
=item B<$out>
Output from Embperl
=back
You can give B (which must be comma-separated) to B,
which will then pass them as a string.
Example:
PerlSetEnv EMBPERL_OUTPUT_FUNC "OutputFunc, foo, bar"
will call
OutputFunc ($r, $out, 'foo', 'bar') ;
for output.
B
sub Output
{
my ($r, $out) = @_ ;
$r -> send_http_header ;
$r -> print ($$out) ;
return 0 ;
}
See also L below,
for an output function which comes with Embperl.
=head2 EMBPERL_MAILHOST
Specifies which host the L function uses as SMTP server.
Default is B.
=head1 SYNTAX
Embperl understands four categories of commands. The first three are
special Embperl commands, and the last 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.,
`<' 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.
B If you do use an ASCII editor to write your HTML documents,
you should set the option B so that Embperl does not
preprocess your source. You can also HTML-escape your code
(i.e. write `<' 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.
B
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 B take) `['
and `]' as normal text, there should be no problem.
=head2 [+ 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 L<"(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)
C Whitespace is ignored. The output will be automatically
HTML-escaped (e.g., `<' is translated to `<') depending on the
value of the variables C<$escmode>. You do not have to worry about
it.
=head2 [- 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.
[- $i=0; while ($i<5) {$i++} -] Even more complex
statements or multiple
statements are possible.
C 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.
C To define subroutines, use L<"[! Perl Code !]"> (see below) instead of
[- ... -] to avoid recompilation of the subroutine on every request.
=head2 [! 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.
=head2 [$ Cmd Arg $] (Meta-Commands)
Execute an Embperl metacommand. B can be one of the following.
(B varies depending on ).
=over 4
=item B, B, B, B
Everything following the B metacommand until the B,
B, or B is only output if the Perl expression given in
B is true. B and B work similarly.
Example:
[$ if $ENV{REQUEST_METHOD} eq 'GET' $]
Method was GET
[$ else $]
Method other than GET used
[$ endif $]
This will send one of the two sentences to the client, depending on the
request method used to retrieve the document.
=item B, B
Executes a loop until the B given to B is false.
Example: (see eg/x/while.htm)
[- $i = 0; @k = keys %ENV -]
[$ while ($i < $#k) $]
[+ $k[$i] +] = [+ $ENV{$k[$i]} +]
[- $i++ -]
[$ endwhile $]
This will send a list of all environment variables to the client.
NOTE: The `<' is translated to `<' before calling Perl eval,
unless optRawInput is set.
=item B, B
Executes a loop until the B given to B is true.
Example:
[- $i = 0 -]
[$ do $]
[+ $i++ +]
[$ until $i > 10 $]
=item B, B
Executes a loop for each element of the second B, setting the
first B accordingly.
Example:
[- @arr = (1, 3, 5) -]
[$ foreach $v @arr $]
[+ $v +]
[$ endforeach $]
=item B
B consists of zero, one or two names of hashes (with or without
the leading %) and an optional array as third parameter. The
B 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 C<%fdat>, C<%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:
If you request this with
http://host/doc.htm?field1=A&field2=B&field3=C
the output will be
C 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 change 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.
=item B
The var command declares one or more variables for use within this
Embperl document and sets the B pragma. The variable names
must be supplied as 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.
=back
=head2 HTML Tags
Embperl recognizes the following HTML tags specially. All others are
simply passed through, as long as they are not part of a Embperl
command.
=over 4
=item B, B, B
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 , as long the expressions in
which $row or $cnt occurs is/are defined.
Embperl repeats all text between and , as long the
expressions in which $col or $cnt occurs is/are defined.
See also L<"$tabmode"> (below) for end-of-table criteria.
Examples: (see eg/x/table.htm for more examples)
[- @k = keys %ENV -]
[+ $i=$row +]
[+ $k[$row] +]
[+ $ENV{$k[$i]} +]
This will show all entries in array @k (which contains the keys from
%ENV), so the whole environment is displayed (as in the B
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.
=item B, B
The tag is interpreted as a table heading. If the whole row is made
up of instead of , 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.
=item B, B, B, B , B ,
B, B, B, B
Lists and dropdowns or list boxes are treated exactly as one-
dimensional tables. Only L<"$row">, L<"$maxrow">, L<"$col">, L<"$maxcol"> and L<"$tabmode">
are honored. $col and $maxcol are ignored. See eg/x/lists.htm for an
example.
=item B
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:
=item B
The INPUT tag interacts with the hashes C<%idat> und C<%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 tags are stored in the hash C<%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.)
=item B
The TEXTAREA tag is treated exactly like other input fields.
=back
=item B
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 B
Example of how to set a http header:
This is the same as using the Apache function
[- $req_rec -> header_out("Language" => "DE"); -]
=head1 Variable scope and cleanup
The scope of a variable declared with B or B ends at the
end of the enclosing [+/- ... -/+] block; the [+/- ... -/+] blocks act
much like Perl's { ... } in that regard.
Global variables (everything not declared with B or B) 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 B. (See also
L<"(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 declare them in
another package (i.e., $Persistent::handle instead of $handle).
If you use the strict pragma, you can use the B metacommand to
declare your variables.
C 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
B or the B parameter of the B
function.
If you like to do your own cleanup you can define a subroutine B
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 ; } !]
=head1 Predefined variables
Embperl has some special variables which have a predefined meaning.
=head2 %ENV
Contains the environment as seen from a CGI script.
=head2 %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.
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:
Embperl ACTION:
[- if (defined $fdat{ImageName}) {
open FILE, "> /tmp/file.$$";
print FILE $buffer
while read($fdat{ImageName}, $buffer, 32768);
close FILE;
}
-]
=head2 @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.
=head2 %idat
Contains all the values from all input tags processed so far.
=head2 %udat (only 1.2b1 or higher)
You can use B<%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 fill the %udat hash from Apache::Session
with just the same values as you have stored for that user. (See also L<"Session handling">)
=head2 $row, $col
Row and column counts for use in dynamic tables.
(See L<"HTML tag table"|"HTML Tags">.)
=head2 $maxrow, $maxcol
Maxium number of rows or columns to display in a table. To prevent
endless loops, $maxrow defaults to 100 and $maxcol to 10.
(See L<"HTML tag table"|"HTML Tags">.)
=head2 $cnt
Contains the number of table cells displayed so far.
(See L<"HTML tag table"|"HTML Tags">.)
=head2 $tabmode
Determines how the end of a dynamic table is detected:
B
=over 4
=item B<1>
End when an expression with $row becomes undefined. The row
containing the undefined expression is B displayed.
=item B<2>
End when an expression with $row becomes undefined. The row
containing the undefined expression B displayed.
=item B<4>
End when $maxrow rows have been displayed.
=back
B
=over 4
=item B<16>
End when an expression with $col becomes undefined. The column
containing the undefined expression is B displayed.
=item B<32>
End when an expression with $col becomes undefined. The column
containing the undefined expression B displayed.
=item B<64>
End when $maxcol columns have been displayed.
=back
The default is B<17>, which is correct for all sort of arrays. You
should rarely need to change it. The two values can be added
together.
=head2 $escmode
Turn HTML and URL escaping on and off. The default is on ($escmode =
3).
=over 4
=item B<$escmode = 3>
The result of a Perl expression is HTML-escaped (e.g., `>' becomes
`>') in normal text and URL-escaped (e.g., `&' becomes `%26')
within an tag.
=item B<$escmode = 2>
The result of a Perl expression is always URL-escaped (e.g., `&'
becomes `%26').
=item B<$escmode = 1>
The result of a Perl expression is always HTML-escaped (e.g., `>'
becomes `>').
=item B<$escmode = 0>
No escaping takes place.
=back
=head2 $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 B for more information.
=head2 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, 'HTML::Embperl::Log';
to get a handle by which you can write to the Embperl logfile.
=head2 OUT
This filehandle is tied to Embperl's output stream. Printing to it has the same effect
as using the [+ ... +] block. (See also L)
=head2 @param
Will be setup by the B<'param'> parameter of the B function. Could be used
to pass parameters to an Embperl document and back. (see
L
for further docs)
=head2 $optXXX $dbgXXX
All options (see L<"EMBPERL_OPTIONS">) and all debugging flags (see L<"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
=head1 Session handling
From 1.2b1 and higher Embperl is able to handle per user sessions for you. You can store any data
in the L<%udat> hash and if the same user request again an Embperl document, you will see the same
values in that hash again.
To configure Embperl to do session management for you, you must have installed Apache::Session and
loaded it before you load Embperl and you must tell Embperl which storage you would like to use for
Apache::Session, by setting the environement variable EMBPERL_SESSION_CLASS.
You may have a startup.pl for your httpd which looks like this:
$ENV{EMBPERL_SESSION_CLASS}='File' ;
use Apache::Session::File ;
use HTML::Embperl ;
1 ;
NOTE: You can use all the environement variables recognized by Apache::Session to configure it.
Now you are able to use the %udat hash for your user sessions. As long as you don't touch %udat
Embperl will not create any session, also Apache::Session is 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
it's id, while the data is stored by Apache::Session. (Further version may also be able to use
URL rewriting for storing the id).
B
=head1 (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
B. NOTE: By explicitly specifying a package name, you
can access data that is used by another document.
If Embperl is used by more then one person, it may be neccessary to
really 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
B to B. The default package name
used is the same as in normal operation and can be changed with
B. NOTE: From the perspective of the document being
executed, the code is running in the package B!
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 = HTML::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 B in
B and specify from which compartment the opcode mask
should be taken by setting B.
Example (for use with mod_perl):
B
PerlScript startup.pl
SetEnv EMBPERL_DEBUG 2285
Alias /embperl /path/to/embperl/eg
SetHandler perl-script
PerlHandler HTML::Embperl
Options ExecCGI
PerlSetEnv EMBPERL_OPTIONS 12
PerlSetEnv EMBPERL_COMPARTMENT test
B
$cp = HTML::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 B used!
Look at the documentation of Safe.pm and Opcode.pm for more detailed
information on how to set opcode masks.
=head1 Utility Functions
=head2 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 L<"(Safe-)Namespaces and opcode restrictions"> for details on how Embperl uses compartments.
Example:
$cp = HTML::Embperl::AddCompartment('TEST');
$cp->deny(':base_loop');
=head2 MailFormTo($MailTo, $Subject, $ReturnField)
Sends the content of the hash %fdat in the order specified by @Z<>ffld to
the given B<$MailTo> addressee, with a subject of B<$Subject>.
If you specify $ReturnField the value of that formfield will be used
as B. 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