Roger Pettett > ClearPress > ClearPress

Download:
ClearPress-457.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  2
Open  0
View/Report Bugs
Module Version: 457   Source  

NAME ^

ClearPress - Simple, fresh & fruity MVC framework - http://clearpress.net/

VERSION ^

$Revision: 414 $

SYNOPSIS ^

DESCRIPTION ^

Application Structure

 /cgi-(bin|perl)/application
 /lib/application/model/*.pm
 /lib/application/view/*.pm
 /data/config.ini
 /data/templates/*.tt2

Application Setup

 The simplest method for setting up a clearpress application is to use
 the 'clearpress' script in the scripts/ subdirectory. See the POD
 there for usage instructions.

Adding models

 Models should generally be object representations of rows of entities
 from a specific database table. There are some occasions where models
 can be purely virtual, usually for convenience or inheritance, but on
 the whole things are quite straight-forward.

 ClearPress models do not (currently) inspect the database to
 determine structure and accessors. The rationale for this is that
 schema structure changes relatively infrequently and when it does
 it's reasonable to modify the data model to reflect it. There are of
 course both pros and cons in terms of efficiency for this approach.

 So let's say we have a table called 'person' for our application
 'app', looking like this:

 id_person forename surname initials

 To create a model for this by hand we'd make app/model/person.pm ,
 and extend ClearPress::model . Firstly we specify the array of fields
 in the database. Secondly we ask Class::Accessor to auto-create
 accessors for those fields. There you have it!

 package app::model::person;
 use base qw(ClearPress::model);
 use strict;
 use warnings;

 __PACKAGE__->mk_accessors(fields());

 sub fields {
  return qw(id_person forename surname initials);
 }

 1;

 Let's now say that a person has a person_role but we want to normalise roles
 to a dictionary table, person_role_dict.

 person_role looks like this:

 id_person_role id_person id_person_role_dict

 and person_role_dict looks like this:

 id_person_role_dict description


 To add the role dictionary association 'through' the person_role
 table in our person model we say:

 __PACKAGE__->belongs_to_through('person_role_dict|person_role');

 You can also use the synonym 'has_a_through' if it makes more
 grammatical sense. You will also need to define person_role_dict and
 person_role models to support querying database fields.

Adding views

 Basic views are extremely easy to add. To create a view to reflect
 our new 'person' model we would add the file app/view/person.pm and
 make it inherit from ClearPress::view.

 package app::view::person;
 use strict;
 use warnings;
 use base qw(ClearPress:view);

 1;

 For each standard action there needs to be a tt2 template in
 data/templates, so add the files:

 data/templates/person_list.tt2
 data/templates/person_add.tt2
 data/templates/person_edit.tt2
 data/templates/person_create.tt2
 data/templates/person_read.tt2
 data/templates/person_update.tt2
 data/templates/person_delete.tt2

 and put appropriate content into each one. See 'Templates' for more
 about the things you can do with these.

 That's really all there is to it for the basic functionality. By
 default there's no authentication or authorisation built-in so this
 basic view allows list/edit/add/create/read/update/delete as you'd
 expect.

Templates

 There are a number of things which ClearPress makes available to the
 template system. See ClearPress::view for a full list but the most
 important ones are:

 requestor   - an object (usually) representing the person requesting
               the page, if authentication is available.

 model       - the data model for the entity being viewed

 SCRIPT_NAME - very useful for building self-referential urls for
               links, forms, ajax etc.

 So person_list.tt2 might look like this:

 <table id="people">
  <caption>People</caption>
  <thead><tr><th>Id</th><th>Name</th><th>Initials</th></tr></thead>
  <tbody>
   [% FOREACH person = model.people %]
   <tr>
    <td>[% person.id_person %]</td>
    <td>[% person.forename | html %]</td>
    <td>[% person.initials | html %]</td>
   </tr>
   [% END %]
  </tbody>
 </table>

 person_add.tt2 might look like this:

 <form method="post" action="[% SCRIPT_NAME %]/person">
 <ul>
  <li><label for="forename">Forename</label><input type="text" name="forename" id="forename"/></li>
  <li><label for="surname">Surname</label>  <input type="text" name="surname"  id="surname" /></li>
  <li><label for="initials">Initials</label><input type="text" name="initials" id="initials"/></li>
 </ul>
 </form>

 person_create.tt2 might look like this:

 <h1>Person Created!</h1>
 Click <a href="[% SCRIPT_NAME %]/person/[% model.id_person %]">here</a> to continue.

 <script type="text/javascript">
  document.location.href="[% SCRIPT_NAME %]/person/[% model.id_person %]";
 </script>

SUBROUTINES/METHODS ^

 There are no methods in this module. It's purely for documentation
 purposes. See the POD for this module's dependencies for details of
 the guts.

DIAGNOSTICS ^

CONFIGURATION AND ENVIRONMENT ^

 Most configuration settings for ClearPress-based applications come
 form data/config.ini . Environment variables which have influential
 effects include in particular 'dev' (set to 'dev', 'test' or 'live')
 and DOCUMENT_ROOT, commonly set to './htdocs'.

DEPENDENCIES ^

ClearPress::model
ClearPress::view
ClearPress::controller
ClearPress::util
strict
warnings
CGI
POSIX
Template
Lingua::EN::Inflect
HTTP::Server::Simple::CGI
Config::IniFiles

INCOMPATIBILITIES ^

BUGS AND LIMITATIONS ^

ClearPress is not an implementation of the classic MVC pattern, in particular ClearPress views are more like classic MVC controllers, so if you're expecting that, you may be disappointed. Having said that it has been used extremely effectively in rapid development of a number of production applications.

AUTHOR ^

Roger Pettett, <rpettett@cpan.org>

LICENSE AND COPYRIGHT ^

Copyright (C) 2008 Roger Pettett

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.4 or, at your option, any later version of Perl 5 you may have available.

syntax highlighting: