Chris/webperl
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Documentation!

Browse Source
This commit is contained in:
Chris 2012-03-26 17:51:41 +01:00
parent fbf834cc0b
commit de075b8726
3 changed files with 66 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
mdfiles/blocks.md
View File

@ -6,13 +6,14 @@ A 'block' is considered to be a discrete feature of your web application - you
will usually have a `Login.pm` block that handles logging users in and out, you
might have a `Core.pm` block that generates the front page and a few associated
pages. Essentially, each feature of your application will usually have one or
more blocks associated with it.
more blocks associated with it. How granular you wish to be is entirely up to
you - the system does not enforce any rules on this.
The Block class itself is quite simple: it provides a number of useful validation
functions, so that your code doesn't need to implement its own string and option
validation in most cases, it allows your application to log user actions if
needed, and it provides a stub implementation of the page_display() function
that all subclasses need to override.
needed, and it provides stub implementations of the page_display() and
block_display() functions, one or both of which all subclasses need to override.
Each subclass of Block gets a number of references to useful objects added to
it on creation, and methods in the subclass can access them from $self. Some
@ -37,7 +38,24 @@ connection if possible.
* `$self -> {"session"}` is a reference to the current SessionHandler object. See
the [Sessions](@ref sessions) documentation for more about this.
Each Block subclass also has access to a few values that can be useful:
* `$self -> {"args"}` is a string containing any arguments set in the block's
row in the blocks table in the database. The format of this string is not
enforced, and will vary from module to module.
When subclassing Block, you will need to provide your own implementation of
Block::page_display() - in most cases that's the only method you need to
worry about overriding, and the remaining methods in Block will generally
be usable as-is.
either Block::page_display() or Block::block_display() (or perhaps both!)
In most cases you will only need to implement one of them, and the remaining
methods in Block will generally be usable as-is. If your block is able to
generate a complete page, you should implement the page_display() method. If
your block is only intended to produce a fragment of a page, and be invoked
by other blocks as needed, you'll need to write a block_display() method
instead. Sometimes you may find that there could be two different 'views' of
your block - say that your system includes a calendar, and sometimes it will
be displayed as a small box in a page with other content, and sometimes
the user will want to look at a page that shows nothing but the calendar.
You can implement both page_dusplay() and block_display() for the block,
the latter dealing with the situation where the calendar is embedded in a
larger page, while the former handles the situation where the user is
looking at just the calendar.

28
mdfiles/overview.md
View File

@ -28,11 +28,27 @@ Block class, usually stored in the cunningly named `blocks` directory (see the
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. If you are using the Application class as
the base of your webapp, it will automatically load one of the Block subclasses
using the value specified in the 'block' parameter in the query string or POSTed
data (if the value in the blocks 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.
redundant functionality when started.
If you are using the Application class as the base of your webapp, it will
automatically load one of the Block subclasses using the value specified in the
'block' parameter in the query string or POSTed data (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 by Application, it calls the block's page_display()
function and prints the result 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.

23
mdfiles/structure.md
View File

@ -16,13 +16,13 @@ follow the diagram
![directory structure](filestructure.png)
<dl><dt>blocks</dt>
<dd>contains subclasses of Block that implement the actual functionality of
<dd>Contains subclasses of Block that implement the actual functionality of
your web application. Further subdirectories may be present, if more complex
class hierarchies are needed. See the @ref blocks "Blocks" information for more details.</dd>
</dl>
<dl><dt>config</dt>
<dd>contains the global site.cfg file, protected by .htaccess. You can easily
<dd>Contains the global site.cfg file, protected by .htaccess. You can easily
place the configuration file outside the web tree if you want, by using the
`config` argument to Application::new(). See the @ref config "Configuration" information for
more about the config file, and how configuration information is stored and
@ -37,5 +37,22 @@ the 6 lines shown in the Application documentation!</dd>
</dl>
<dl><dt>lang</dt>
<dd>has subdirectories containing language files.</dd>
<dd>Contains subdirectories containing language files. Each subdirectory should be
a language name, and can contain any number of files that define the language
variables for the template engine. If langauge file handling is disabled in the
template engine, this directory can be omitted.</dd>
</dl>
<dl><dt>modules</dt>
<dd>If you have any application-specific non-Block modules, you may wish to
add them to a separate directory tree for clarity (remember to add `use lib qw(modules)`
to the index.cgi file if you do this). The modules directory can contain any
modules you need, and by calling Modules::add_load_path() you can even use the
dynamic module loading facility to load modules from this directory too.</dd>
</dl>
<dl><dt>templates</dt>
<dd>The templates directory contains the templates for the application, each
set of templates is arranged in its own theme directory - you will generally
need to provide at least the 'default' template directory.</dd>
</dl>