/ 
Apache-PApp-0.1
/ Apache::PApp

NAME

Apache::PApp - multi-page-state-preserving web applications

SYNOPSIS

#   Apache's httpd.conf file
#   mandatory: activation of Apache::PApp
PerlModule Apache::PApp

# configure the perl module
<Perl>
   search_path Apache::PApp "/root/src/Fluffball/macro";
   search_path Apache::PApp "/root/src/Fluffball";
   configure Apache::PApp (
      cipherkey => "f87a1b96e906bace04c96dbe562af9731957b44e4c282a1658072f0cbe6ba440",
      pappdb    => "DBI:mysql:papp",
      checkdeps => 1,
   );

   # mount an application (here: dbedit.papp)
   mount Apache::PApp (
      location => "/dbedit",
      src => "dbedit.papp"
   );
</Perl>

DESCRIPTION

Apache::PApp is a complete solution for developing multi-page web applications that preserve state across page views. It also tracks user id's, supports a user access system and provides many utility functions (html, sql...). You do not need (and should not use) the CGI module.

Advantages:

  • Speed. Apache::PApp isn't much slower than a hand-coded mod_perl handler, and this is only due to the extra database request to fetch and restore state, which typically you would do anyway. To the contrary: a non-trivial Apache::Registry page is much slower than the equivalent Apache::PApp application.

  • Embedded Perl. You can freely embed perl into your documents. In fact, You can do things like these:

    <h1>Names and amounts</h1>
<:
   my $st = sql_exec "select name, amount from ...",
            [\my($name, $amount];

   while ($st->fetch) {?>
      Name: $name, Amount: $amount<p>
   <:}
:>
<hr>

    That is, mixing html and perl at statement boundaries.

  • State-preserving: The global hash %state is automaticaly preserved during the session. Everything you save there will be available in any subsequent pages that the user accesses.

  • XML. PApp-paplications are written in XML. While this is no advantage in itself, it means that it uses a standardized file format that can easily be extended. Apache::PApp comes with a DTD and a vim syntax file, even ;)

  • Easy internationalization. I18n has never been that easy: just mark you strings with __"string", either in html or in the perl source. The "poedit"-demo-application enables editing of the strings on-line, so translaters need not touch any text files and can work diretcly via the web.

  • Feature-Rich. Apache::PApp comes with a lot of small-but-nice-to-have functionality.

Disadvantages:

  • Unfinished Interface: To admit it, this module is a hack. HMTL::Mason (for example) not only is older and probably larger and more powerful, it has also a more standardized API. Apache::PApp will certainly be changed and improved to accomodate new features (like CGI-only operation).

  • No documentation. Especially tutorials are missing, so you are most probably on your own.

Be advised that, IF YOU WANT TO USE THIS MODULE, PELASE DROP THE AUTHOR (Marc Lehmann <pcg@goof.com>) A MAIL. HE WILL HELP YOU GETTING STARTED.

To get a quick start, read the bench.papp module, the dbedit.papp module, the cluster.papp module and the papp.dtd description of the papp file format.

GLOBAL VARIABLES

Some global variables are free to use and even free to change (yes, we still are about speed, not abstraction).

$request

The Apache request object (Apache), the same as returned by Apache-request>.

%state

A global hash that can be used for almost any purpose, such as saving state values. All keys with prefix papp are reserved for use by this module. everything else is yours.

$userid

The current userid. User-Id's are automatically assigned to every incoming connection, you are encouraged to use them for your own user-databases, but you mustn't trust them.

$pmod (a hash-ref)

