ePages 6.10 - DE_EPAGES/Presentation/API/Form.pm

Package DE_EPAGES::Presentation::API::Form

This package provides functions for validating input data submitted by HTML forms.

Base
DE_EPAGES::WebInterface::API::Form
Example
my $Form = $Servlet->form;
my $hValues = $Form->form( $User, 'LoginData' );
$User->set( $hValues );
# read unchecked values
my @Quantities = $Servlet->form->value('Quantity');

# check each individual value
my $Index = 0;
foreach ( @Quantities ) {
    unless ( /^\d+$/ ) {
        $Form->addFormError( {
            Reason => 'NoInteger',
            Name => 'Quantity',
            Index => $Index,
            LoopName => 'BasketProducts',
            Form => 'Basket',
        } );
    }
    $Index++;
}

# die if an input error occured
$Form->executeFormError;

Functions

MandatoryForm
addFormError
checkValues
errors
executeFormError
existsFormError
field
form
formData
formErrors
formName
locale
mapFormError
new
object
resetFormErrors
setlocale

MandatoryForm

Returns TLE variables containging information about the form definition. They can be used to indicate required fields or accepted ranges.

Syntax
$hVars = MandatoryForm($hFormData);
Example
my $hFormData = $self->formData( LoadClassByObject('User', 'LoginData' )
$hVars = { %$hVars, %{ MandatoryForm( $hFormData ) } };
Input
$hFormData (ref.hash.hash.string)
format definition, see formData
Return
$hVars (ref.hash.string)
TLE variables, keys:
  • TYPE_xxx - type of data
  • MANDATORY_xxx - true if field is required
  • MIN_xxx - min length (string) min amount (integer,float)
  • MAX_xxx - max length (string) max amount (integer,float)
  • EXAMPLE_xxx - example (for regional dependent types)

addFormError

Adds a form error to the list of form errors. Use formErrors to get all errors that have been added.

Syntax
$self->addFormError($hFormError);
Input
$hFormError (ref.hash.string)
keys:
  • Reason - reason error code - string
  • Name - input name - string
  • LoopName - loop name (optional)- string
  • Index - index of error in loop (optional default=0)- integer
  • Form - form name (optional default=NoForm)- string

checkValues

Checks the form data and converts them from regional-specific formatting to the internal (Perl) representation using the given form field specifications.

Syntax
$hValues = $self->checkValues($Object, $hFormData, $skipExecuteFormError);
Example
my $hFormData = $Form->formData( $Object->class, 'SearchMask' );
my $hValues = $Form->checkValues( $Object, $hFormData );
Input
$Object (object)
form based on object
$hFormData (ref.hash)
from field specifications, see formData
$skipExecuteFormError (boolean)
skip "executeFormError" or not
Return
$hValues (ref.hash.string)
checked form values in internal representation

errors

The errors of form vars will be converted to accessable objects.

Syntax
$hVars = $self->errors;
Example
$Servlet->vars('FormError', 1);
$Servlet->vars('FormErrors', $self->form->errors);
#LOOP(#FormErrors.Errors)
  Reason: #Reason
  Name: #Name
  Value: #Value
  Index: #Index
  LoopName: #LoopName
  <br />
#ENDLOOP
#IF(#FormErrors.Reason.FORMAT_NOT_INTEGER) ... #ENDIF
Return
$hVars (ref.hash.string)
empty hash if no error else keys:
  • Errors - list of all form errors
    (keys: Reason, Name, Value, LoopName, Index)
    - ref.array.hash
  • Error - form errors by input filen name and loop index
    (keys: Reason, Name, Value, LoopName, Index)
    - ref.hash.hash.hash
  • Reasons - list of all form errors by reason. error code
    (keys: Reason, Errors, ErrorCount)
    - ref.array.hash
  • Reason - form errors by reason code
    (keys: Reason, Errors, ErrorCount)
    - ref.hash.hash
  • Form - form errors by form name
    (keys: Form, Reason, Error, ErrorCount)
    - ref.hash.hash

executeFormError

Throws an 'INVALID_FORM' Error if a form error exists. If $FormError is defined this error will be added and then executed.

Syntax
$self->executeFormError;
$self->executeFormError($FormError);
Input
$FormError (ref.hash.string)
(optional) keys:
  • Reason - reason error code - string
  • Index - index of error in loop (optional) - string
  • LoopName - loop name (optional) - string
  • Form - form name - string
  • Name - input name - string

existsFormError

Returns true if a form error has been added by addFormError.

Syntax
$Exists = $self->existsFormError;
Return
$Exists (boolean)
true if an error exists

field

Tests form data and converts from external to internal representation.

Syntax
$Value = $self->field($Object, $FormValue, $hFormData);
Example
my $Value = $Servlet->form->field($Shop, $QuantityData, { 'Type'=>'reg_integer', 'Name'=>$InputName });
Input
$Object (object)
form based on object
$FormValue (string)
value of input field in form
$hFieldData (ref.hash)
field data keys:
  • Name
  • Type
  • Mandatory
  • MinValue
  • MaxValue
  • LoopName
  • Index
  • CurrencyID
Return
$Value (integer,float,DateTime,string)
unformatted value

form

Reads form field specifications from the database using the object class and form name. Then checks the form data and converts them to the internal representation using checkValues.

Syntax
$hValues = $self->form($Object, $FormName, $skipExecuteFormError);
Example
my $hValues = $Servlet->form->form($Shop, 'SearchMask');
my $hValues = $Servlet->form->form($Basket, 'Update');
Input
$Object (object)
form based on object
$FormName (string)
name of form (used only for error parameter)
$skipExecuteFormError (boolean)
skip "executeFormError" or not
Return
$hValues (ref.hash.string)
checked form values in native Perl format (possible copy of
input $rIn)

formData

Gets form field defininitions from database.

Syntax
$hFormData = $self->formData( $ObjectClass, $FormName )
Example
$hFormData = $self->formData( LoadClassByAlias('User'), 'LoginData' )
Input
$ObjectClass (object)
class
$FormName (string)
form name
Return
$hFormData (ref.hash.hash)
hash with form field definitions, keys are form field names,
values are hashes containing field definition,
see formField

formErrors

Returns all form errors that were added previously by addFormError.

Syntax
$aFormErrors = $self->formErrors;
Return
$aFormError (ref.array.hash)
list of form errors. The list elements are hash references
that were passed to addFormError

formName

Returns the name of the current form.

Syntax
$FormName = $self->formName;
Return
$FormName (string)
form name

locale

Returns the locale that is used for input validation of numbers and date/time values.

Syntax
$Locale = $self->locale;
Return
$Locale (string)
locale string, e.g. 'en_US'

mapFormError

Builds form error from standard error.

Syntax
$self->mapFormError($hFieldData, $Error);
Input
$hFieldData (string)
data for input field ()
$Error (object)
error of parameter see DE_EPAGES::Core::API::Error::GetError

new

Creates a form object on a HTTP::Request object.

Syntax
$Form = DE_EPAGES::Presentation::API::Form->new($HttpRequest);
Input
$HttpRequest (object)
HTTP::Request object
Return
$Form (object)
form

object

Returns the object that this form is based on. This object is used to determine format and curreny settings if they are not available otherwise.

Syntax
$Object = $self->object;
Return
$Object (object)
object

resetFormErrors

Resets the collected form errors.

Syntax
$self->resetFormErrors;

setlocale

Sets the locale that is used for input validation of numbers and date/time values.

Syntax
$self->setlocale($Locale);
Input
$Locale (string)
locale string, e.g. 'en_US'