Upcoming: FormBuilder helper class

[WebBird]

I'm currently working on a FormBuilder class that I am going to use with all my WB modules.

Features:

* Create valid XHTML strict forms from config files or by calling the creator functions from your code
* Form validation (uses another class I am working on) - marks fields with invalid or missing data automatically
* Output form as table (default) or fieldset
* Option to overwrite the output templates (to create your own layout)
* CSS driven layout

Example:

(Examples extracted from an also upcoming WB module)

Config file:

Code:

<?php

if(!defined('WB_PATH')) { exit("Cannot access this file directly"); }

/*
    Backend options
*/

$FG_OPTS = array(
    'common' => array(
        array(
            'type'     => 'checkbox',
            'name'     => 'allow_registration',
            'on'       => 'yes',
            'allow'    => array( 'yes', NULL ),
        ),
        array(
            'type'     => 'checkbox',
            'name'     => 'allow_search',
            'on'       => 'yes',
            'allow'    => array( 'yes', NULL ),
        ),
        array(
            'type'  => 'text',
            'name'  => 'cat_overview_paging',
            'allow' => 'number'
        ),
        array(
            'type'  => 'text',
            'name'  => 'search_term_min_length',
            'allow' => 'number'
        ),
    )
);

$FG_LABELS = array(
    'DE' => array(
        'allow_registration' => array(
            'label'   => 'Registrierung erlauben',
            'invalid' => ''
        ),
        'allow_search'       => array(
            'label'   => 'Suche aktivieren',
            'invalid' => ''
        ),
        'cat_overview_paging'=> array(
            'label'   => '&Uuml;bersicht einer Kategorie: Anzahl Eintr&auml;ge pro Seite (0 f&uuml;r unbegrenzt)',
            'invalid' => 'Bitte eine Zahl angeben'
        ),
        'search_term_min_length'=> array(
            'label'   => 'Mindestl&auml;nge f&uuml;r Suchbegriffe',
            'invalid' => 'Bitte eine Zahl angeben'
        ),
    )
);

(Note: The array key 'common' is used to create a subheading: <legend> for fieldset layout and <th></th> for table based layout. Can be translated using I18n helper class.)

Create the form:

Code:

<?php

    $this->form              = new wbFormBuilder(
                                       array(
                                           'include' => dirname( __FILE__ ).'/config.inc.php',
                                           'varname' => 'FG_OPTS',
                                           'labels'  => 'FG_LABELS',
                                           'lang'    => 'DE',
                                           'asTable' => false
                                       )
                                   );

    $this->form->generateFromFile();

    echo $this->form->printForm(
        array(
            'header' => $this->lang->translate( 'Settings' ),
            'action' => $this->url.'?page_id='.$page_id,
            'name'   => 'settings',
        )
    );

Check the form data:

Code:

<?php

        if ( isset( $_POST['save'] ) ) {

            if ( $this->form->checkFormData( array('current' => $this->_current_settings) ) ) {

                $data = $this->form->getValid();

                foreach ( $data as $field => $value ) {
                    $values = "'" . implode( "', '", array( $page_id, $this->_current_section, $field, $value ) ) . "'";
                    $sql    = 'REPLACE INTO '.TABLE_PREFIX.'mod_profiles_settings VALUES ( '.$values.')';
                    $this->db->execute( $sql );
                }
                
                $this->_current_settings = $this->getSettings($page_id);
                
            }
            else {
            
                $info = $this->lang->translate(
                    'The settings could not be saved. Please correct the issues listed below.'
                );
                $infoclass = 'fbfail';
                
            }
            
        }

See screenshots below.

Please feel free to post your thoughts and suggestions. I will release this module bundled with some others (Validator, Template Engine) as an alpha within the next weeks. (I hope)

[WebBird]

Screenshots:

* Form generated from example above.
* Error message when inserting text into field cat_overview_paging (which allows numbers only)

[WebBird]

Most used methods:

generateFromFile( array( <options> ) )

Valid options:
'include' => file to include (string)
'current' => current values for fields to generate (array)


addElement( array( <options> ) )

Create a form element. Valid <options> see below.


