Embperl - building dynamic websites with Perl


Embperl - Building dynamic Websites with Perl

Copyright (c) 1997-2008 Gerald Richter / ecos gmbh  www.ecos.de
Copyright (c) 2008-2015 Gerald Richter
Copyright (c) 2015-2023 actevy.io

You may distribute under the terms of either the GNU General Public 
License or the Artistic License, as specified in the Perl README file.

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED 
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF 
MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.




OVERVIEW
========

Embperl gives you the power to embed Perl code in your HTML documents
and the ability to build your Web site out of small reusable objects in
an object-oriented style. You can also take advantage of all the
usual Perl modules, (including DBI for database access) use their
functionality and easily include their output in your web pages.
Additionally Embperl support including XML, XSLT tranformations and
a lot of other sources formats.

Embperl has several features which are especially useful for creating
HTML, including dynamic tables, form field processing and validation, URL
escaping/unescaping, session handling, and more.

Embperl is a server-side tool, which means that it's browser-independent. 
It can run in various ways: under mod_perl, as a CGI script, or offline.

For database access, there is a module called DBIx::Recordset, which 
works well together with Embperl and simplifies creating web pages
with database content.


DOCUMENTATION
=============

The following documentation is available within the distribution

Detailed list of documenation:  perldoc TOC.pod
Features of Embperl:            perldoc Features.pod
Introduction to basic Embperl:  perldoc Intro.pod
Introduction to Embperl 2 
advanced features:              perldoc IntroEmbperl2.pod
Introduction to EmbperlObject:  perldoc IntroEmbperlObject.pod
Installation of Embperl:        perldoc INSTALL.pod
Full documentation:             perldoc Config.pod
                                perldoc Embperl.pod
                                perldoc Embperl/Object.pm
                                perldoc Embperl/Mail.pm
                                perldoc Embperl/Inline.pm
Tips and Tricks:                perldoc TipsAndTricks.pod
Changes:                        perldoc Changes.pod
Examples:                       eg/README
Sourcecode encryption:          crypto/README
Documentation and example for
Embperl::Form can be found at:  eg/forms


All the above and further information can be found at the Embperl website 

    https://perl.apache.org/embperl/

All the above and further information can be found at the german Embperl website 

    https://www.actevy.io/embperl/


FEATURES
========

* Embperl facilitates embedding Perl code into HTML/XML or other text documents. 
Perl code is evaluated at the server side and the result is sent to the browser.
All available Perl modules can be used without any restriction.

* Allows one to build Web sites out of small reusable components in an object-oriented way.
Components can call and/or embed each other and inherit from other objects.

* Standard layout of a web-site site can be defined once and the content can be 
dynamically generated by these components based on the uri. The documents need only 
contain the variable portions but not the common items which define the 
layout like headers/footers or navigation bars which normally form the template. 
Also these common elements can be overwritten in each sub-directory.

* Embperl 2.0 thus facilitates separating code, layout and creating MVC (Model-View-Controller)
applications. Control logic can be moved into an application object, 
which controls further execution of the request, while the actual pages are
containing the display code. Simple applications can still embed all the code in the pages.

* Source-code for each component can come from a different source, eg.
from file, memory or sub-request which allows one to act on the output from another Apache
application like PHP, JSP, CGI Script etc.

* Each component can be in a different source format (e.g. HTML, WML, XML, POD, ...)
and can be transformed to other output formats, say by using via XSLT. 

* Supports one or more scripting syntax using Embperl, ASP, Text, Perl and others.

* Output generation is divided into small steps where each is processed by a plugable provider. 
The interaction of the providers can be individually configured for each component via recipes.

* Supports caching of intermediate results and output.

* Embperl encompasses several features that ease the task of dynamic web-site content generation, 
including dynamic-tables, form-field-processing, escaping/unescaping, etc.

* Contains a module for easy form input validation, which is able to validate user input
at the server side and on the client side by one definition of rules.

* Handles per-user and per-module persistent session requiring only storage and retrieval of 
the session data from a special hash.

