Jet\Form

Overview of constants

HTTP form submission methods

Constanta Meaning of
Form::METHOD_POST The form will be sent by POST method - default method
Form::METHOD_GET The form will be sent using the GET method

Types of form coding

Constanta Meaning of
Form::ENCTYPE_URL_ENCODED application/x-www-form-urlencoded
Form::ENCTYPE_FORM_DATA multipart/form-data
Form::ENCTYPE_TEXT_PLAIN text/plain

Overview of methods

General

General methods are mainly related to form definition.

Method Meaning of
public __construct(
string $name,
Form_Field[] $fields,
string $method=Form::METHOD_POST
) : 		Parameters:
  • $name
    Name of form.
  • $fields
    Form fields.
  • $method
    The HTTP method by which the form will be sent.
public setName(
string $name
) : void		 Allows you to change the form name after creation.
public getName(
) : string		 Returns the name of the form.
public getId(
) : string		 Returns the form ID specified for JavaScript and CSS.
public setMethod(
string $method
) : void		 Allows to change the HTTP method by which the form will be sent (values: Form::METHOD_POST, or Form::METHOD_GET)
public getMethod(
) : string		 Returns the HTTP method by which the form will be sent.
public setEnctype(
string $enctype
) : void		 Sets the form encoding. Important especially for forms with file uploads.
Beware! In practice, there is actually no need to use the extra method, because the Jet\Form_Field_File and Jet\Form_Field_FileImage fields set the form encoding automatically.
public getEnctype(
) : string		 Returns the set form encoding.
public setIsReadonly(
) : void		 Switches the form to read-only mode. This way the form fields are rendered and it is not even possible to capture and process the form.
public getIsReadonly(
) : bool		 Indicates whether the form is in read-only mode.
public setAction(
string $action
) : void		 Sets the form action. That is, the URL to which the form will be sent.
public getAction(
) : string		 Returns sets the form action. That is, the URL to which the form will be sent.
public setTarget(
string $target
) : void		 Sets the form target (e.g. _blank, etc.)
public getTarget(
) : string		 Returns the set form target (e.g. _blank, etc.)
public setAcceptCharset(
string $accept_charset
) : void		 Sets the accept-charset attribute.
public getAcceptCharset(
) : string		 Returns the set value of the accept-charset attribute.
public setNovalidate(
bool $novalidate
) : void		 Suppresses (or re-enables) form validation already on the browser side - novalidate attribute.
public getNovalidate(
) : bool|null		 Indicates whether or not form validation is already suppressed on the browser side - attribute novalidate.
public setAutocomplete(
bool $autocomplete
) : void		 Suppresses (or re-enables) browser-side form autocomplete - autocomplete attribute.
public getAutocomplete(
) : bool		 Indicates whether or not the form autocomplete is suppressed on the browser side - attribute autocomplete.
public setSentKey(
string $sent_key
) : void		 It allows to change the name of the hidden field indicating the submission of the currently submitted form only for a specific form - for one of its instances.

The name of this field for all forms can be changed using system configuration SysConf_Jet_Form.
public getSentKey(
) : string		 Returns the name of the hidden field indicating the submission of the current form, valid for the specific form.
public enableCSRFProtection(
) : void		 Enables CSRF form protection - automatically inserts the token field into the form.
public getCSRFTokenField(
) : Form_Field|null		 Returns the CSRF token field - if the form contains such a field.

Working with form fields

Working with fields is also primarily related to form definition.

Method Meaning of
public setFields(
Form_Field[] $fields
) : void		 Sets all fields at once. This means that if the form already had some fields before calling this method, they are removed and the fields whose list is the parameter of this method are added.
public getFields(
bool $as_multidimensional_array=false
) : Form_Field[]		 Returns a list of all the fields the form has. If the $as_multidimensional_array parameter is false, then a regular list is returned.

However, in the chapter on form definition, we noted that form elements can be arranged in a multidimensional array, and a path name is used for this arrangement.

If the parameter is true, then this is what is taken into account and the normal list of fields is no longer returned, but the fields are arranged into an N dimensional array.

This means that a field named:
/content/cs_CZ/title
will be in the returned list of fields here:
$fields['content']['cs_CZ']['title'].
public getSubFormPrefixes(
): array		 A form can be generated by piecing together several forms from several entities - from a rule with a main entity and its subentities. A typical example is localized content, where the localizations are instances of the subentity and the keys of these subentities represent the localizations.

To facilitate the display of forms in such a situation, there is this method that works as follows: <?= $form->field( 'date_time' ) ?>
        
