Embperl - building dynamic websites with Perl

• mod_perl
• CGI/FastCGI
• Offline
• By calling Embperl::Execute (\%param)
• Debugging

Embperl can operate in one of four modes:

	mod_perl
	The mostly used way is to use Embperl together with mod_perl and Apache. This gives the best performance and the most possibilities.
	CGI/FastCGI
	When you want to run Embperl on a machine that doesn't have mod_perl, you can run Embperl also as normal CGI script. Due to the overhead of CGI, this mode is much slower. To get a better performance you should consider using Embperl together with FastCGI. (http://www.fastcgi.com).
	Offline
	You can use Embperl also on the command line. This is useful for generating static content out of dynamic pages and can sometime be helpful for testing.
	Call it from other Perl programs
	If you have your own application and want to use Embperl's capbilities you can do so by calling Embperl::Execute. This allows you to build your own application logic and use Embperl possibilities for rendering content.

To use Embperl under mod_perl you must have installed Apache and mod_perl on your system. Then you add some directives to your httpd.conf to load Embperl and add Embperl as the PerlHandler. The following directives will cause all file with extetion epl to be handled by Embperl:

    PerlModule Embperl

    AddType text/html .epl

    <Files *.epl>
    SetHandler  perl-script
    PerlHandler Embperl
    Options     ExecCGI
    </files>

Another possibility is to have all files under a special location processed by Embperl:

    PerlModule Embperl

    Alias /embperl /path/to/embperl/eg

    <Location /embperl/x>
    SetHandler  perl-script
    PerlHandler Embperl
    Options     ExecCGI
    </Location>

In this setup you should make sure that non Embperl files like images doesn't served from this directory.

For mod_perl 2.0 you need addtionaly to load the dynamic object library of Embperl. This is necessary so Embperl is loaded early enough to register the configuration directives with Apache. After installing, search underneath your Perl site directory for the library. On Unix it is mostly called Embperl.so on Windows it is called Embperl.dll. Now add the following line to your httpd.conf before any of the Embperl configuration directives, but after mod_perl.so is loaded:

    LoadModule  embperl_module  /path/to/perl/site/lib/Embperl/Embperl.so

To use Embperl::Object you use the Embperl::Object as PerlHandler:

    <Location /foo>
        Embperl_AppName     unique-name
        Embperl_Object_Base base.htm
        Embperl_UriMatch    "\.htm.?|\.epl$"
        SetHandler          perl-script
        PerlHandler         Embperl::Object 
        Options             ExecCGI
    </Location>

Addtionaly you can setup other parameters for Embperl::Object. If you do so inside a container (like <Location, <Directory>, <Files>>) you need to set Embperl_AppName to a unique-name (the actual value doesn't matter). The Embperl_UriMatch makes sure that only files of the requested type are served by Embperl::Object, while all others are served by Apache as usual.

For more information see: perldoc Embperl::Object.

Embperl accepts a lot of configuration directives to customize it's behaviour. See the next section for a description.

NOTE: If mod_perl is statically linked into Apache you can not use ClearModuleList in your httpd.conf

To optimize memory usage you can preload your pages during the initialization. If you do so they will get loaded into the parent process and the memory will be shared by all child processes.

To let Embperl preload your files, you have to supply all the filename into the key preloadfiles of the hash %initparam, before you load Embperl.

Example:

  BEGIN 
    {
    $Embperl::initparam{preloadfiles} = 
        [
        '/path/to/foo.epl',
        '/path/to/bar.epl',
        { inputfile  => "/path/to/other.epl", input_escmode => 7 },
        ] ;
    }

  use Embperl ;

As you see for the third file, it is also possible to give a hashref and supply the same parameter like Execute accpets (see below).

NOTE: Preloading is not supported under Apache 1.3, when mod_perl is loaded as DSO. To use preloading under Apache 1.3 you need to compile mod_perl statically into Apache.

To use this mode you must copy embpcgi.pl 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 embpcgi.pl as a handler for a specific file extension or directory.

Example of Apache httpd.conf:

    <Directory /path/to/your/html/docs>
    Action text/html /cgi-bin/embperl/embpcgi.pl
    </Directory>

NOTE: Via CGI Scripts it maybe possible to bypass some of the Apache setup. To avoid this use Embperl_Allow to restrict access to the files, which should be processed by Embperl.

For Embperl::Object you have to use epocgi.pl instead of embpcgi.pl.

You can also run Embperl with FastCGI, in this case use embpfastcgi.pl as cgi script. You must have FCGI.pm installed.

Run Embperl from the comannd line use embpexec.pl on unix and embpexec.bat on windows:

embpexec.pl [options] htmlfile [query_string]

embpexec.bat [options] htmlfile [query_string]

	htmlfile
	The full pathname of the source file which should be processed by Embperl.
	query_string
	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. <query_string> should be URL-encoded. The default is no query string.

Options:

	-o outputfile
	Optional. Gives the filename to which the output is written. The default is stdout.
	-l logfile
	Optional. Gives the filename of the logfile. The default is /tmp/embperl.log on unix and \embperl.log on windows.
	-d debugflags
	Optional. Specifies the level of debugging (what is written to the log file). The default is nothing. See EMBPERL_DEBUG for exact values.
	-t options
	See EMBPERL_OPTIONS for option values.
	-s syntax
	Defines the syntax of the source. See See EMBPERL_SYNTAX
	-p param
	Gives a value which is passed in the @param array to the executed page. Can be given multiple times.
	-f fdat value
	Gives a name/value pair which is passed in the %fdat hash to the executed page. Can be given multiple times.

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 to nest multiple Embperl pages (for example to store a common header or footer in a different file).

(See eg/x/Excute.pl for more detailed examples)

When you want to use Embperl::Object call Embperl::Object::Execute, when you want Embperl::Mail, call Embperl::Mail::Execute.

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.

  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 @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 are descriped in the configuration section and parameter section.

 # Get source from /path/to/your.html and
 # write output to /path/to/output'

 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 = '<html><head><title>Page [+ $no +]</title></head>' ;

 Embperl::Execute ({ inputfile  => 'some name',
                     input      => \$src,
                     mtime      => 1 }) ;

 # Get source from scalar and write output to another scalar

 my $src = '<html><head><title>Page [+ $no +]</title></head>' ;
 my $out ;

 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') -]
 

Starting with 2.0b2 Embperl files can debugged via the interactive debugger. The debugger shows the Embperl page source along with the correct linenumbers. You can do anything you can do inside a normal Perl program via the debugger, e.g. show variables, modify variables, single step, set breakpoints etc.

You can use the Perl interacive command line debugger via

    perl -d embpexec.pl file.epl  

or if you prefer a graphical debugger, try ddd (https://www.gnu.org/software/ddd/) it's a great tool, also for debugging any other perl script:

    ddd --debugger 'perl -d embpexec.pl file.epl'

NOTE: embpexec.pl could be found in the Embperl source directory

If you want to debug your pages, while running under mod_perl, Apache::DB is the right thing. Apache::DB is available from CPAN.