Module

(Redirected from Modules)

A Module is a program that provides functionality as part of a Baldrick Site. Each Site has at least one module; it might have many.

A Module is something like a blog, a message board, a shopping cart, a calendar, a photo gallery.

Modules are developed by independent programmers using the Baldrick framework. They may be made available for download, or kept private.

A Baldrick Module consists of:

a Module definition, in the form of a Module section in baldrick.cfg
PathMap entries that direct Baldrick to load the module for particular URLs
at least one Perl Module, that inherits from Baldrick::Dogsbody (MVC "Controller")
other Perl modules, database records, files, etc., that enable the module to do something useful (MVC "Model")
output template files, by which any of several TemplateAdapters can generate content for the user's screen. (MVC "View")

[edit] Installing third-party Modules

A Module is added to a Site by this process:

downloading the module distribution from the author
placing its source code in the Perl include path
choosing a URL, and copying the standard baldrick-stub there
editing the PathMap in baldrick.cfg
adding a Module section to baldrick.cfg
performing any configuration needed for the module, in that module's own configuration file.

Programmers wishing to use Baldrick for their own projects will generally begin by writing new modules.

Step 0 - Choose a template system.: Output is generated through various template-processing engines. As of version 0.83 (November 2007), the options are Template Toolkit and Text::Template - more may be added on request (this author prefers Template Toolkit). Install the template system of your choice from CPAN if you don't have it already.; example: root# cpan Template

Step 1 - Choose a Perl namespace for your module.: Choose a unique prefix for your class names. This should not contain "Baldrick".; example: "FredBlog::", "AcmeCart::"

Step 2 - make a directory for that namespace in the Perl include-path.: You probably don't want to put your classes in the system-wide Perl include path (/usr/lib/perl5) - you'll want them in directories associated with your web site, particularly if you're on a shared server. baldrick-stub, on startup, modifies its default include-path to include the "lib" directory within the directory where baldrick-stub is installed. This is a good place to put your application's Perl modules.; example: $ mkdir /www/example.com/cgi-bin/lib/FredBlog

Step 3 - make a templates directory: You'll need a directory for your templates, preferably with the "templates" directory in the cgi-bin directory where baldrick-stub is installed. Please use a name that will likely be unique, and make a subdirectory there.; example: $ mkdir /www/example.com/cgi-bin/templates/FredBlog

Step 4 - copy and rename Baldrick::ExampleDogsbody: Baldrick::ExampleDogsbody is a class intended to serve as a template for module-authors' request handlers - it is never instantiated directly or inherited from. Copy it to the location you've chosen for your classes, renaming it to something appropriate. I recommend a name ending in "Handler" (in corporate environments) or "Dogsbody" (for fun projects).; example: $ cp lib/Baldrick/ExampleDogsbody.pm lib/FredBlog/BlogDogsbody.pm

Step 5 - edit your renamed Dogsbody class.: Change the "package" at the top of the file to something appropriate (FredBlog::BlogDogsbody for example). Change the init() parameters to point to your subdirectory of "templates").

Step 6 - make a symlink to baldrick-stub: You probably don't want "baldrick-stub" as the URL, so link it to something else -- "shop", "blog", "forum", or whatever is appropriate. See the baldrick-stub article

Step 7 - Create a PathMap entry and Module section.: Edit etc/baldrick.cfg to point to the baldrick-stub symlink you created (via PathMap, and to associate it with your module (via the Module section's 'handler-class directive).

Step 8 - Test it in a web browser.: Go to the URL associated with your baldrick-stub symlink - something like http://www.example.com/cgi-bin/blog. If it works, the framework will dispatch the request to your new handler, and to the handler function associated with the default command. (If you started with ExampleDogsbody and didn't change the default, then it will run handleTest(), which prints the class name of the handler class and some other semi-useful info).

Step 9 - Programming.: Everything else is just a simple matter of programming.