Andrew's Web Libraries (AWL)
awl Namespace Reference

Detailed Description

Authentication handling class

This class provides a basic set of methods which are used by the Session class to provide authentication.

This class is expected to be replaced, overridden or extended in some instances to enable different pluggable authentication methods.

AuthPlugin

Author
Andrew McMillan andre.nosp@m.w@mc.nosp@m.milla.nosp@m.n.ne.nosp@m.t.nz

A class for authenticating and retrieving user information

The authentication handling plugins can be used by the Session class to provide authentication.

Each authenticate hook needs to:

  • Accept a username / password
  • Confirm the username / password are correct
  • Create (or update) a 'usr' record in our database
  • Return the 'usr' record as an object
  • Return === false when authentication fails

It can expect that:

  • Configuration data will be in $c->authenticate_hook['config'], which might be an array, or whatever is needed.

In order to be called:

  • This file should be included
  • $c->authenticate_hook['call'] should be set to the name of the plugin
  • $c->authenticate_hook['config'] should be set up with any configuration data for the plugin

AuthPlugin

Author
Andrew McMillan andre.nosp@m.w@mc.nosp@m.milla.nosp@m.n.ne.nosp@m.t.nz

Authenticate against a different PostgreSQL database which contains a usr table in the AWL format.

Authentication has already happened. We know the username, we just need to do the authorisation / access control. The password is ignored.

AwlDatabase query/statement class and associated functions

This subpackage provides some functions that are useful around database activity and a AwlDBDialect, AwlDatabase and AwlStatement classes to simplify handling of database queries and provide some access for a limited ability to handle varying database dialects.

The class is intended to be a very lightweight wrapper with some features that have proved useful in developing and debugging web-based applications:

  • All queries are timed, and an expected time can be provided.
  • Parameters replaced into the SQL will be escaped correctly in order to minimise the chances of SQL injection errors.
  • Queries which fail, or which exceed their expected execution time, will be logged for potential further analysis.
  • Debug logging of queries may be enabled globally, or restricted to particular sets of queries.
  • Simple syntax for iterating through a result set.

See http://wiki.davical.org/w/AwlDatabase for design and usage information.

If not already connected, AwlDatabase will attempt to connect to the database, successively applying connection parameters from the array in $c->pdo_connect.

We will die if the database is not currently connected and we fail to find a working connection.

AwlDatabase

Author
Andrew McMillan andre.nosp@m.w@mo.nosp@m.rphos.nosp@m.s.co.nosp@m.m

Methods in the AwlDBDialect class which we inherit, include: __construct() SetSearchPath( $search_path ) GetVersion() GetFields( $tablename_string ) TranslateSQL( $sql_string ) Quote( $value, $value_type = null ) ReplaceParameters( $query_string [, param [, ...]] ) Typically there will only be a single instance of the database level class in an application.

AwlDatabase - support for different SQL dialects

This subpackage provides dialect specific support for PostgreSQL, and may, over time, be extended to provide support for other SQL dialects.

See http://wiki.davical.org/w/Coding/AwlQuery for design and usage information.

AwlDatabase

Author
Andrew McMillan andre.nosp@m.w@mo.nosp@m.rphos.nosp@m.s.co.nosp@m.m

The AwlDBDialect class handles support for different SQL dialects

This subpackage provides dialect specific support for PostgreSQL, and may, over time, be extended to provide support for other SQL dialects.

If you are looking for the place to add support for other SQL dialects, this is the class that you should be looking at. You might also look at the AwlDatabase class which extends this one, but these are the core capabilities which most probably need attention.

AwlDatabase

Author
Andrew McMillan andre.nosp@m.w@mo.nosp@m.rphos.nosp@m.s.co.nosp@m.m

The AwlQuery Class.

This class builds and executes SQL Queries and traverses the set of results returned from the query.

Example usage $sql = "SELECT * FROM mytable WHERE mytype = ?"; $qry = new AwlQuery( $sql, $myunsanitisedtype ); if ( $qry->Exec("typeselect", line, file ) && $qry->rows > 0 ) { while( $row = $qry->Fetch() ) { do_something_with($row); } }

AwlDatabase

Author
Andrew McMillan andre.nosp@m.w@mo.nosp@m.rphos.nosp@m.s.co.nosp@m.m

Database upgrader class and associated functions

This subpackage provides some functions that are useful around database schema creation and changes. The AwlUpgrader Class.

This class updates an Awl database to a newer schema version.

Utility functions of a general nature which are used by most AWL library classes.

Utilities

