NAME

macro/editform - macros used for creating sql editing forms

SYNOPSIS

 <import src="macro/editform"/>

DESCRIPTION

*sigh* :( Not yet. 


Basically, 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 the PApp::HTML manpage. 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 SURL_EXEC or similar commands then these will be executed AFTER the form has been processed.

ef_sbegin [surl-arguments]
Similar to ef_begin, but uses PApp::sform to create the form. This disables ef_file widgets with most (if not all browsers).

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 convinience.

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

ef_edit [group]
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
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).

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.

ef_string fieldref, [length=20]
Output a text input field.

ef_password fieldref, [length=20]
Output a non-readable text input field.

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
Output a checkbox. fieldref is evaluated as a normal perl boolean.

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 user).

ef_selectbox $ref, 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.

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, relation [mysql-specific]
Similar to ef_relation, but 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, relation [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).

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 beign processed and call every END callback after all form arguments have been processed.

SEE ALSO

the PApp manpage

AUTHOR

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