.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Embperl 3pm"
.TH Embperl 3pm "2023-01-22" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Embperl \- Building dynamic Websites with Perl
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
For a list of available Embperl documentation please view
Embperl::TOC with \fBperldoc\fR\|(1) or \fBman\fR\|(1). If Embperl is not yet
installed, have a look at perldoc \s-1TOC\s0.pod in the distribution archive.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Embperl is a framework for building websites with Perl.
.PP
For the beginner it's any easy to setup and use way of embedding
Perl code in \s-1HTML\s0 pages.
.PP
It delivers several features that ease the task of creating a websites,
including dynamic tables, formfield-processing, escaping/unescaping,
session handling, caching and more.
.PP
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
\&\s-1MVC\s0 application). Of course Embperl doesn't ties you to \s-1HTML,\s0 it allows
components to be from different source formats (e.g. \s-1HTML, WML, XML, POD, ...\s0)
and if necessary transforms it (for example via \s-1XSLT\s0) to other output formats.
This is achieved by diving the output generation in small steps, where each
is processed by a plugable provider.
.PP
Advanced user can create their own syntax definitions (for example tag libraries)
and extent Embperl by writing their own providers and much more
.PP
\&\fB\s-1IMPORTANT:\s0\fR This document describes the syntax and several features of Embperl.
Please read also perldoc Config.pod, which describes how to
configure Embperl and how to access the different Embperl objects and
their data. Also take a look at perldoc Embperl::Object
to learn how to use Embperl page as objects.
.PP
Additionally there are a few introductions documents should consider to read:
Intro.pod, IntroEmbperl2.pod and IntroEmbperlObject.pod.
.SH "SYNTAX"
.IX Header "SYNTAX"
Embperl understands two categories of commands. The first one are
special Embperl commands, and the second category consists of some \s-1HTML\s0 tags
which can trigger special processing. Embperl commands can span
multiple lines and need not start or end at a line boundary.
.PP
Before the special Embperl commands are processed, and for the \s-1VALUE\s0
attribute of the \s-1INPUT\s0 tag (see below), all \s-1HTML\s0 tags are removed and
special \s-1HTML\s0 characters are translated to their \s-1ASCII\s0 values (e.g.,
`<' is translated to `<'). You can avoid this behavior by
preceding the special character or \s-1HTML\s0 tag with a backslash. This is
done in case your favorite (\s-1WYSIWYG\s0) \s-1HTML\s0 editor inserts tags like
line breaks or formatting into your Embperl commands where you don't
want them.
.PP
All Embperl commands start with a `[' and end with a `]'. To get a
real `[' you must enter `[['.
.PP
Embperl does not use \s-1SGML\s0 comments (i.e., or similar things)
because some \s-1HTML\s0 editors can't create them, or it's much more
complicated. Since every \s-1HTML\s0 editor takes (or \fBshould\fR take) `['
and `]' as normal text, there should be no problem.
.SS "[+ Perl code +]"
.IX Subsection "[+ 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\*(R" below
for restrictions.) Examples:
.PP
.Vb 2
\& [+ $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)
.Ve
.PP
\&\f(CW\*(C`NOTE:\*(C'\fR Whitespace is ignored. The output will be automatically
HTML-escaped (e.g., `<' is translated to `<') depending on the
value of the variables \f(CW$escmode\fR. You do not have to worry about
it.
.SS "[\- Perl code \-]"
.IX Subsection "[- Perl code -]"
Executes the Perl code, but deletes the whole command from the \s-1HTML\s0
output.
.PP
Examples:
.PP
.Vb 2
\& [\- $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.
.Ve
.PP
\&\f(CW\*(C`NOTE:\*(C'\fR 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.
.PP
\&\f(CW\*(C`NOTE:\*(C'\fR To define subroutines, use \*(L"[! Perl Code !]\*(R" (see below) instead of
[\- ... \-] to avoid recompilation of the subroutine on every request.
.SS "[! Perl Code !]"
.IX Subsection "[! 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.
.SS "[* Perl code *]"
.IX Subsection "[* Perl code *]"
(only version 1.2b2 or higher) \fB\s-1EXPERIMENTAL\s0!\fR
.PP
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 \*(L"local\*(R" 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.
.PP
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 \fBnot\fR span multiple [\- Perl Code \-]
blocks, but it can span multiple [* Perl Code *].
.PP
.Vb 1
\& Example:
\&
\& [* foreach $i (1..10) { *]
\&
\& [\- $a = $i + 5 \-]
\& loop count + 5 = [+ $a +]
\&
\& [* } *]
\&
\& The following B work:
\&
\& [\- foreach $i (1..10) { \-]
\& some text here
\& [\- } \-]
.Ve
.PP
The same can be done with Embperl meta commands (see below)
.PP
.Vb 1
\& [$ foreach $i (1..10) $]
\&
\& [\- $a = $i + 5 \-]
\& loop count + 5 = [+ $a +]
\&
\& [$ endforeach $]
.Ve
.PP
\&\fB\s-1NOTE 1:\s0\fR [* ... *] blocks _must_ always end with a \fB;\fR,\fB{\fR or \fB}\fR
.PP
\&\fB\s-1NOTE 2:\s0\fR [* ... *] cannot apear inside a html tag that is interpreted by Embperl
(unless you disable the interpretation of such tags like table, input etc.)
.PP
\&\fB\s-1NOTE 3:\s0\fR 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.
.SS "[# Some Text #] (Comments)"
.IX Subsection "[# Some Text #] (Comments)"
(only version 1.2b2 or higher)
.PP
This is a comment block. Everything between the [# and the #] will be removed from
the output.
.PP
\&\fB\s-1NOTE 1:\s0\fR The [* ... *] blocks are interpreted before the comment block, so they are
executed also inside a comment.
.PP
\&\fB\s-1NOTE 2:\s0\fR Everything (except [* ... *]) is really removed from the source, so you
can also use the [# ... #] block to take a part out of your document.
.SS "[= =] (Internationalisation)"
.IX Subsection "[= =] (Internationalisation)"
Defines a string which should be translated into a local language. See
Internationalisation (I18N) for details.
.SS "[$ Cmd Arg $] (Meta-Commands)"
.IX Subsection "[$ Cmd Arg $] (Meta-Commands)"
Execute an Embperl metacommand. \fBCmd\fR can be one of the following.
(\fBArg\fR varies depending on ).
.IP "\fBif\fR, \fBelsif\fR, \fBelse\fR, \fBendif\fR" 4
.IX Item "if, elsif, else, endif"
Everything following the \fBif\fR metacommand until the \fBelse\fR,
\&\fBelsif\fR, or \fBendif\fR is only output if the Perl expression given in
\&\fBArg\fR is true. \fBelse\fR and \fBelsif\fR work similarly.
.Sp
Example:
.Sp
.Vb 5
\& [$ if $ENV{REQUEST_METHOD} eq \*(AqGET\*(Aq $]
\& Method was GET
\& [$ else $]
\& Method other than GET used
\& [$ endif $]
.Ve
.Sp
This will send one of the two sentences to the client, depending on the
request method used to retrieve the document.
.IP "\fBwhile\fR, \fBendwhile\fR" 4
.IX Item "while, endwhile"
Executes a loop until the \fBArg\fR given to \fBwhile\fR is false.
.Sp
Example: (see eg/x/loop.htm)
.Sp
.Vb 5
\& [\- $i = 0; @k = keys %ENV \-]
\& [$ while ($i < $#k) $]
\& [+ $k[$i] +] = [+ $ENV{$k[$i]} +]
\& [\- $i++ \-]
\& [$ endwhile $]
.Ve
.Sp
This will send a list of all environment variables to the client.
.IP "\fBdo\fR, \fBuntil\fR" 4
.IX Item "do, until"
Executes a loop until the \fBArg\fR given to \fBuntil\fR is true.
.Sp
.Vb 1
\& Example:
\&
\& [\- $i = 0 \-]
\& [$ do $]
\& [+ $i++ +]
\& [$ until $i > 10 $]
.Ve
.IP "\fBforeach\fR, \fBendforeach\fR" 4
.IX Item "foreach, endforeach"
Executes a loop for each element of the second \fBArg\fR, setting the
first \fBArg\fR accordingly.
.Sp
.Vb 1
\& Example:
\&
\& [\- @arr = (1, 3, 5) \-]
\& [$ foreach $v (@arr) $]
\& [+ $v +]
\& [$ endforeach $]
.Ve
.IP "\fBnext\fR" 4
.IX Item "next"
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):
.Sp
.Vb 1
\& [* next if ($foo) *]
.Ve
.IP "\fBlast\fR" 4
.IX Item "last"
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):
.Sp
.Vb 1
\& [* last if ($foo) *]
.Ve
.IP "\fBredo\fR" 4
.IX Item "redo"
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):
.Sp
.Vb 1
\& [* redo if ($foo) *]
.Ve
.IP "\fBhidden\fR" 4
.IX Item "hidden"
\&\fBArg\fR consists of zero, one or two names of hashes (with or without
the leading %) and an optional array as third parameter. The
\&\fBhidden\fR 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 \f(CW%fdat\fR, \f(CW%idat\fR is used for the second.
.Sp
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 \*(L"wizard\*(R"). 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.
.Sp
Example:
.Sp
.Vb 4
\&
.Ve
.Sp
If you request this with
.Sp
.Vb 1
\& http://host/doc.htm?field1=A&field2=B&field3=C
.Ve
.Sp
the output will be
.Sp
.Vb 2
\&
.Ve
.Sp
\&\f(CW\*(C`NOTE:\*(C'\fR 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.
.IP "\fBvar\fR" 4
.IX Item "var"
The var command declares one or more variables for use within this
Embperl document and sets the \fBstrict\fR pragma. The variable names
must be supplied as a space-separated list.
.Sp
Example:
.Sp
.Vb 1
\& [$var $a %b @c $]
.Ve
.Sp
This is the same as writing the following in normal Perl code:
.Sp
.Vb 2
\& use strict ;
\& use vars qw($a %b @c) ;
.Ve
.Sp
\&\s-1NOTE 1:\s0 `use strict' within an Embperl document will only apply to the
block in which it occurs.
.IP "\fBsub\fR" 4
.IX Item "sub"
(Only Embperl 1.2b5 and above)
.Sp
Defines a Embperl subroutine. Example:
.Sp
.Vb 3
\& [$ sub foo $]
\&
Here we do something
\& [$ endsub $]
.Ve
.Sp
You can call this subroutine either as a normal Perl subroutine
.Sp
.Vb 1
\& [\- foo \-]
.Ve
.Sp
or via the Embperl::Execute function.
.Sp
.Vb 2
\& [\- Execute (\*(Aq#foo\*(Aq) # short form \-]
\& [\- Execute ({ sub => \*(Aqfoo\*(Aq}) # long form \-]
.Ve
.Sp
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.
.Sp
You may also pass Parameters to the subroutine:
.Sp
.Vb 4
\& [$ sub foo $]
\& [\- $p = shift \-]
\&
Here we show the first parameter [+ $p +]
\& [$ endsub $]
\&
\&
\& [\- foo (\*(Aqvalue\*(Aq) \-]
.Ve
.Sp
In Embperl 2.0.2 and up you can use a shortcut syntax for passing parameters:
.Sp
.Vb 3
\& [$ sub foo ($p) $]
\&
Here we show the first parameter [+ $p +]
\& [$ endsub $]
.Ve
.Sp
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.
.Sp
In addtion you can define some initial Perl code for the subroutine:
.Sp
.Vb 5
\& [$ sub foo ($a, $b)
\& my $c = $a + $b ;
\& $]
\&
The result is [+ $c +]
\& [$ endsub $]
.Ve
.Sp
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:
.Sp
.Vb 1
\& [\- Execute ({ inputfile => \*(Aqmylib.htm\*(Aq, import => 1 }) \-]
.Ve
.Sp
This will import all subroutines from the file \fImylib.htm\fR into the current page
where they could call just as a normal Perl subroutine.
.IP "\fBdump\fR" 4
.IX Item "dump"
Embperl 2.1.1 and above.
.Sp
\&\f(CW\*(C`dump\*(C'\fR can be used to output the values of variables either to the output or
to logfiles. The first parameter specifies the output channel:
.RS 4
.IP "out" 4
.IX Item "out"
Output to the page output
.IP "pre" 4
.IX Item "pre"
Same as \f(CW\*(C`out\*(C'\fR, but surrounded with a
tag. This is the default, if
the output parameter is omitted.
.IP "log" 4
.IX Item "log"
Output to embperl log file
.IP "err" 4
.IX Item "err"
Output to stderr, which normally goes to the httpd error log.
.RE
.RS 4
.Sp
If the output parameter is omitted, \f(CW\*(C`pre\*(C'\fR is assumed.
.Sp
The following parameter can be a literal text (in quotes) or a list
of variables.
.Sp
Example:
.Sp
.Vb 1
\& [$ dump err \*(Aqdump test\*(Aq, %fdat $]
\&
\& [$ dump %fdat, $i, @array $]
.Ve
.RE
.SS "\s-1HTML\s0 Tags"
.IX Subsection "HTML Tags"
Embperl recognizes the following \s-1HTML\s0 tags in a special way. All others are
simply passed through, as long as they are not part of a Embperl
command.
.IP "\fB\s-1TABLE\s0\fR, \fB/TABLE\fR, \fB\s-1TR\s0\fR, \fB/TR\fR" 4
.IX Item "TABLE, /TABLE, TR, /TR"
Embperl can generate dynamic tables (one\- or two-dimensional). You
only need to specify one row or column.
.Sp
Embperl generates as many rows or columns as necessary. This is done
by using the magic variables \f(CW$row\fR, \f(CW$col\fR, and \f(CW$cnt\fR. If you don't use
\&\f(CW$row\fR/$col/$cnt within a table, Embperl does nothing and simply passes
the table through.
.Sp
Embperl checks if any of \f(CW$row\fR, \f(CW$col\fR, or \f(CW$cnt\fR is used. Embperl repeats
all text between
and
, as long as the expressions in
which \f(CW$row\fR or \f(CW$cnt\fR occurs are defined.
.Sp
Embperl repeats all text between
and
, as long as the
expressions in which \f(CW$col\fR or \f(CW$cnt\fR occurs are defined.
.Sp
See also \*(L"$tabmode\*(R" (below) for end-of-table criteria.
.Sp
Examples: (see eg/x/table.htm for more examples)
.Sp
.Vb 8
\& [\- @k = keys %ENV \-]
\&
\&
\&
[+ $i=$row +]
\&
[+ $k[$row] +]
\&
[+ $ENV{$k[$i]} +]
\&
\&
.Ve
.Sp
This will show all entries in array \f(CW@k\fR (which contains the keys from
\&\f(CW%ENV\fR), so the whole environment is displayed (as in the \fBwhile\fR
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.
.Sp
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.
.IP "\fB\s-1DIR\s0\fR, \fB\s-1MENU\s0\fR, \fB\s-1OL\s0\fR, \fB\s-1UL\s0\fR, \fB\s-1DL\s0\fR, \fB\s-1SELECT\s0\fR, \fB/DIR\fR, \fB/MENU\fR, \fB/OL\fR, \fB/UL\fR, \fB/DL\fR, \fB/SELECT\fR" 4
.IX Item "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 \*(L"$row\*(R", \*(L"$maxrow\*(R", \*(L"$col\*(R", \*(L"$maxcol\*(R" and \*(L"$tabmode\*(R"
are honored. \f(CW$col\fR and \f(CW$maxcol\fR are ignored. See eg/x/lists.htm for an
example.
.IP "\fB\s-1OPTION\s0\fR" 4
.IX Item "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.
.Sp
Example:
.Sp
<\s-1FORM\s0 METHOD=\*(L"\s-1POST\*(R"\s0>