Adding work-in-progress documentation.

mdfiles/blocks.md

@@ -0,0 +1,43 @@
+Blocks                                                                 {#blocks}
+======
+
+The Block class serves as the base class for 'blocks' in your web application.
+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.
+
+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.
+
+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
+of the more important and useful ones are:
+
+* `$self -> {"template"}` contains a reference to the application's instance
+of Template.
+* `$self -> {"settings"}` is the web application's settings object. See the
+[Configuration](@ref config) documentation for more on this, but usually you will
+need to use `$self -> {"settings"} -> {"database"} -> {somename}` to use the
+database table name mapping feature, and the settings stored in the settings
+table are loaded into `$self -> {"settings"} -> {"config"}` as key-value pairs.
+* `$self -> {"module"}` is an instance of the Modules class, through which
+you can load other blocks as needed, or even dynamically load any perl module
+that has a `new()` constructor via Modules::load_module().
+* `$self -> {"cgi"}` is the global CGI object (or CGI::Compress::Gzip if you
+have that available). You can use it to pull values out of the POST/GET data,
+and so on.
+* `$self -> {"dbh"}` is a DBI object connected to the web application's
+database, issue queries through this rather than creating a separate
+connection if possible.
+* `$self -> {"session"}` is a reference to the current SessionHandler object. See
+the [Sessions](@ref sessions) documentation for more about this.
+
+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.

mdfiles/config.md

@@ -0,0 +1,9 @@
+Configuration                                                        {#config}
+=============
+
+All web applications need some degree of configuration information to operate.
+The webperl framework uses the ConfigMicro class to load a single global config
+file, the information in that file is then used to initialise the rest of the
+system - if you use the Application class, the configuration file must include
+the information about the database the web application will work with, and
+how to map 'internal' table names to the actual names of tables in the database.

mdfiles/overview.md

@@ -0,0 +1,38 @@
+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, here.
+
+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. 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.
+
+

mdfiles/structure.md

@@ -0,0 +1,41 @@
+Web App Structure                                            {#appstructure}
+=================
+
+The framework assumes that a specific files and directories are present in
+order to work correctly. Note that you can easily change these if you handle
+the initialisation of the various modules in the framework yourself, but if
+you use the Application module to handle all the setup for you, you must
+follow the structure given in this documentation.
+
+Structure overview
+------------------
+
+This diagram shows a typical web application's directory hierarchy. Notes
+follow the diagram
+
+![directory structure](filestructure.png)
+
+<dl><dt>blocks</dt>
+<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
+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
+passed to your Block implementations.</dd>
+</dl>
+
+<dl><dt>index.cgi</dt>
+<dd>The front-end script for the application (or, potentially, one of them).
+If you are using the Application class to handle all the framework setup for
+you, this will usually contain very little code indeed - potentially only
+the 6 lines shown in the Application documentation!</dd>
+</dl>
+
+<dl><dt>lang</dt>
+<dd>has subdirectories containing language files.</dd>
+</dl>