Author
Andrew McMillan andre.nosp@m.w@mc.nosp@m.milla.nosp@m.n.ne.nosp@m.t.nz

Table browser / lister class

Browsers are constructed from BrowserColumns and can support sorting and other interactive behaviour. Cells may contain data which is formatted as a link, or the entire row may be linked through an onclick action.

Browser

Author
Andrew McMillan andre.nosp@m.w@mc.nosp@m.milla.nosp@m.n.ne.nosp@m.t.nz

BrowserColumns are the basic building blocks. You can specify just the field name, and the column header or you can get fancy and specify an alignment, format string, SQL formula and cell CSS class.

Start a new Browser, add columns, set a join and Render it to create a basic list of records in a table. You can, of course, get a lot fancier with setting ordering, where clauses totalled columns and so forth.

Class for editing a record using a templated form.

classEditor

Author
Andrew McMillan andre.nosp@m.w@mc.nosp@m.milla.nosp@m.n.ne.nosp@m.t.nz

A class for the fields in the editor

The class for the Editor form in full

Classes to handle entry and viewing of field-based data.

DataEntry

Author
Andrew McMillan andre.nosp@m.w@mc.nosp@m.milla.nosp@m.n.ne.nosp@m.t.nz

Individual fields used for data entry / viewing.

This object is not really intended to be used directly. The more normal interface is to instantiate an EntryForm and then issue calls to DataEntryLine() and other EntryForm methods.

Understanding the operation of this class (and possibly auditing the source code, particularly EntryField::Render) will however convey valuable understanding of some of the more esoteric features.

Todo:
This class doesn't really provide a huge amount of utility between construct and render, but there must be good things possible there. Perhaps one EntryField is created and used repeatedly as a template (e.g.). That might be useful to support... Why is this a Class anyway? Maybe we should have just done half a dozen functions (one per major field type) and just used those... Maybe we should build a base class for this and extend it to make EntryField in a better way.

EntryField is only useful at present if you desperately want to use it's simple field interface, but want to intimately control the layout (or parts of the layout), otherwise you should be using EntryForm as the main class.

A class to handle displaying a form on the page (for editing) or a structured layout of non-editable content (for viewing), with a simple switch to flip from view mode to edit mode.

Some functions and a base class to help with updating records.

This subpackage provides some functions that are useful around single record database activities such as insert and update.

DataUpdate

Author
Andrew McMillan andre.nosp@m.w@mc.nosp@m.milla.nosp@m.n.ne.nosp@m.t.nz

A Base class to use for records which will be read/written from the database.

Lightweight class for sending an e-mail.

EMail

Author
Andrew McMillan andre.nosp@m.w@mc.nosp@m.milla.nosp@m.n.ne.nosp@m.t.nz

Lightweight class for sending an e-mail.

A Class for representing properties within an iCalendar

iCalProp

Author
Andrew McMillan andre.nosp@m.w@mc.nosp@m.milla.nosp@m.n.ne.nosp@m.t.nz

A Class for representing components within an iCalendar

iCalComponent

Author
Andrew McMillan andre.nosp@m.w@mc.nosp@m.milla.nosp@m.n.ne.nosp@m.t.nz

Some intelligence and standardisation around presenting a menu hierarchy.

See the MenuSet class for examples as that is the primary interface.

See also
MenuSet

MenuSet

Author
Andrew McMillan andre.nosp@m.w@mc.nosp@m.milla.nosp@m.n.ne.nosp@m.t.nz

Each menu option is an object.

A MenuSet is a hierarchy of MenuOptions, some of which might be MenuSet objects themselves.

The menu options are presented in HTML span tags, and the menus themselves are presented inside HTML div tags. All layout and styling is expected to be provide by CSS.

A non-trivial example would look something like this: require("MenuSet.php"); $main_menu = new MenuSet('menu', 'menu', 'menu_active'); ... $other_menu = new MenuSet('submenu', 'submenu', 'submenu_active'); $other_menu->AddOption("Extra Other","/extraother.php","Submenu option to do extra things."); $other_menu->AddOption("Super Other","/superother.php","Submenu option to do super things."); $other_menu->AddOption("Meta Other","/metaother.php","Submenu option to do meta things."); ... $main_menu->AddOption("Do This","/dothis.php","Option to do this thing."); $main_menu->AddOption("Do That","/dothat.php","Option to do all of that."); $main_menu->AddSubMenu( $other_menu, "Do The Other","/dotheother.php","Submenu to do all of the other things.", true); ... if ( isset($main_menu) && is_object($main_menu) ) { $main_menu->AddOption("Home","/","Go back to the home page"); echo $main_menu->Render(); } In a hierarchical menu tree, like the example above, only one sub-menu will be shown, which will be the first one that is found to have active menu options.

