NAME

Bigtop::Backend::Control - defines legal keywords in control blocks

SYNOPSIS

If you are making a control generating backend:

    use Bigtop::Backend::Control;

This specifies the valid keywords for the controller.

If you need additional keywords which are generally useful, add them here (and send in a patch). If you need backend specific keywords, register them within your backend module.

DESCRIPTION

If you are using a Bigtop backend which generates controllers, you should read this document to find out what the valid keywords inside controller blocks are and what affect they have.

If you are writing a Bigtop backend which generates controllers, you should use this module. That will register the standard controller keywords with the Bigtop parser.

BASIC STRUCTURE

A controller block looks like this:

    controller name { }

Inside the braces, you can include simple statements or method blocks. Each method block looks like this:

    method name is type { }

The type must be supported by your backend. Look in its pod for SUPPORTED TYPES.

KEYWORDS in app blocks

This module registers these keywords in app blocks:

authors

These are the authors which Control backends will put in the pod stub for each generated module. Unless you use the copyright_holder statement, the first author will also be used as the copyright holder.

Entries in this list may be either simple names or name => email pairs.

contact_us

Text to include in the CONTACT US section of the base module's POD.

copyright_holder

This string will come at the end of the phrase Copyright... in the pod. By default, it will be the first person in the authors list.

email

Deprecated synonymn for contact_us.

This will be presented by the Control backend as the author's email in the AUTHOR section of the pod block at the bottom of each module.

license_text

The exact text of the paragraph that comes directly after the copyright statement in the all files that have that. Controllers should pick a default that h2xs would have generated for Perl version 5.8 or later.

Example:

    copyright_holder `Your Company Inc.`;
    license_text     `All rights reserved.`;

Example output:

    Copyright (c) 2005 Your Company Inc.

    All rights reserved.

location

Base url for the application. Normally, this applies only to httpd.conf and things like it. We need it here to generate tests.

KEYWORDS in controller blocks

The simple statement keywords available in controller blocks are (all of these are optional):

controls_table: This is the name of the table which this controller controls. It must be defined in a table block somewhere in the bigtop file.
uses: A comma separated list of modules which the controller should include with Perl use statements. There is not currently a way to limit what these modules export, except by editing the generated stub.
text_description: This is a short phrase that describes the rows of the table. It will usually become the return value of get_text_description (a class accessor). For example, Gantry's AutoCRUD uses this in user messages.
rel_location: The location (URL suffix) relative to the base location of the application, which will hit a given controller. This keyword is primarily for httpd conf and the like, but we need it here to generate tests.
location: The location (URL) which will hit a given controller. This keyword is primarily for httpd conf and the like, but we need it here to generate tests.

Note that some other backend types also look for information in controller blocks. Pay particular attention to HttpdConf backends. They typically expect a location or rel_location keyword which becomes the Apache Location for the controller.

METHODS for Control backends

is_controller_keyword: Parameters: a word which might be a controller keyword
Returns: true if it is a controller keyword, false otherwise

AUTHOR

Phil Crow <crow.phil@gmail.com>

COPYRIGHT and LICENSE

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.6 or, at your option, any later version of Perl 5 you may have available.