The current module (don't ask). The only user-accessible keys are:

lang     a hash-ref enumerating the available langauges, values are
         either language I<Names> or references to another language-id.
config   the argument to the C<config>option given to  C<mount>.
$location

The location value from mount.

$module

The current module within the application.

FUNCTIONS/METHODS

Apache::PApp->search_path(path...);

Add a directory in where to search for included/imported/"module'd" files.

Apache::PApp->configure(name => value...);
pappdb        The (mysql) database to use as papp-database
              (default "DBI:mysql:papp")
cipherkey*    The Twofish-Key to use (16 binary bytes,)
              BIG SECURITY PROBLEM if not set!
cookie_reset  delay in seconds after which papp tries to
              re-set the cookie (default: one day)
cookie_expires time in seconds after which a cookie shall expire
              (default: one year)
checkdeps     when set, papp will check the .papp file dates for
              every request (slow!!) and will reload the app when necessary.

[*] required attributes
Apache::PApp->mount(location => 'uri', src => 'file.app', ... );
location[*]   The URI the application is moutned under, must start with "/"
src[*]        The .papp-file to mount there
config        Will be available to the module as $pmod->{config]

[*] required attributes
dprintf "format", value... dprint value...

Work just like print/printf, except that the output is queued for later use by the debugbox function.

echo value[, value...]

Works just like the print function, except that it is faster for generating output.

capture { code/macros/html }

Captures the output of "code/macros/perl" and returns it, instead of sending it to the browser. This is more powerful that it sounds, for example, this works:

<:
   my $output = capture {

      print "of course, this is easy\n";
      echo "this as well";
      :>
         
      Yes, this is captured as well!
      <:&this_works:>
      <?$captureme:>

      <:

   }; # close the capture
:>
reference_url $fullurl

Return a url suitable for external referencing of the current page. If $fullurl is given, a full url (including a protocol specifier) is generated. Otherwise a partial uri is returned (without http://host:port/).

This is only a bona-fide attempt: The current module must support starting a new session and only "import"-variables and input parameters are preserved.

Create "a link" (a href) with the given contents, pointing at the given url.

$url = surl ["module"], arg => value, ...

surl is one of the most often used functions to create urls. The first argument is the name of a module that the url should refer to. If it is missing the url will refer to the current module.

The remaining arguments are parameters that are passed to the new module. Unlike GET or POST-requests, these parameters are directly passed into the %state-hash, i.e. you can use this to alter state values when the url is activated. This data is transfered in a secure way and can be quite large (it will not go over the wire).

This is just "alink shift, &url", that is, it returns a link with the given contants, and a url created by surl (see above). For example, to create a link to the view_game module for a given game, do this:

<? slink "Click me to view game #$gamenr", "view_game", gamenr => $gamenr :>

The view_game module can access the game number as $state{gamenr}.

returl

*FIXME*

%locals = current_locals

Return the current locals (defined as "local" in a state element) as key => value pairs. Useful for sublinks:

<? sublink [current_locals], "Log me in!", "login" :>

This will create a link to the login-module. In that module, you should provide a link back to the current page with:

<? retlink "Return to the caller" :>
sform [module, ]arg => value, ...
cform [module, ]arg => value, ...
endform

Return a <form> or </form>-Tag. sform ("simple form") takes the same arguments as surl and return a <form>-Tag with a GET-Method. cform ("complex form") does the same, but sets method to POST.

Endform simply returns a closing </form>-Tag, and should be sued to close forms created via sform/cform.

errbox
submit

*FIXME*

textfield
textarea
password_field
hidden key => value
checkbox
radio

*FIXME*

mailto_url $mailaddr, key => value, ...

Create a mailto url with the specified headers (see RFC 2368). All values will be scaped for you. Example:

mailto_url "pcg@goof.com",
           Subject => "Mail from me",
           body => "(generated from ".referebce_url(1).")";
redirect url
internal_redirect url

Immediately redirect to the given url. These functions do not return!. redirect_url creates a http-302 (Page Moved) response, changign the url the browser sees (and displays). internal_redirect redirects the request internally (in the web-server), which is faster, but the browser will not see the url change.

debugbox

Create a small table with a single link "[switch debug mode ON]". Following that link will enable debugigng mode, reload the current page and display much more information (%state, %param, %$pmod and the request parameters). Useful for development. Combined with the admin package ("admin" in macro), you can do nice things like in your page:

#if admin_p
  <: debugbox :>
#endif
sql_exec "sql-command"[, bind-vals], sql-arg, sql-arg...

Runs the given sql command with the given parameters and returns the statement handle. The command and the statement handle will be cached, so prepare will be called only once. If the second argument is an array-ref, it's contents should be references to variables that get bound via bind_cols. See the Advantages-section in the DESCRIPTION chapter for an example.

sql_fetch "sql-command", args..

Execute a sql-statement and fetch the first row of results. Depending on the caller context the row will be returned as a list (array context), or just the first columns.

sql_fetchall "slq-command", args...

Similarly to sql_fetch, but all result rows will be fetached (this is inefficient for large results!).

sql_exists "table where ...", args...

Check wether the result of the sql-statement "select xxx from $first_argument" would be empty or not. Works everywhere but can be quite slow, except on mysql, where this should be quite fast.

fancydie $error, $additional_info

Aborts the current page and displays a fancy error box, complete with backtrace. $error should be a short error message, while $additional_info can be a multi-line description of the problem.

phtml2perl "pthml-code"

Convert <phtml> code to normal perl. The following four mode-switches are allowed, the initial mode is ":>" (i.e. plain html).

<:	start verbatim perl section ("perl-mode")
:>	start plain html section (non-interpolated html)
<?	start perl expression (single expr, result will echo'd) (eval this!)
?>	start interpolated html section (similar to qq[...]>)

Within plain and interpolated html sections you can also use the __"string" construct to mark (and map) internationalized text. The construct must be used verbatim: two underlines, one double-quote, text, and a trailing double-quote. For more complex uses, just escape to perl (e.g. <?__"xxx"?>).

insert_module "module"

Switch permanently module "module". It's output is inserted at the point of the call to switch_module.

expand_lang langid, langid...

Tried to identify the closest available language. #fixme#

reload_p

Return the count of reloads, i.e. the number of times this page was reloaded (which means the session was forked).

This is a relatively costly operation (a database access), so do not do it by default, but only when you need it.

switch_userid $newuserid

Switch the current session to a new userid. This is useful, for example, when you do your own user accounting and want a user to log-in. The new userid must exist, or bad things will happen.

SEE ALSO

The macro/admin-package on the distribution, the demo-applications (.papp-files).

AUTHOR

Marc Lehmann <pcg@goof.com>
http://www.goof.com/pcg/marc/

1 POD Error

The following errors were encountered while parsing the POD:

Around line 79:

Expected '=item *'