The menu display will generally recognise the current URL and mark as active the menu option that matches it, but in some cases it might be desirable to force one or another option to be marked as active using the appropriate parameter to the AddOption or AddSubMenu call.

PostgreSQL query class and associated functions

This subpackage provides some functions that are useful around database activity and a PgQuery class to simplify handling of database queries.

The class is intended to be a very lightweight wrapper with no pretentions towards database independence, but it does include some features that have proved useful in developing and debugging web-based applications:

  • All queries are timed, and an expected time can be provided.
  • Parameters replaced into the SQL will be escaped correctly in order to minimise the chances of SQL injection errors.
  • Queries which fail, or which exceed their expected execution time, will be logged for potential further analysis.
  • Debug logging of queries may be enabled globally, or restricted to particular sets of queries.
  • Simple syntax for iterating through a result set.

The database should be connected in a variable $dbconn before PgQuery.php is included. If not already connected, PgQuery will attempt to connect to the database, successively applying connection parameters from the array in $c->pg_connect.

We will die if the database is not currently connected and we fail to find a working connection.

PgQuery

Author
Andrew McMillan andre.nosp@m.w@mc.nosp@m.milla.nosp@m.n.ne.nosp@m.t.nz

The PgQuery Class.

This class builds and executes PostgreSQL Queries and traverses the set of results returned from the query.

Example usage $sql = "SELECT * FROM mytable WHERE mytype = ?"; $qry = new PgQuery( $sql, $myunsanitisedtype ); if ( $qry->Exec("typeselect", line, file ) && $qry->rows() > 0 ) { while( $row = $qry->Fetch() ) { do_something_with($row); } }

Session handling class and associated functions

This subpackage provides some functions that are useful around web application session management.

The class is intended to be as lightweight as possible while holding all session data in the database:

  • Session hash is not predictable.
  • No clear text information is held in cookies.
  • Passwords are generally salted MD5 hashes, but individual users may have plain text passwords set by an administrator.
  • Temporary passwords are supported.
  • Logout is supported
  • "Remember me" cookies are supported, and will result in a new Session for each browser session.

Session

Author
Andrew McMillan andre.nosp@m.w@mc.nosp@m.milla.nosp@m.n.ne.nosp@m.t.nz

A class for creating and holding session information.

Functions involved in translating with gettext

Translation

Author
Andrew McMillan andre.nosp@m.w@mc.nosp@m.milla.nosp@m.n.ne.nosp@m.t.nz

A class to handle reading, writing, viewing, editing and validating usr records.

Author
Andrew McMillan andre.nosp@m.w@mc.nosp@m.milla.nosp@m.n.ne.nosp@m.t.nz

We need to access some session information. We use the DataEntry class for data display and updating We use the DataUpdate class and inherit from DBRecord A class to handle reading, writing, viewing, editing and validating usr records.

User

Classes to handle validation of form data.

Validation

Author
Emily Mossman emily.nosp@m.@mcm.nosp@m.illan.nosp@m..net.nosp@m..nz

Rules used for validation of form fields.

A Class for handling vCalendar data.

When parsed the underlying structure is roughly as follows:

vCalendar( array(vComponent), array(vProperty), array(vTimezone) )

with the TIMEZONE data still currently included in the component array (likely to change in the future) and the timezone array only containing vComponent objects (which is also likely to change).

vCalendar

Author
Andrew McMillan andre.nosp@m.w@mc.nosp@m.milla.nosp@m.n.ne.nosp@m.t.nz

A Class for handling vCalendar & vCard data.

When parsed the underlying structure is roughly as follows:

vComponent( array(vComponent), array(vProperty) )

vComponent

Author
Milan Medlik milan.nosp@m.@mor.nosp@m.phoss.nosp@m..com

A Class for representing properties within a myComponent (VCALENDAR or VCARD)

Handling of namespacing for XML documents

XMLDocument

Author
Andrew McMillan andre.nosp@m.w@mo.nosp@m.rphos.nosp@m.s.co.nosp@m.m

A class for XML Documents which will contain namespaced XML elements

A class to assist with construction of XML documents

XMLElement

Author
Andrew McMillan andre.nosp@m.w@mc.nosp@m.milla.nosp@m.n.ne.nosp@m.t.nz

A class for XML elements which may have attributes, or contain other XML sub-elements