* UTF-8 Support (honours Perl's internal UTF-8 flag during in- and output)

* Offers flexible configuration options to suite individual tastes and needs.

* Fully integrated into Apache and mod_perl to acheive the best performance. 
Can also run as a free standing CGI-script, off-line or can be called from another Perl program.

* The Perl module DBIx::Recordset offers high level, easy to use database access for Embperl.

* Embperl::Mail enables redirecting the result output to a mail-recipient.

* Embperl::Inline allows one to embedd Embperl code in normal Perl code

* Embperl::Form is a sophisticated library for building HTML forms



COMPATIBILITY
=============

I have tested Embperl successfully on different linux distributions.
Embperl does work on Windows, but is not fully tested there.

See perldoc INSTALL.pod for installation instructions.

Hints for using Embperl 2.x and higher
--------------------------------------

Embperl 2 is totaly rewritten. Most of the Perl code is moved 
into C to speed up processing. The core is totaly redesigned to
give a lot of new possibilities.


The Embperl core now works in a totaly different way. The processing
of the source towards the output is done by providers. Every provider
takes a small step. Which providers are used is defined by a recipe.
The standard Embperl recipe contains the following providers:

    1 reading the source
    2 parsing 
    3 compiling 
    4 executing
    5 outputing

The providers work in a similar way as Unix shell programs which are
processing a single source in a pipeline towards the output. In
Embperl is is not only a smimple pipeline, but a tree structure,
so multiple sources can be incorpoarted in one result.
Recipes descripes how providers are executed.
Rearrangeing the provideres or writing and useing new ones gives
flexibility and power. Addtional to the standard Embperl providers
Embperl ships with XML parser and XSLT processor providers.

The new execution scheme is also faster, because html tags and metacommands
are parsed only once (Perl code was also (and is still) cached in 1.x)
My first benchmarks show 50%-100% faster execution under mod_perl 
compared to Embperl 1.x.

Another new feature is that the syntax of the Embperl parser is defined
within the module Embperl::Syntax and can be modified as nessecary.
Embperl comes with a set of syntax definitons which can be modified by
the user. So far there are syntax definitions for SSI, Text only, Perl only,
ASP, POD, RTF and a Mail taglib. You can tell Embperl which syntax to use either in
the configuration via EMBPERL_SYNTAX, or with the syntax parameter of
Execute, or you can change the syntax dynamically inside the page via the
[$syntax $] command. You also could specify more then one syntax at the same
time, e.g. [$syntax Embperl SSI $] to mix Embperl tags and SSI tags in the same
page.

If you'd like to create your own syntax read:

   perldoc Embperl::Syntax

and look at the files under Embperl/Syntax/ for examples on how to do it.

Also new is the ability to cache (parts of) the output. See
the new configuration directives below.

Starting with 2.0b6 Embperl provides a set of new object, which allows
to access Embperl internals and manipulate the processing. Basicly there
are three major objects:

    - Application
    - Request
    - Component

The application object is responsible for a set of pages that forms an
application. It is used to configure things like session handling and
logging which should be unique across these pages. More important
it can be overriden and the overriden object can contain the application
logic, to create a proper separation of logic and presentation.

The request object holds everything which spans a whole (HTTP-)request.

The component object is responsible for a single component, inside the
desired output. It holds things like sourcefile etc.

All three objects have a subobject which holds the configuration and a
subobject for it's current parameters.


Debugging
---------

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.


The following differences to Embperl 1.x apply:
------------------------------------------------------

- When running under mod_perl you _must_ load Embperl
  at server startup time. Either with a

  PerlModule Embperl

  in your httpd.conf or a

  use Embperl ;

  inside of a startup script.
  You can use the Embperl configuration directives now
  directly, (without PerlSetEnv/SetEnv). If you still
  want to use environment varibales to configure Embperl, write

  Embperl_UseEnv on

- Embperl now supports Apache 2 / mod_perl 2, but you need a additional
  configuration line in your httpd.conf:

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


- For every container in your httpd.conf (e.g. VirtualHost,Directory,Location)
  where you want to define any application level configuration directives
  (see below under tAppConfig for a list), you need to set a unique
  value for EMBPERL_APPNAME. This is for example necessary for all
  Embperl::Object parameters. Example:

  
  EMBPERL_APPNAME my_embperl_app
  EMBPERL_OBJECT_BASE base.epl
  
    
- The following options can currently only be set from httpd.conf:
     optKeepSpaces

- The option optRawInput is replaced by EMBPERL_INPUT_ESCMODE,
  which is off by default (same as when optRawInput was set 
  in 1.x)

- The following options are currently not supported:
     optRedirectStdout
     optDisableHtmlScan, optDisableTableScan,
     optDisableInputScan, optDisableMetaScan

  optDisableHtmlScan can be replaced by switching the syntax, e.g.

  [$syntax EmbperlBlocks $]  # same as [- $optDisableHtmlScan = 1 -]

    (here goes your code - Embperl will not interpret any html tags here)

  [$syntax Embperl $]        # same as [- $optDisableHtmlScan = 0 -]


- Nesting must be done properly. I.e. you cannot put a  tag (for a
  dynamic table) inside an 'if' and the 
inside another 'if'. (That still works for static tables) - optUndefToEmptyValue is always set and cannot be disabled. - [$ foreach $x (@x) $] now requires the brackets around the array (like Perl) - [+ +] blocks must now contain a valid Perl expression. Embperl 1.x allows you to put multiple statements into such a block. For performance reasons this is not possible anymore. Also the expression must _not_ be terminated with a semicolon. To let old code work, just wrap it into a 'do' e.g. [+ do { my $a = $b + 5 ; $a } +] - EMBPERL_INPUT_FUNC and EMBPERL_OUTPUT_FUNC are not supported anymore You can the same result and much more by writing custom provider. - Embperl doesn't change the current working directory anymore to the directory of the source file. This is done for performance reasons and because it won't reliable work with threads under mod_perl 2.0. You can use $req -> component -> cwd to get the directory of the sourcefile (where $req is Embperl request object, which is the first parameter passed to the page i.e. $_[0]) - safe namespaces are not supported anymore, since are are not really safe anyway - errors can be mailed to an administrator - Parameters of SetupSession, CleanupSession and SetSessionCookie have changed. Embperl 1.x compatibility flag ------------------------------ The compatibility flag isn't available anymore in 2.0b6. Since now Embperl 2.0 lives in his own namespace, you can install Embperl 1.x and 2.x on the same machine without conflicts. exit ---- B 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. B 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. If you want to exit the whole request, call exit with an argument e.g. exit (200) B If you write a module which should work with Embperl under mod_perl, you must use Embperl::exit instead of the normal Perl exit. (In 1.3.x it was Apache::Exit) 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. 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 https://mail-archives.apache.org/mod_mbox/perl-embperl For mod_perl related questions you may search the mod_perl mailing list archive at https://mail-archives.apache.org/mod_mbox/perl-modperl AUTHOR ====== G. Richter (richter at embperl dot org)


© 1997-2023 Gerald Richter / actevy