This is the second in a series of Cgiapp2 Tutorials.
In this tutorial, I cover creating what I call 'Pluggable Applications',
applications that can be distributed and customized to work with other
sites.
Background
In several positions I've held over the years, I've needed to use the same
application with very slight modifications on multiple sites. These include
article applications, galleries, contact forms, and more. The underlying
code typically remains the same -- but I may need to plug the content into a
different sitewide template, or require authentication.
When following MVC
well, many of these tasks are already easy. You can create a new instance of
the controller at will, and slip in new templates to customize the look and
feel. However, things like a sitewide template fall out of the scope of the
application templates; they are designed for a suite of
applications. Authentication is also typically very site dependent; sure,
your application may require a logged in user, but should you really dictate
what credentials are used? shouldn't that be left up to the site owner?
A good Controller can provide this kind of flexibility. With Cgiapp2's
callback hook system, you actually don't need to develop the application to
do some of these tasks; instead, you can leave it up to the end-user
developer to implement. This provides strong portability and incredible
flexibility in your applications.
Example 1: Add content to a sitewide template
One of the most common tasks I need to undertake is to add the content
generated by an application to a sitewide template. In Cgiapp, you can do
this via cgiapp_postrun().
cgiapp_postrun() is executed after the application logic is done, and
receives the generated content as its first argument:
public function cgiapp_postrun($body, $cgiapp)
{
$cgiapp->tmpl_assign('content', $body);
return $cgiapp->load_tmpl('site.phtml');
}
However, if you do this in your application logic, you're deciding things
for later users of the application. Leave it out. Instead, let the end-user
developer register their own postrun hook to do this. As an example:
require_once 'Cgiapp2.class.php';
require_once 'My/Article.php';
class OurSite
{ public
static function postrun
($body, Cgiapp2
$cgiapp) { $cgiapp->
tmpl_assign('content',
$body);
return $cgiapp->
load_tmpl('site.phtml');
}}Cgiapp2::
add_callback('postrun',
array('OurSite',
'postrun'),
'My_Article');
$app =
new My_Article
($options);
$app->
run();
The developer has now registered a 'postrun' hook with the My_Article
application. When the application flow hits the postrun event, it will
trigger OurSite::postrun(), which can then manipulate the content, throwing
it into the developer's sitewide template.
Example 2: Adding authentication
What if an article application doesn't require authentication, but you, as
the end-user developer, want to require it for the edit, add, and delete
views? Register a prerun action. Using our example from above:
require_once 'Cgiapp2.class.php';
require_once 'My/Article.php';
class OurSite
{ protected
static function _validate
($user,
$pass) { // ... validate user ... } public
static function prerun
($action, Cgiapp2
$cgiapp) { if (in_array($action,
array('add',
'edit',
'delete')) { // Need to authenticate... require_once 'Phly/Auth.php';
$auth =
new Phly_Auth
(array(self,
'_validate'));
$auth->
start();
if (!
$auth->
isValid) { // reset to the default entry for the app $cgiapp->
prerun_mode($cgiapp->
start_mode());
return;
} } } public
static function postrun
($body, Cgiapp2
$cgiapp) { $cgiapp->
tmpl_assign('content',
$body);
return $cgiapp->
load_tmpl('site.phtml');
}}Cgiapp2::
add_callback('prerun',
array('OurSite',
'prerun'),
'My_Article');
Cgiapp2::
add_callback('postrun',
array('OurSite',
'postrun'),
'My_Article');
$app =
new My_Article
($options);
$app->
run();
The example above uses Phly_Auth,
but could as easily use another authentication mechanism.
The prerun hook is executed just prior to running the requested action, and
receives the requested action as its first argument. In the code above, we
check to see if the action requires authentication, and if so, check the
user's credentials. If they are not authenticated, we then reset the action
to the default entry action.
Summary
Cgiapp2's callback hook system allows incredible opportunities for end-user
developers to customize applications on a per-instance basis. This tutorial
covered two hooks, prerun and postrun, but several more are available, and
Cgiapp2 provides the means for creating additional hooks in your
applications.
For more information on this topic, see the callback hook documentation.
