=head1 NAME HTML::Embperl - Building dynamic Websites with Perl =head1 SYNOPSIS =head1 DESCRIPTION Embperl is a Perl extension module which gives you the power to embed Perl code directly in your HTML documents (like server-side includes for shell commands). If building more than a single page, you may also want to take a look at L<"perldoc EmbperlObject"|"EmbperlObject.pod"> which lets you build your website out of small reusable objects. Additionally, L<"perldoc HTML::Embperl::Mail"|"Mail.pod"> allows you to send the resulting page via email. =head1 Operating-Modes Embperl can operate in one of four modes: =head2 Offline Converts an HTML file with embedded Perl statements into a standard HTML file. B B Use embpexec.pl on Unix systems and embpexec.bat on Win32 systems. =over 4 =item B The full pathname of the HTML file which should be processed by Embperl. =item B Optional. Has the same meaning as the environment variable QUERY_STRING when invoked as a CGI script. That is, QUERY_STRING contains everything following the first "?" in a URL. should be URL-encoded. The default is no query string. =item B<-o outputfile> Optional. Gives the filename to which the output is written. The default is stdout. =item B<-l logfile> Optional. Gives the filename of the logfile. The default is /tmp/embperl.log. =item B<-d debugflags> Optional. Specifies the level of debugging (what is written to the log file). The default is nothing. See L<"EMBPERL_DEBUG"> for exact values. =back =head2 As a CGI script Instead of a file being sent directly by the web server, the document is processed by the CGI script and the result is sent to the client. B B Use embpcgi.pl on Unix systems and embpcgi.bat on Win32 systems. You can also run Embperl with B, in this case use embpfastcgi.pl as cgi script. You must have FCGI.pm installed. If C is invoked without any parameters and the environment variable B is set, it runs itself as a CGI script. This means that form data is taken either from the environment variable B or from stdin, depending on whether or not B is set. (This will be set by the web server depending on whether the request method is GET or POST). Input is taken from the file pointed to by B and the output is send to stdout. The logfile is generated at its default location, which is configurable via the environment variable B. To use this mode you must copy B to your cgi-bin directory. You can invoke it with the URL http://www.domain.xyz/cgi-bin/embpcgi.pl/url/of/your/document. The /url/of/your/document will be passed to Embperl by the web server. Normal processing (aliasing, etc.) takes place before the URI makes it to PATH_TRANSLATED. If you are running the Apache httpd, you can also define B as a handler for a specific file extension or directory. Example of Apache C: Action text/html /cgi-bin/embperl/embpcgi.pl B: For security reasons, embpexec.pl must not be used as a CGI script anymore! B: CGI Scripts are not so secure. You should consider using L to restrict access. =head2 From mod_perl (Apache httpd) This works like the CGI-Script, but with the advantage that the script is compiled only once at server startup, where other one-time actions (such as opening files and databases) can take place. This will drastically reduce response times for the request. To use this you must compile C with C and add C as the C. Example of Apache C or C: SetEnv EMBPERL_DEBUG 2285 Alias /embperl /path/to/embperl/eg SetHandler perl-script PerlHandler HTML::Embperl Options ExecCGI Another possible setup is SetEnv EMBPERL_DEBUG 2285 SetHandler perl-script PerlHandler HTML::Embperl Options ExecCGI AddType text/html .epl Don't forget the B. In this setup, all files ending with .epl are processed by Embperl. See the section L<"EMBPERL_DEBUG"> (dbgLogLink and EMBPERL_VIRTLOG) to find out how you can configure Embperl so you can view the log file with your browser! B: When mod_perl is compiled as loadable module (i.e. with USE_DSO) you B load Embperl at server startup time! B: L<"perldoc EmbperlObject"|"EmbperlObject.pod"> to see how to setup I so as to create your site out of small overwriteable objects. =head2 By calling HTML::Embperl::Execute (\%param) Execute can be used to call Embperl from your own modules/scripts (for example from a Apache::Registry or CGI script) or from within another Embperl page (only 1.2b1 or higher) to nest multiple Embperl pages (for example to store a common header or footer in a different file). There are two forms you can use for calling Execute. A short form which only takes a filename and optional additional parameters or a long form which takes a hash reference as its argument. This gives it the chance to vary the parameters according to the job that should be done. (See B for more detailed examples) B: L<"perldoc EmbperlObject"|"EmbperlObject.pod"> to see how to setup I so as to create your site out of small overwriteable objects and L<"perldoc HTML::Embperl::Mail"|"Mail.pod"> on how to use I to send email. Execute($filename, $p1, $p2, $pn) ; This will cause Embperl to interpret the file with the name $filename and, if specified, pass any additional parameters in the array @Z<>param (just like @_ in a perl subroutine). The above example could also be written in the long form: Execute ({inputfile => $filename, param => [$p1, $p2, $pn]}) ; The possible items for hash of the long form are: =over 4 =item B The file which should be used as source. If B is also specified, this parameter should be given a unique name to identify the source. Every time Embperl sees the same text in B, it assumes that you compiled the same source - that means that Embperl uses the same package name as in your last call, and only recompiles the code if B has changed or is undefined. =item B Call the Embperl subroutine named by this parameter(see also B<"[$ sub $]">). Currently the subroutine must be in the same file or if it's in another file, the other file has to be imported first. =item B Reference to a string which contains the source. B must also be specified to give a name for the source. The name can be any text. =item B Last modification time of member B. If undef the code passed by input is always recompiled, else the code is only recompiled if mtime changes. =item B File to which the output should be written. If neither outputfile nor output is specified, ouput is written to stdout. =item B Reference to a scalar where the output should be written to. =item B A value of zero tells Embperl not to execute the page, but define all subrountines found inside. This is neccessary before calling them with Execute by the B parameter or for a later import. A value of one tells Embperl to define the subrountines inside the file (if not already done) and to import them as perl subroutines into the current namespace. See B<[$ sub $]> metacommand and section about subroutines for more info. =item B NOTE: The req_rec parameter isn't necessary anymore in versions >= 1.2b2 If used under mod_perl, you should set the req_rec parameter to the Apache request record object provided by mod_perl. =item B This value specifies if and when the cleanup of the package should be executed. (See L<"Variable scope and cleanup"> below for more information on cleanup) =over 4 =item B Never cleanup the variables =item B or not specified If running under mod_perl, cleanup is delayed until the connection to the client is closed, so it does not lengthen the response time to the client. If the Execute function is called more the once before the end of the request, all cleanups take place after the end of the request and not between calls to Execute. If running as a CGI or offline, cleanup takes place immediately. =item B Immediate cleanup =back =item B Can be used to pass parameters to the Embperl document and back. Must contain a reference to an array. Example: HTML::Embperl::Execute(..., param => [1, 2, 3]) ; HTML::Embperl::Execute(..., param => \@parameters) ; The array @Z<>param in the Embperl document is setup as an alias to the array. See eg/x/Excute.pl for a more detailed example. =item B Could be used to setup the two Embperl predefined variables. =item B Specifies the first linenumber of the sourcefile (Default: 1) =item B Same as L<"EMBPERL_OPTIONS"> (see below), except for cleanup. B You should set the B if you have already read the form data from stdin while in a POST request. Otherwise Execute will hang and try to read the data a second time. =item B Same as L<"EMBPERL_DEBUG"> (see below). =item B Same as L<"EMBPERL_ESCMODE"> (see below). =item B Same as L<"EMBPERL_PACKAGE"> (see below). =item B Same as L<"EMBPERL_VIRTLOG"> (see below). If B is equal to B the logfile is sent. =item B Same as L<"EMBPERL_ALLOW"|"EMBPERL_ALLOW (only 1.2b10 and above)"> (see below) =item B Same as L<"EMBPERL_PATH"|"EMBPERL_PATH (1.3b6 and above)"> (see below) =item B The URI of the request. Only needed for the virtlog feature. =item B Same as L<"EMBPERL_COMPARTMENT"> (see below). =item B Same as L<"EMBPERL_INPUT_FUNC"> (see below). Additionaly you can specify a code reference to a perl subroutine, which is used as input function; or an array reference, where the first element contains the code reference and further elements contain additional arguments passed to the function. =item B Same as L<"EMBPERL_OUTPUT_FUNC"> (see below). Additionaly you can specify a code reference to a perl subroutine, which is used as output function; or an array reference, where the first element contains the code reference and further elements contain additional arguments passed to the function. =item B Same as L<"EMBPERL_COOKIE_NAME"> (see below). =item B Same as L<"EMBPERL_COOKIE_PATH"> (see below). =item B Same as L<"EMBPERL_COOKIE_DOMAIN"> (see below). =item B Same as L<"EMBPERL_COOKIE_EXPIRES"> (see below). =item B Takes a reference to an array. Upon return, the array will contain a copy of all errormessages, if any. =item B (1.3.1b1 and above) Takes a filename and returns an hashref that is blessed into the package of the given file. That's usefull, if you want to call the subs inside the given file, as methods. By using the C parameter (see below) you are able to provide an inherence tree. Additionaly you can use the returned hashref to store data for that obeject. Example: [# the file eposubs.htm defines two subs: txt1 and txt2 #] [# first we create a new object #] [- $subs = Execute ({'object' => 'eposubs.htm'}) -] [# then we call methods inside the object #] txt1: [+ $subs -> txt1 +]
txt2: [+ $subs -> txt2 +]
=item B (1.3.1b1 and above) Takes a name of a file and pushes the package of that file into the @ISA array of the current file. By using this you can setup an inherence tree between Embperl documents. Is is also usefull within I. Example: [! Execute ({'isa' => '../eposubs.htm'}) !] =item B (1.3.2 and above) In 1.3.x the only value that is accepted is 'Text', this emulates the Embperl 2.0 behaviour of simply passing the whole text thru, without doing any processing. =back =head2 Helper functions for Execute =over 4 =item B This function can be used to setup the logfile path and (optionally) a default value for the debugflags, which will be used in further calls to Execute. There will always be only one logfile, but you can use B to change it at any time. B You do not need to call Init in version >= 0.27. The initialization of Embperl takes place automatically when it is loaded. =item B Scans B<%ENV>, setting up B<%params> for use by B. All Embperl runtime configuration options are recognized, except EMBPERL_LOG. =back =head2 EXAMPLES for Execute: # Get source from /path/to/your.html and # write output to /path/to/output' HTML::Embperl::Execute ({ inputfile => '/path/to/your.html', outputfile => '/path/to/output'}) ; # Get source from scalar and write output to stdout # Don't forget to modify mtime if $src changes $src = 'Page [+ $no +]' ; HTML::Embperl::Execute ({ inputfile => 'some name', input => \$src, mtime => 1 }) ; # Get source from scalar and write output to another scalar my $src = 'Page [+ $no +]' ; my $out ; HTML::Embperl::Execute ({ inputfile => 'another name', input => \$src, mtime => 1, output => \$out }) ; print $out ; # Include a common header in an Embperl page, # which is stored in /path/to/head.html [- Execute ('/path/to/head.html') -] =head1 Runtime configuration The runtime configuration is done by setting environment variables, either on the command line (when working offline) or in your web server's configuration file. Most HTTP servers understand: SetEnv If you are using Apache and mod_perl you can use PerlSetEnv The advantage of PerlSetEnv over SetEnv is that it can be used on a per directory/virtual host basis. =head2 EMBPERL_FILESMATCH If specified, only files which match the given B will be processed by Embperl, all other files will be handled by the standard Apache handler. This can be useful if you have Embperl documents and non Embperl documents (e.g. gifs) residing in the same directory. EMBPERL_FILESMATCH works only under mod_perl. Example: # Only files which end with .htm will processed by Embperl PerlSetEnv EMBPERL_FILESMATCH \.htm$ =head2 EMBPERL_ALLOW (only 1.2b10 and above) If specified, only files which match the given B will be processed by Embperl. All other files will return FORBIDDEN. This is especially useful in a CGI environment by making the server more secure. =head2 EMBPERL_PATH (1.3b6 and above) Can contain a semicolon (also colon under Unix) separated file search path. When a file is processed and the filename isn't an absolute path or does not start with ./ (or .\ under windows), I searches all the specified directories for that file. Directories must end with a slash (C), otherwise the entry is treated as a fileprefix. A special handling is done if the filename starts with any number of C<../> i.e. refers to an upper directory. Then I strips the same number of entries at the start of the searchpath as the filename contains C<../>. =head2 EMBPERL_COMPARTMENT Gives the name of the compartment from which to take the opcode mask. (See the chapter about L<"(Safe-)Namespaces and opcode restrictions"> for more details.) =head2 EMBPERL_ESCMODE Specifies the initial value for L<"$escmode"> (see below). =head2 EMBPERL_LOG Gives the location of the log file. This will contain information about what Embperl is doing. The amount of information depends on the debug settings (see L<"EMBPERL_DEBUG"> below). The log output is intended to show what your embedded Perl code is doing and to help debug it. The default is B. B When running under mod_perl you need to use B for setting the logfile path, and mod_perl >= 1.07_03 if you load Embperl at server startup (with PerlScript or PerlModule). =head2 EMBPERL_PACKAGE The name of the package where your code will be executed. By default, Embperl generates a unique package name for every file. This ensures that variables and functions from one file do not conflict with those of another file. (Any package's variables will still be accessible with explicit package names.) =head2 EMBPERL_VIRTLOG Gives a virtual location where you can access the Embperl logfile with a browser. This feature is disabled (default) if EMBPERL_VIRTLOG is not specified. See also L<"EMBPERL_DEBUG"> and dbgLogLink for an Example on how to set it up in your srm.conf. =head2 EMBPERL_OPTIONS This bitmask specifies some options for the execution of Embperl. To specify multiple options, simply add the values together. =over 4 =item optDisableVarCleanup = 1 Disables the automatic cleanup of variables at the end of each request. =item optDisableEmbperlErrorPage = 2 Tells Embperl not to send its own errorpage in case of failure, but instead show as much of the page as possible. Errors are only logged to the log file. Without this option, Embperl sends its own error page, showing all the errors which have occurred. If you have dbgLogLink enabled, every error will be a link to the corresponding location in the log file. This option has no effect if optReturnError is set. =item optReturnError = 262144 With this option set, Embperl sends no output in case of an error. It returns the error back to Apache or the calling program. When running under mod_perl this gives you the chance to use the Apache I directive to show a custom error-document. Inside the ErrorDocument you can retrieve the error messages with $errors = $req_rec -> prev -> pnotes('EMBPERL_ERRORS') ; where C<$errors> is a array reference. (1.3b5+) =item optShowBacktrace = 0x8000000 When set every error message not only show the sourcefiles, but all files from which this file was called by Execute. =item optSafeNamespace = 4 Tells Embperl to execute the embedded code in a safe namespace so the code cannot access data or code in any other package. (See the chapter about L<"(Safe-)Namespaces and opcode restrictions"> below for more details.) =item optOpcodeMask = 8 Tells Embperl to apply an operator mask. This gives you the chance to disallow special (unsafe) opcodes. (See the Chapter about L<"(Safe-)Namespaces and opcode restrictions"> below for more details.) =item optRawInput = 16 Causes Embperl not to pre-process the source for a Perl expression. (The only exception is that carriage returns will be removed, as Perl does not like them.) This option should be set when you are writing your code with an ASCII editor. If you are using a WYSIWYG editor which inserts unwanted HTML tags in your Perl expressions and escapes special characters automatically (e.g., `<' appears as `<' in the source), you should not set this option. Embperl will automatically convert the HTML input back to the Perl expressions as you wrote them. =item optEarlyHttpHeader = 64 Normally, HTTP headers are sent after a request is finished without error. This gives you the chance to set arbitrary HTTP headers within the page, and gives Embperl the chance to calculate the content length. Also Embperl watches out for errors and sends an errorpage instead of the document if something goes wrong. To do this, all the output is kept in memory until the whole request is processed, then the HTTP headers are sent, and then the document. This flag will cause the HTTP headers to be sent before the script is processed, and the script's output will be sent directly. =item optDisableChdir = 128 By default, Embperl changes the current directory to the one where the script resides, thus giving you the chance to use relative pathnames. Since directory-changing takes up some millisecs, you can disable it with this option if you don't need it. =item optDisableFormData = 256 This option disables the setup of %fdat and @Z<>ffld. Embperl will not do anything with the posted form data. Set this when using Execute from your perl script and you have already read the Form Data (via eg. CGI.pm). =item optDisableHtmlScan = 512 When set, this option disables the scanning of B html-tags. Embperl will only look for [+/-/!/$ ... $/!/-/+]. This will disable dynamic tables, processing of the input data and so on. =item optDisableInputScan = 1024 Disables processing of all input-related tags. ( The C