plainblack.com
Username Password
search
Bookmark and Share

Content Handlers

Content handlers give you an easy way to add your own functionality to WebGUI without having to incur the complexity of assets and URL handlers. Content handlers are given a WebGUI session, so you don't even need to set that up. Content handlers, equal to macros, are the easiest plugin you can write for WebGUI.

 

Request Cycle

Since content handlers are called by a URL handler, they sit in a position directly after the URL handlers. In the diagram below the grey areas are the URL handlers, and the black areas are content handlers.

 

When to Use

Content handlers should be written whenever you want to write something that doesn't need to directly interact with the request cycle, and doesn't need the power of an asset, but does need to be able to do round-trip requests. For example, a macro is an output mechanism only. You can't post back to a macro;however, with a content handler you can post back to it.

 

Content handlers need to decide when they will or won't handle a request. They are usually either looking for a specific URL to be requested (like an asset has a specific URL), or they're looking for something in the POST or GET parameters (like operations look for '?op='). If you don't put this sort of condition in, then the handler will always be called, and nothing else will ever get through. See the Hello World example later in this chapter for an example of that.

 

You may write a content handler as a gateway into some subsystem, such as the Shop content handler acts as a gateway into the WebGUI e-commerce functions. You may also use it to allow a macro to post back to the server, using the macro to display some output, and using the content handler to process the results of the post back.

 

Configuration

Configuring content handlers is relatively simple. Just add your content handler to the contentHandlers directive in the WebGUI config file. The default configuration looks something like this:

 

"contentHandlers" : [

"WebGUI::Content::Prefetch",

"WebGUI::Content::Maintenance",

"WebGUI::Content::Referral",

"WebGUI::Content::Operation",

"WebGUI::Content::Setup",

"WebGUI::Content::Shop",

"WebGUI::Content::Asset"

]

 

The order in which the content handler is specified is particularly important. Whichever is the first to return a value other than undef is the one that gets to service the request.

 

To add your own handler, simply add it to the list like this:

 

“WebGUI::Content::EmailProcessor”,

 

Examples

The following examples should get you started in writing your own content handlers.

 

Hello World

This is the simplest content handler you can write. Of course, it's also utterly useless. =)

 

package WebGUI::Content::HelloWorld;



use strict;



sub handler {

return “Hello World”;

}



1;

 

From the Core

WebGUI has many content handlers out of the box. Use these to get an idea of both how to build your own, and what they are capable of. Here's a brief rundown of some of them.

 

WebGUI::Content::Referral

WebGUI::Content::Referral never outputs anything. Instead, it tracks which site a new visitor to the site came from. As of this writing, this subsystem has very little functionality, and no reporting mechanism, but it does a good job as a proof of concept of how a content handler can be used for simple tracking.

 

WebGUI::Content::Asset

The WebGUI::Content::Asset handler instantiates the asset subsystem. It matches a URL to an asset using the database, and then hands off the request to the asset to complete processing. This is a great example of a URL based content handler.

WebGUI::Content::Shop

The WebGUI::Content::Shop handler is a good example of a URL query parameter (GET/POST parameter) based content handler. It looks at the query parameters, and if there's one called “shop” then it tries to invoke the commerce system. For example, if a URL looks like /home?shop=cart it will show you the shopping cart.

 

WebGUI::Content::Setup

The WebGUI::Content::Setup handler looks for a variable called specialState in the settings database table. If it's set to “init” then it will be invoked. This is what drives the WebGUI Site Configuration wizard.

 

WebGUI::Content::Maintenance

The WebGUI::Content::Maintenance handler also looks in the settings table for the specialState variable, but it's looking for a value of “upgrading”, which is set by sbin/upgrade.pl while it's running. Have a look at how this works. First, initialize the package like any other Perl module:

 

package WebGUI::Content::Maintenance;

use strict;

 

Then, create the required subroutine that all content handlers require:

 

sub handler {

my $session = shift;

...

}

 

Now, check the settings table for your special variable. If it's not what you're looking for, return undef so that the next content handler will process.

 

if ($session->setting->get("specialState") eq "upgrading") {

...

}

return undef;

 

If the specialState variable does equal “upgrading,” then you will read in the docs/maintenance.html file and return that back to the user, rather than the requested page, so that the user knows you're conducting maintenance.

 

$session->http->sendHeader;

my $output = "";

open(my $FILE,"<",$session->config->getWebguiRoot."/docs/maintenance.html");

while (<$FILE>) {

$output .= $_;

}

close($FILE);

return $output;

 

As you can see from these examples, writing content handlers is quite simple.

 

Handling a Post from an Arbitrary Form

Let's say your boss tells you that he'd like to collect email addresses from the people that visit the site, but there's a caveat. He wants to be able to display the form on every page, maybe in the style template, and wants the user to be returned back to the page he/she was visiting. You may decide to put the form directly into the style template, or you may use a snippet, or you may even create a macro for it. It really doesn't matter how the form is created. All that matters is that you can use a very simple content handler to capture the email addresses.

 

Say the form he wants looks like this:

 

<form>

Gimme Yer Email Sucka: <input type=”text” name=”email” />

<input type=”submit” />

</form>

 

You decide that you will look for a form parameter called “storeThisEmailAddress” when it equals “1”, so you add a hidden field to his form, like so:

 

<input type=”hidden” name=”storeThisEmailAddress” value=”1” />

 

Now you write a content handler to deal with this. First, start with a basic package.

 

package WebGUI::Content::EmailProcessor;



use strict;



sub handler {

my $session = shift;

... our code goes here ...

}



1;

 

Then, add a condition that you'll use to activate the handler.

 

if ($session->form->get('storeThisEmailAddress')) {

...

}



 

If it's true, then you can add your code to store the email address.

 

$session->db->write(“insert into emailStorage (email) values (?)”,

[$session->form->get('email')]);

 

Finally, always return undef from this handler because you want the user to be returned back to the page he/she was previously viewing.

 

return undef;

 

That's all there is to it! Here's what the final code looks like:

 

package WebGUI::Content::EmailProcessor;



use strict;



sub handler {

my $session = shift;

if ($session->form->get('storeThisEmailAddress')) {

$session->db->write(“insert into emailStorage (email) values (?)”,

[$session->form->get('email')]);

}

return undef;

}



1;



Keywords: apache API config file configuration gateway request cycle

Search | Most Popular | Recent Changes | Wiki Home
© 2018 Plain Black Corporation | All Rights Reserved