GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  BIGTOP::KEYWORDS (3)

.ds Aq ’

NAME

Bigtop::Keywords - A central place to describe all bigtop keywords

CONTENTS

SYNOPSIS

In your backend or backend type module:



    use Bigtop::Keywords;
    # There is no need to use Bigtop::Parser since it uses you.

    BEGIN {
        Bigtop::Parser->add_valid_keywords(
            Bigtop::Keywords->get_docs_for(
                $keyword_level,
                qw( your keywords here )
            )
        );
    }



Note that this must be done in a BEGIN block.

Or, if you are writing a documenation tool:



    my $keyword_for = Bigtop::Keywords->get_full_doc_hash();



DESCRIPTION

Since many backends need to use the same keywords, it eventually dawned on me that a central place to describe would be a good thing. This is that place. By keeping all the keyword definitions here, all backends can share them. This became especially helpful with the birth of tentmaker. It wants to consistently tell users about the keywords.

If you write or modify a backend and need new keywords in the process, define them here and send in a patch. This will avoid name collisions and keep the tentmaker functioning. Read on for how to define the keywords.

DEFINING KEYWORDS

To define a new keyword, first decide at what level it will be used. That is, does it apply inside controller blocks, table blocks, or somewhere else. See KEYWORD LEVELS for a list of all the choices.

Once you know where your keyword should be legal, find its level among the top level keys in the %docs_for in this file. Inside the hash for your level add a new hash keyed by your keyword name (pick the name carefully, changing them after release is painful). The value for your new hash key is itself a hash. Here are the legal keys for the hash (all keys are optional unless marked required):
keyword Required and must be the same as the key for the hash. The official name of the keyword. The user must type this to use the keyword (or get a tool to do it for her).
label Required for tentmaker. The name tentmaker shows its users for this keyword. Traditionally, this is just the keyword beautified so the label for keyword ’contact_us’ is ’Contact Us’.
descr tentmaker shows this next to the input box for the keyword. Feel free to use a bit of html in the value for descr. For instance, when providing examples, surround them with pre tags.
sort_order tentmaker uses this to order the statements within their category. A simple numeric sort is done on these values.
multiple Indicates that the keyword can accept a list of values (or pairs of them if its type is pair). This only applies to types text, pair, and select. The others ignore it. See below for information about types.
repeatable Indicates that the statement can be repeated. Currently only data statements may be repeated to any useful effect. To contrast, multiple means that the single statement can take many values in a comma separated list, while repeatable means that the keyword itself may be used many times each timw with one or more values. Again, only data statements are repeatble.
pair_labels You probably want to use this key if your keyword’s type is pair. A two element array reference with the labels to display over the two input columns of keywords whose type is pair. Example:



    pair_labels => [ Name, Email Address ],



pair_required Required for keywords of type pair.

Use this key for all pair keywords. Make it true if a pair is always required for the keyword and false if items may have only the first half of a pair (like author pairs where the name is in the hash key position and the optional email address is in the value position).

Look for keywords of type pair for examples.

options An array reference of hashes describing the options for the keyword. Use this only for keywords of type select. Example:



    options => [
        { label => User Sees This, value => internal_value },
        { label => Hourly,         value => 24             },
    ],



If you don’t want a default, you should include a hash like this:



    { label => -- Choose One --, value => undefined },



The value ’undefined’ is special to JavaScript. So, tentmaker will unset the value if you the user selects ’-- Choose One --’.

quick_label Only applies to field keywords. Indicates that this keyword should appear in the Field Quick Edit box in tentmaker. Fields appear there in the same order they appear in the full edit expanding box. That order is controlled by the sort_order (see below).

Quick editing does not allow pairs or multiples. You can set a quick_label for a multiple entry keyword, but the quick edit will only update the first one. If the user changes the one in the quick edit, only that one will be preserved. Pairs will not work in the quick edit box.

refresh Unused and ignored.

This used to indicate that a field keyword update should trigger a full page refresh. There is now javascript support to update the DOM no matter what happens and it should stay that way. Temptation to set this flag indicates a lack of javascript courage.

urgency Indicates how useful the keyword is. Most have urgency 0, they show up white on the screen. tentmaker currently understands these urgency values:



  value  screen color  implied meaning
  -----------------------------------------------------------------
    10   red           required by someone
     5   yellow        this or a related keyword is likely required
     3   green         many people use this regularly
     1   blue-green    many people use this at least occasionally
     0   white         less frequently used



Note that only values from the above list are understood by tentmaker. If you use other values, they will be treated as zero.

method_types This tells tentmaker which method types understand a keyword. It is a hash. They key are individual method types. The values are 1. There is one special key ’all’. If it has a true value, then the keyword is available to all methods regardless of type.
field_type Not yet used. Meant to tell tentmaker that a field keyword only applies to a certain html_form_type.
type Essentially the tentmaker html form element for the keyword. Note that literal keywords do not need to set this key (and if they do, it will be ignored). They always get a textarea for their input. For other keyword levels choose from these input types (in order by utility):
text This is the most common type. It tells tentmaker to use a text input box for the keyword.
boolean Indicates that the value is either 1 or 0 and tells tentmaker to use a checkbox for the keyword.
pair Indicates that the keyword admits either single values or pairs. A pair is two things separated by =>, like



    name => `email@example.com`



You want to use the pair_labels and pair_required keys if you use this type, trust me.

textarea Indicates that typical values for this keyword are large text blocks, so tentmaker should use a textarea for their input.
select Indicates that only certain values are legal so tentmaker users should pick them from a list. You must use the options key with this type. You might also want to use the multiple key.
deprecated Tells tentmaker not to show this keyword, which is usually an archaic spelling for a keyword.

    KEYWORD LEVELS

There are several levels in the parse tree where keywords may appear. These are the levels:
config Keywords in the bigtop level config block (where the backends are defined).
app Keywords at the top level of the bigtop app block.
app_literal The legal names of literal statements at the bigtop app block level.
table Keywords at the top level of table blocks.
field Keywords in field blocks (inside table blocks).
controller Keywords at the top level of controller blocks.
controller_literal The legal names of literal statements at the controller block level.
method Keywords in method blocks (inside controller blocks).
There are no other valid keyword locations in the current grammar. Adding new levels will require substantial change to the grammar, the parser, and all the backends. Thus, such changes are extremely unlikely (though some are in the back of my mind).

METHODS

There is only one method defined in this module. Use it as shown in the SYNOPSIS above.
get_docs_for Parameters:



    keyword_level
    list of keywords



Returns:

an array whose first element is the keyword_level and whose remaining elements are keyword hashes. This return is designed for direct passing to the add_valid_keywords method of Bigtop::Parser

get_full_doc_hash Parameters: none

Returns: the entire internal hash representation of all the keywords. This is useful for automated tools, like scripts/vimsyntax that builds the vim syntax file.

AUTHOR

Phil Crow <crow.phil@gmail.com>

COPYRIGHT and LICENSE

Copyright (C) 2006-7 by Phil Crow

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.

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 BIGTOP::KEYWORDS (3) 2016-04-03

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.