NAME

macro/editform - macros used for creating html forms

SYNOPSIS

 use PApp::EditForm;

DESCRIPTION

This package lets you create very powerful html forms.

Unless noted otherwise, all the functions creating input elements accept an optional additional argument which must be a hashref with additional attribute => value pairs to use in the resulting element (see the similar functions in PApp::HTML. The name attribute can optionally be overriden.

ef_mbegin [surl-arguments]

Start an editform. This directive outputs the <form> header (using PApp::multipart_form). The arguments are treated exactly like PApp::surl arguments. If it contains callbacks or similar commands, then these will be executed AFTER the form has been processed.

If, inside ef_begin/ef_end, another form is embedded, the outside form will automatically be upgraded (sbegin < cbegin < mbegin) to the most powerful form required by the forms and the nested forms are integrated into the surrounding form.

Please note that this doesn't work when you change the module, as only the outside ef_begin call will have the module name honoured, so always use a ef_submit to do this, or things will go very wrong.

NOTE: editform does not currently check wether a nested form specifies a module name. Behaviour in this case is undefined, and will most likely result in an obscure error from surl.

ef_sbegin [surl-arguments]

Similar to ef_mbegin, but uses PApp::sform to create the form.

ef_cbegin [surl-arguments]

Similar to ef_sbegin, but uses PApp::cform to create the form.

ef_begin [surl-arguments]

Identical to ef_cbegin, just for your convenience, as this is the form most often used.

ef_end

Ends the editform. This adds the closing </form> tag.

ef_edit [group] [DEPRECATED]

Returns wether the global edit-mode is active (i.e. if $S{ef_edit} is true). If the argument group is given, additionally check for the stated access right.

ef_may_edit [DEPRECATED]

Display a link that activates or de-activates global edit-mode (see ef_edit).

ef_submit [\%attrs,] $value [, surl-args...]

Output a submit button. If $value is undef or omitted, __"Save Changes" is used. The rest of the arguments is interpreted in exactly the same way as the arguments to PApp::surl, with one exception: if no destination module is given, the module destination from the ef_begin macro is used instead of overwriting the destination with the module (as surl usually does).

The surl-args are interpreted just before callbacks specified via ef_cb_end (but code references are still executed afterwards unless SURL_EXEC_IMMED is used).

ef_reset [\%attrs,] [$value]

Output a reset button. If $value is omitted, __"Restore Values" is used.

$name = ef_field fieldref [, name]

This rarely used function does not output an element itself but rather registers a field name within the editform. If the name is omitted it returns a newly generated name. You are responsible for creating an input element with the given name. Since it doesn't generate an HTML element it will of course not accept an \%attrs hash.

This can be used to implement custom input elements:

 my $name = ef_field \$self->{value};
 echo tag "input", { name => $name };

$name = ef_mutli_field fieldref [, name]

Same as ef_field but creates a field that allows multiple selections, in case you want to create a selectbox.

ef_string fieldref, [length=20]

Output a text input field.

ef_password fieldref, [length=20, [display]]

Output a non-readable text input field. To ensure that it is not readable, a display string will be used as value (the reference won't be read), and the field will be assigned only when the submitted string is non-empty and different to the display string.

The default display string is the empty string. Whatever you chose for the display string, it cannot be entered as a valid password (spaces are a good choice).

ef_text fieldref, width, [height]

Output a textarea tag with the given width (if height is omitted ef_text tries to be intelligent).

ef_checkbox fieldref[, bitmask]

Output a checkbox. If bitmask is missing, fieldref is evaluated as a normal perl boolean. Otherwise, the bitmask is used to set or clear the given bit in the fieldref.

ef_radio fieldref, value

Output a single radiobox that stores, when checked and submitted, "value" in fieldref. Be careful to use the same fieldref for all radioboxes or overwrite the name manually. fieldref is compared to "value" using eq.

ef_button fieldref

Output an input button element.

ef_hidden fieldref

Output a field of type "hidden" (see also ef_constant for a way to specify constants that cannot be altered by the client, as ef_hidden cannot guarentee this).

ef_selectbox fieldref, values...

Creates an selectbox for the given values. If $$ref evaluates to an array-ref, a multiple-select selectbox is created, otherwise a simple single-select box is used. values... can be as many value, description pairs as you like.

Beginning with version 0.143 of PApp, ef_selectbox (and other functions that use it, like ef_relation) don't send the key values to the client, but instead enumerate them and check wether submitted values are in range. This has two consequences: first, the client can only submit valid keys, and second, keys can be complex perl objects (such as undef ;), where they could only be strings earlier. Only arrayrefs in single-select boxes need to be treated differently as they will be wrongly interpreted as multiselects.

Equality of key values (used to find the currently "active" selection) is done by string comparison after stringifying the keys.

ef_relation fieldref, relation, [key => value]...

Output relation, e.g. an selectbox with values from a sql table. relation is an arrayref containing a string (and optionally arguments) for a select statement that must output key => value pairs. The values will be used as display labels in an selectbox and the corresponding key will be stored in the result field. Examples:

  ef_relation \$field, ["id, name from manufacturer order by 2"];
  ef_relation \$field, ["game_number, game_name 
                         from games where game_name like ?", "A%"];

Additional key => value pairs can be appended and will be used.

ef_set fieldref, [ table => "column" ] [mysql-specific]

Similar to ef_relation, but is based on the SQL SET type, i.e. multiple selections are possible. The field value must be of type "arrayref" for this to work. Example:

  ef_set \$field, [game => "categories"];

ef_enum fieldref, [ table => "column" ] [mysql-specific]

Similar to ef_set, but is based on the ENUM type in sql.

  ef_set \$field, [game => "type"];

ef_file destination-path[, source-path]

Output a file upload box. The file (if submitted) will be stored as destination-path. If destination-path is a coderef it will be executed like this:

   $res = $callback->($fh, $name, $ct, $cta, $cd);

(see PApp::parse_multipart_form, which uses the exact same parameters). The return value can be undefined, in which case the file will be skipped, a normal string which will be treated as a path to store the file to or something else, which will be used as a file-handle.

If a destination path is given, the file will be replaced atomically (by first writing a file with a prepended "~" and renaming (success case) or unlinking it).

Although a source path can be given, most browsers will ignore it. Some will display it, but not use it, so it's a rather useless feature.

ef_file automatically upgrades the surrounding form to a multipart form.

ef_constant fieldref, constant

Set the field to the given constant. This is useful when creating a database row and some of the fields need to be set to a constant value. The user cannot change this value in any way. Since this function doesn't output an html tag it doesn't make sense to prepend an initial hashref with additonal name => value pairs.

ef_cb_begin coderef

ef_cb_end coderef

Add a callback the is to be called at BEGINing or END of result processing, i.e. call every BEGIN callback before the form results are being processed and call every END callback after all form arguments have been processed (except submit buttons, which are processed after ef_cb_end callbacks). All callbacks are executed in the order they were registered (first in, first out).

ef_form_name

This function adds a unique name="id" attribute to the opening form tag and returns the id value to the caller. You can call it as often as you like. If this function isn't called, no name attribute will be created.

SEE ALSO

PApp.

AUTHOR

 Marc Lehmann <schmorp@schmorp.de>
 http://www.goof.com/pcg/marc/