NAME

HTML::FormEngine::Handler - FormEngine template handler

HANDLERS

default

The default handler is called if the named handler doesn't exist.

With help of the default handler one can nest templates. It expects the name, with which it was called, to be the name of an template. It then reads in this template and processes it. The resulting code is returned.

checked

This handler is used in the select, radio, check and similar templates.

The first argument defines the value, which should be returned if a certain option was submitted. By default this is 'checked'.

The second argument defines the name of the variable in which the option values are stored (default: OPT_VAL).

The third argument defines the name of the variable which defines the field name (default: NAME).

..or if you want to know it more exactly:

The first argument is returned if the field was selected. If this argument is not defined, checked is returned. If the field wasn't selected, an empty string is returned.

The second argument is the name of the variable in which the value of the field is defined which is submitted if the field was selected. By default the value of this argument is OPT_VAL.

The third argument contains the name of the variable in which the name of the field is stored. With the help of this variable the submitted value of the field is read in to be compared with the value which the field should have if it was selected. So the handler can determine whether the field was selected or not. By default this argument is NAME.

Normally the only important argument is the first one. The others can be important if you want to change variable names.

value

This handler returns the value of the field.

The first argument defines the value which should be returned if the value is empty. By default this is undef.

If the second argument is true (1), the returned value will be returned again next time the handler is called for this field name.

The third argument is used to tell the handler the name of the variable in which the field name is stored. By default this is NAME.

The fourth argument should be set to the name of the variable which contains the fields value. By default this is VALUE.

If the form wasn't submitted, the fields default value is returned.

error, error_in, error_check

The first argument sets the name of the variable in which the error checks are set. By default this is ERROR.

The second argument sets the name of the variable in which the fields name is stored. By default this is NAME.

The third argument sets the name of the variable which contains the fields value. By default this is VALUE but if error_check was used as handler name the default is OPT_VAL.

If the last argument is set to true (1) no checking will be done, that means that also no error can be returned. This can only be usefull for debugging.

The handler calls the defined error checks until an error message is returned or all checks were called. If it retrieves an error message it returns this message or the message given by the [checkmethod, errormessage, arg1, ... argn] notation, else NULL is returned.

gettext

The arguments given to this handler, are passed through gettext and then joined together with a spacing blank inbetween. The resulting string is returned.

gettext_var

You can pass variable names to this handler. The values of those variables are then pushed through gettext and the resulting strings are glued together with a blank inbetween.

label

This handler gets the id, title and accesskey value and uses this informations to create a (X)HTML <label> tag which is then returned.

The first argument should be set to the name of the variable which provides the fields title, by default this is TITLE.

The seconds argument default is ID. It should be always set to the variable which contains the fields id.

The third argument is used to try to get an accesskey for the field. Normally the variable ACCESSKEY is expected to provide such, if you prefer to use another variable please give its name here.

decide

Expects a list of variable names, it then returns the content of the first variable in the list which is not empty.

readonly

Expects the name of the variable which says whether the field should be set readonly or not. By default this is READONLY. readonly="readonly" is returned if that variable is set to 1 (true).

multiple

Works like readonly but multiple="multiple" is returned if MULTIPLE is true.

confirm_check_prepare

This handler is a confirm handler. It sets the variables OPTION and OPT_VAL to the list of submitted values resp. their visible names. This is usefull because like that only the really submitted values and options are printed when the template iterates over OPTION and/or OPT_VAL.

With the first argument you can set how many options/values you want to have per line when iterating. By default this is 2. Internally it just configurs how many elements every array should have.

The second argument is by default OPTION and should always be set to the name of the variable which provides the option list.

The third argument configures which variable should be read in to get the list of submitted values. By default this is OPT_VAL.

The fourth argument should be set to the right variable name if the variable which contains the fields name is not NAME (normally it is NAME).

seperate

First of all: The handler doesn't do anything if the set_seperate method was not called with a true value!

If set_seperate was called with a true value, this handler returns a seperation-field if the fieldname changes while iterating or if a template came to its end. Of course that only works when used in the right way in the templates.

The seperation-field is important because it controlls which values of a certain fieldname belong together and are thus packed into one subarray of the get_input result for that fieldname.

E.g.: you've a field called name which consists of two text-inputs, one for the first- and one for the lastname. If you now call get_input('name') it'll return: [firstname,lastname]. So far no problem. The problem comes if you use this name field twice e.g. because you want to get the data of 2 persons in one form. Now FormEngine normally would think that all four belong together: [firstname,lastname,firstname,lastname] but with the help of the seperation field which will automatically be inserted inbetween, it knows that the following is to be expected: [[firstname,lastname],[firstname,lastname]]. So far that isn't so important, but it really gets important for the radio,select and checkbox fields, because here FormEngine must know which values belong to which group and so on.

One might think: why do people not just use diffrent names? Well, i would say it is much more easier to define and also much more easy to evaluate the return value if fields who semanticlly belong together have the same name. If you would give the fields for each person its own name like name1, name2 ... it'll be not so nice to call get_value() for each person especially if the count of persons is flexible. So its much nicer to just call get_value(name) and then to know that each subarray represents one person.

The first argument is attached to the seperation-field-code. If the second argument is set to true (1) the sepeartion-field-code will be returned in any case (if set_seperate was called with a true value). The third argument is by default NAME and should always be set to the variable which contains the fields name.

encentities

This handler expects a variable name. It then fetches the variables contents and passes it through encode_entities so that all HTML entities are encoded. The resulting string is returned.

save_to_global

The handlers first argument can be any template expression (like <&NAME&> or <&value ,1&>), the second argument is by default saved and should always be set to a string which is not yet used as variable name anywhere in the template (at least it normally will make most sense if it is not used anywhere, in some cases might be usefull to use an existing name).

The handler will then read in the value of the expression given as first argument and will save it to the variable given as second argument but as a global variable, that means that value will then be available in every template if the variable is not overwritten by a local variable.

This handler is especially usefull in association with the fmatch check method.

not_null

The first argument is by default ERROR and should always be set to the name of the variable which defines the error checks.

The second argument is returned if the list of error checks contains the not_null check, which means that the field mustn't be empty. What is to be returned by default is setted by the skin, normally it is the empty string (no mark). A good value would be e.g. *. See HTML::FormEngine::Skin on how to modify the default (set_not_null_string).

This handler is used to automatically mark fields which have to be filled out.

html2text

This handler expects a variable name as argument, it then fetches the value of the variable and passes it through HTML::Entities::decode_entities before returning it. decode_entities turns HTML entities like < in their corresponding plain-text character.

arg

When calling a template you can pass arguments to it like this: <&template arg0,arg1...,argn&>

In the template you then use this handler to fetch the passed arguments. An example: <&#arg 1&>. This will return arg1.

WRITING A HANDLER

Design

In general, a handler has the following structure:

   sub myhandler {
     my($self,$callname,@args) = @_;
     # ... some code ... #
     return $res;
   }

$self contains a reference to the FormEngine object.

$callname contains the name or synonym which was used to call the handler. So it is possible to use the same handler for several, similar jobs.

@args contains the arguments which were passed to the handler (see Skin.pm).

Install

Read HTML::FormEngine::Skin on how to make your handlers available. To hardcode them into the skin edit its source code, also read about the other skin packages.

cpanm HTML::FormEngine

perl -MCPAN -e shell
install HTML::FormEngine