insertElement( array( '[before|after]' => '<fieldname>', array( <options> ) )

Insert an element at given position. Element will be added to the end of the form if <fieldname> is not found.


replaceElement( '<fieldname>', array( <options> ) )

Replace element <fieldname>. Element will be added to the end of the form if <fieldname> is not found.


addButtons( array( <options> ) )

By default, two buttons are added automatically: Submit and Reset. You can define your own buttons (or translate the button labels) using this method.


printForm( array( <options> ) )

Print the form. Called after using generateFromFile() or the other methods above to populate the form.


checkFormData( array( <options> ) )

Check the form data. Returns 'true' if all data is valid, or 'false' if there were errors. Use in combination with printForm() to print the form with errors marked. (See screenshots)

[WebBird]

How to create a form element (<options> array)

Common:

Code:

<?php
array(
    'type'     => optional; valid values [radio|checkbox|select|text|password|legend]; default 'text',
    'name'     => optional; unique field name; randomly generated if omitted,
    'value'    => optional; value to fill the field with; default empty,
    'allow'    => predefined list (see below),
    'required' => [true|false],
    'equal_to' => fieldname to compare with (for password repetition etc.),
)

Checkboxes only:

Code:

<?php
array(
    'on' => optional; value to return if checkbox is checked; default 'on'
    'options' => optional array; allows to create a list of checkboxes with one call
)

Note: Use 'value' key to commit current value. The checkbox will be checked if 'value' is the same as 'on'.

Select (Dropdown) only:

Code:

<?php
array(
    'options' => array; list of options
)

Note: Use 'value' key to commit the option to pre-select.


Example for password field:

Code:

<?php
    array(
        'type'     => 'password',
        'name'     => 'item_password_repeat',
        'allow'    => 'password',
        'required' => true,
        'equal_to' => 'item_password',
    )

How to create a sub header ("legend")

There's a special legend() method you can use. Or add a 'legend element':

Code:

<?php

        $this->form->addElement(
            array(
                'type'    => 'legend',
                'content' => $this->lang->translate( 'Common' ),
            )
        );

How to fill a form element with values from a function

* In your config file, predefine the field like this:

Code:

    array(
        'type'    => 'select',
        'name'    => 'item_category',
        'allow'   => 'number'
    ),

* In your code, after using generateFromFile() to populate the form:

Code:

        $cat_opt    = array();
        $categories = $this->getCategories();
        foreach ( $categories as $cat ) {
            $cat_opt[ $cat['cat_id'] ] = $cat['cat_name'];
        }

        $this->form->replaceElement(
            'item_category',
            array(
                'type'    => 'select',
                'name'    => 'item_category',
                'label'   => $this->lang->translate( 'Category' ),
                'options' => $cat_opt,
                'value'   => $this->_current_category,
                'allow'   => 'number'
            )
        );

(Where getCategories() executes a database query to retrieve the data.)

[WebBird]

Predefined validation methods (for now)

'number'   => integer (no floating point numbers!)
'string'   => any string that doesn't have control characters (ASCII 0 - 31) - spaces allowed
'password' => formal valid password
'email'    => formal valid email address


Notes for 'password':

* 6 or more letters, digits, underscores and hyphens.
* The input must contain at least one upper case letter, one lower case letter and one digit.

Use 'string' instead to be less restrictive.

Notes for 'email':

* excluding addresses with consecutive dots such as john@aol...com
* Does not match email addresses using an IP address instead of a domain name
* Does not match email addresses on new-fangled top-level domains with more than 4 letters such as .museum

All validation is provided by an extra class that is required to use the FormBuilder class.

[mr-fan]

hi bianka,

is this something like this one from aldus??

http://www.websitebakers.com/pages/modules/various/x_cform.php

can it be used with/for modules or even just for building simple forms without formpages??

and what means this:

I will release this module bundled with some others (Validator, Template Engine)

template engine for the forms or a complete template engine like the x_fast_template_2 from aldus, too??

regards martin

[WebBird]

is this something like this one from aldus??

http://www.websitebakers.com/pages/modules/various/x_cform.php

Yes, "something like", but more advanced. I began with x_cform (and made some enhancements there I sent Aldus), but then, I decided to create my own class.

can it be used with/for modules or even just for building simple forms without formpages??

It is designed to work with any modules. With any PHP, in fact, also without WB.

template engine for the forms or a complete template engine like the x_fast_template_2 from aldus, too??

A complete enhanced template engine, not only for the FormBuilder. It will be completely compatible to x_fast_template, but with more features. (Conditional markups, loops etc.)

As above, I began using Aldus' module, but it seems to be easier to create my own instead of enhancing his code.

[Stefek]

A complete enhanced template engine, not only for the FormBuilder. It will be completely compatible to x_fast_template, but with more features. (Conditional markups, loops etc.)

Sounds Good, WebBird.

I am very interested into this.

I worked with x_fast_template lately and it is really cool for templating, but there are some missing Features in it.
Good Idea to make it compatible.

Kind regards,
Stefek

[WebBird]

I worked with x_fast_template lately and it is really cool for templating, but there are some missing Features in it.
Good Idea to make it compatible.

You may send me a PN to let me know which features are missing for you.

But, please, this is the thread for FormBuilder. (Maybe I should open one for the Templating...)

[Stefek]

You may send me a PN to let me know which features are missing for you.
But, please, this is the thread for FormBuilder.
(Maybe I should open one for the Templating...)

Hello WebBird,
yeah it was good if you do that.
I think it is of some interest.
Maybe you then could give a brief info on the current extra-features?

Kind Regards,
Stefek

[WebBird]

http://www.websitebaker2.org/forum/index.php/topic,15260.msg98163.html#msg98163

[WebBird]

I am working on the documentation: http://www.webbird.de/wblib/en