webperl/tools/mdfiles/overview.md

Overview                                                             {#overview}
========

The modules and classes discussed here are the result of an uneasy balance between
ease of use and features - the modules (with a couple of exceptions) are not unique,
and may provide fewer features than some alternatives. However, they all present
simple, concise interfaces that make them easy to use, in stark contrast to their
more featureful brethren.

At least I think they do. I might be biased, however.

Moreover, the intent behind this framework is to provide a simple base from which
to rapidly develop web applications, with as few rigid rules as possible - if you
need a more featureful module for something, you will probably be able to use it.

Basics
------

Much of what follows assumes that you are using the Application class as the
base of your webapp. It is important to note that this is not the only way in
which the classes and modules in the framework may be used, and it is likely
that you will find different ways of doing things, as is only Right and Proper.

The core feature underlying the operation of the webperl framework is the dynamic
loading of "blocks": your webapp should consist of one or more subclasses of the
Block class, usually stored in the cunningly named `blocks` directory (see the
[Structuring](@ref appstructure) document for more about the directory hierarchy).
Each subclass of Block should implement a piece of your webapp's functionality -
how much or how little is left entirely up to you. The subclasses are loaded by
the Modules class 'on demand', so the system does not attempt to load lots of
redundant functionality when started. You could implement your entire webapp in
a single block if you wanted, but unless it is very simple a lot of unused code
will be loaded each time a page is generated. Splitting your application up allows
for more logical compartmentalisation of features, and reduces interpreter
overhead.

If you are using the Application class as the base of your webapp, it will
perform all the framework setup process for you, and then load one of your
Block subclasses to generate the actual page content. Application looks at the
'block' parameter in the query string or POSTed data to determine which block
to load, and if the value in the `block` parameter is invalid or missing, a
default 'initial block' specified in the configuration is loaded instead. For
more about blocks, see the [Blocks](@ref blocks) documentation.

Once a block has been loaded, Application calls the block's page_display()
method and prints the returned string to stdout, typically sending it back to the
client web browser. What the block does in page_display is up to you: it could
put together a HTML/XHTML page and return it, sending the page back to the user,
or it could generate some other form of content and exit, bypassing the normal
behaviour of Application (you might want to do this if sending anything other
than HTML back to the user - xml, file data, etc).

Essentially, Application acts as a bootstrap, initialising the standard modules
and framework for you and then jumping into one of your blocks to do the actual
work of generating something to send back to the user. What happens when
Application hands execution over to your blocks is entirely up to you. See the
[Blocks](@ref blocks) documentation for information about what gets passed to
your block's constructor, and from there you can investigate the documentation
for the modules provided in the framework.

The Documentation
-----------------

The remainder of the documentation given here is split up into pages discussing
specific aspects of the library:

* [Blocks](@ref blocks) discusses the purpose, loading, and features of the
  Block class and subclasses you may with to implement in your application.
* [Structure](@ref appstructure) covers the suggested layout of files and directories.
* [Configuration](@ref config) discusses the core configuration file, and the
  optional settings table in the database.
* [Sessions](@ref sessions) introduces the session handling feature of the
  framework, and the various authentication schemes supported.
* [Quick start](@ref quickstart) is a very brief run-through of the steps needed
  to create a new webapp.

Finally, remember this is Perl - the instructions contained here, and in
the rest of the documentation, are not the only way to do it. If you find
that following the structure discussed in this documentation is limiting, go ahead
and try other ways - you'll undoubtedly be able to find many other ways of using
the framework that better suit your needs.