<?php foreach( $form->getSubFormPrefixes('/localized') as $locale => $prefix ):
    $locale = new Locale($locale); ?>
    <legend><?= UI::flag( $locale ) ?> <?= $locale->getName() ?></legend>
    <?= $form->field( $prefix . 'title' ) ?>
    <?= $form->field( $prefix . 'annotation' ) ?>
    <?= $form->field( $prefix . 'text' ) ?>

<?php endforeach; ?>
public addField(
Form_Field $field
) : void		 Adds a new field to the form.
If a field with the same name already existed, it is replaced by the new field.
public getField(
string $name
) : Form_Field		 Returns an array of the given name.
Beware! If no such array exists, an exception is thrown.
public field(
string $name
) : Form_Field		 Alias of the getField method for a shorter notation of a frequently used call.
public removeField(
string $field_name
) : void		 Removes a field from the form.
public fieldExists(
string $name
) : bool		 Indicates whether the form has the given field.

General message forms

Very often we need to display a general information message for a form, for example after it has been submitted. It can be information about success or some general warning. The message can be displayed together with the form (see below), or used in other ways by your application logic.

Method Meaning of
public setCommonMessage(
string $message
) : void		 Sets the general form message for the user/client.
public getCommonMessage(
) : string		 Returns a general form message intended for the user/client.

Capture and validation

The following is an overview of methods related to data capture and validation.

Method Meaning of
public catchInput(
array|Data_Array|null $input_data=null,
bool $force_catch=false
) : bool		 Captures input data. By default from POST or GET, but it is not a requirement.

Parameters:
  • $input_data
    Input data. By default automatically POST or GET (depending on the HTTP method of the form), but it is possible to pass data as a parameter from any source. It is only necessary that this data is in the form of an array or instance of Data_Array.
  • $force_catch
    Force form capture even if there is no field/key on the input indicating the form was submitted.
public validate(
) : bool		 Performs a validation process on all fields and returns the result (true if no error was logged).
public setIsNotValid(
) : void		 Forcibly switches the form to the "not valid" state.
public getIsValid(
) : bool		 Indicates whether the form is valid. That is, whether the data has been captured and successfully passed validation.
public getValidationErrors(
) : Form_ValidationError[]		 Returns a list of all validation errors.

Working with captured data

These methods are related to working with and passing captured data.

Method Meaning of
public getValues(
) : array|bool		 If the form is captured and is valid, it returns the values of all fields in the form of an N-dimensional associated array.

If the form is not valid, it returns false.
public catchFieldValues(
) : bool		 If the form is captured and is valid, then it performs data capture using defined catchers.

If the form is not valid, it returns false.
public catch(
) : bool		 Performs the entire standard sequence. That is, capture input, validate and call catchers.

If any step fails, then return false.

Translation

Methods for translating forms are not to be missed.

Method Meaning of
public _(
string $phrase,
array $data=[]
) : string		 Translates the given text according to form settings. The method is primarily used for internal purposes.
public setDoNotTranslateTexts(
bool $do_not_translate_texts
) : void		 Enables/disables the "do not translate" flag. Thus, it is possible to completely disable the translation of a given form and not perform any translations.
public getDoNotTranslateTexts(
) : bool		 Returns the status of the "do not translate" flag.
public setCustomTranslatorDictionary(
null|string $custom_translator_dictionary
) : void		 Sets the optional translator dictionary. That is, different from the currently globally valid one.
public getCustomTranslatorDictionary(
) : null|string		 Returns the name of the optionally set translator dictionary.
public setCustomTranslatorLocale(
Locale|null $custom_translator_locale
) : void		 Sets an optional localization translator. That is, a different one than the one currently in effect globally.
public getCustomTranslatorLocale(
) : null|Locale		 Returns the optional localization of the translator.

Rendering

And finally, of course, don't miss the form display / rendering.

Method Meaning of
public renderer(
) : Form_Renderer_Form		 Access to the renderer of the beginning and end of the form, which can be used to further configure the parameters of the displayed form tag.
public start(
) : string		 It generates the HTML code for the beginning of the form.

Practically it is a shortcut of the $form->renderer()->start() call;
public end(
) : string		 It generates the HTML code of the end of the form.

Practically it is a shortcut of the $form->renderer()->end() call;
public message(
) : Form_Renderer_Form_Message		 Access to the renderer of the form's general message.

Practically, this is a shortcut to calling $form->renderer()->message();
Previous chapter
Definition of forms
Next chapter
Jet\Form_Field
GitHub