NAME

HTML::FormEngine::Skin - FormEngines basic skin package

THE TEMPLATE SYSTEM

The parsing of the templates is done from left to right and from top to bottom!

Variables

Variables must have the following format:

<&[A-Z_]+&>

When the template is processed these directives are replaced by the variables value. If no value was defined, the default value is used, if even this is missing, they're just removed.

Variables, defined for a certain template, are valid for all subtemplates too!

Handler calls

You can call a handler out of a template and so replace the call directive with the handlers return value.

A handler name must match the follwing regular expression: #?[a-z_]+[a-z_0-9]+.

Optionally one can pass arguments to a handler. E.g. <&error ERROR_IN&> calls the error handler and passes to it ERROR_IN as argument. Mostly handlers are called without any arguments, e.g. <&value&>, which calls the value handler.

Handler calls can also be nested, e.g. like this: <&<&arg 1&> ERROR_IN&>. In that example first <&arg 1&> is called, the result is expected to be the name of a handler which is then called with ERROR_IN as argument.

The handlers are normally defined in Handler.pm, but you can also define them directly in the skin or wherever you think it fits best. Important is that they're registered correctly by the skin. Read HTML::FormEngine::Skin, HTML::FormEngine::SkinComplex and HTML::FormEngine::SkinClassic for more information.

The default handler is used for processing templates. So if you want to nest templates, you might use the templates name as a handler name and so call the default handler which will return the processed template code.

To distinguish handler calls from template calls a # is added infront of the name if a existing handler and not the default handler is to be called. This is only a convention and not necessary from the technical point of view.

For more information about handlers, see the HTML::FormEngine::Handler.

Loops

If you want to repeat a certain template fragment several times, you can use the following notation:

<~some lines of code~LOOPVARIABLES SEPERATED BY SPACE~>

If one or more loop variables are array references, the loop is repeated until the last loop variable as no element left. If all loop variables are scalars, the code is only printed once. If one ore more, but not all loop variables are scalars, these scalar variables have in every repetition the same value. If a loop variable is an array reference, but has no elements left, it has the NULL value in the following repetitions.

You can nest loops. For example the ClassicSkin uses this feature: If you use one dimensional arrays, the text fields are printed each on a single line, if you use two dimensional arrays, you can print several text fields on the same line.

Since FormEngine 1.0 you can also define loops without specifying loop variables. These loops are called global loops and they iterate over all used variables. That means as long as one of the variables used in the loops content has another element the loop is repeated. For example the row template of the ComplexSkin uses this feature.

<! !> Blocks

Code that is enclosed in '<! ... ! VARIABLENAMES !>', is only printed when all variables which are mentioned in VARIABLENAMES are defined (that means not empty). If you seperate the variable names by '|' instead of ' ', only one of these variables must be defined.

HTML::FormEngine::Skin

This class is abstract and not a complete skin class but its the basis of all skins. That means all methods defined here are available in all skins. In case you write your own skin you should also base it on this class if it makes sense. if not you should at least support the same methods.

Methods

new ([ $textdomain ])

This method is the constructor. It returns the skin object. Optionally you can pass it the path to your locale directory. By default this is /usr/share/locale. It is needed for gettext which translates the error messages and other stuff.

set_textdomain ( $textdomain )

Use this method to set the textdomain. Default is /usr/share/locale.

get_templ ([ $name ])

Returns the definition of the template with the given name.

If no name is given a hash reference containing all templates is returned.

set_templ ( HASHREF )

Overwrites all template definitions. Not recommended.

alter_templ ( HASHREF )

If you only want to add or overwrite some templates, call this method. You have to pass a reference to the hash which stores these templates.

get_default ( [$templ, $var] )

If no arguments specified it just returns all default settings in a hash reference.

If $templ is given it returns the default settings for template $templ.

If $var is also given it returns the default setting of the variable $var in template $templ.

set_default ( HASHREF )

By using this method, you completly reset the default values of the template variables. You have to pass a reference to the hash which stores the new settings. In most cases you better call "alter_default ( HASHREF )".

alter_default ( HASHREF )

Pass a hash reference to this method for adding or overwriting default values.

get_handler ([ $name ])

If $name is given it returns a reference to the handler having the given name.

If not it returns a hash reference containing all handlers.

set_handler ( HASHREF )

This method resets the handler settings. If you just want to add or overwrite a handler setting, use "alter_handler ( HASHREF )".

alter_handler ( HASHREF )

This method adds or overwrites template handlers. Have a look at Handler.pm for more information.

get_check ([ $name ])

If $name is given it returns a reference to the check function registered by the skin as $name.

If $name is not given it returns a hash reference containing all check functions.

set_check ( HASHREF )

This method resets the check settings. If you just want to add or overwrite a check function, use "alter_check ( HASHREF )".

alter_check ( HASHREF )

This method adds or overwrites check routines. Have a look at Checks.pm for more information.

is_hidden ( $templ )

Returns 1 (true) if the template with the given name is registered as hidden. Also see "set_hidden ( ARRAY )"

get_hidden

Returns an array containing the names of all templates which are registered as hidden. Also see "set_hidden ( ARRAY )".

set_hidden ( ARRAY )

With this method you can reset the list of templates which are handled as hidden-templates, that means which shouldn't use any visible space and for which it doesn't matter where they're placed in the form. By default this list only contains hidden as reference to the template called hidden.

Normally you'll prefer to only complete or redruce that list and therefore you'll call "alter_hidden ( ARRAY )" or "rm_hidden ( ARRAY )".

alter_hidden ( ARRAY )

See set_hidden.

rm_hidden ( ARRAY )

See "set_hidden ( ARRAY )".

get_confirm_skin

Returns the skin object which is used instead of this skin when the confirm form is created.

See HTML::FormEngine, function confirm ([ CONFIRMSG ]) for more information.

set_confirm_skin ( OBJECT )

Sets the confirm skin to the given skin object.