Form Quick Start

Form in Agile Toolkit will handle all aspects of the web form starting from form building, display, layout, submission, validation, database or model integration. In it's implementation, form relies on number of other object such as "Fields", "Buttons", "Templates", etc. Form inherits ability to manipulate Templates and JavaScript from AbstractView.

When you add form, it will automatically add support for js_widget (jQuery UI based widget which ensures that Form's data is sent safely over AJAX). Optionally forms may contain several Fieds, Buttons. Form can also have a "Layout" which defines a custom-look for it's body. Form may be associated with database and may rely on dsql() object.

What is under the hood?

List of default features supported by Forms
Additionally functionality
How Forms in Agile Toolkit are different with Forms in other Frameworks?

Adding Form

$p->add('Form');

Once you add the form as shown above, it will be automatically rendered by Agile Toolkit, it will have it's submit handler properly configured, it will perform necessary input data loading and validation. If you have multiple forms on the page, they will work independently without affecting each-other.

Agile Toolkit uses POST to submit all forms, which is enhanced through jQuery UI widget and is sent through an AJAX request. Form will also receive unique ID attribute.

Practically, use of Forms in Agile Toolkit require no set-up at all

Adding Fields

Model-integration (MVC)
$f=$p->add('Form');
$f->addField('line','name');

Form class defines a method addField(), which is used to create Form_Field objects. Typically this field object will contain markup for label, error and hint. Objects returned by addField() can be further interacted with. At least 2 arguments must be passed to addField first being a field type and second is field name

Label can be passed optionally as 3rd argument. If it's omitted then name is slightly converted to make a decent label (first_name is converted into 'First Name')

When looking at examples, the variable $f is often used to reference forms. We suggest to keep variable $f to always reference a form. If you need to build cross-linking between multiple form, use object properties instead.

Adding Buttons

$f=$p->add('Form');
$f->addField('line','name');
$f->addSubmit('Greet Me');

Form defines 2 methods — addSubmit() and addButton(). Both are relying on 'Button' class, so technically you can add button elsewhere and instruct it to submit your form

Handling form submission

Forms are always submitted to the same page where they were added on. This is default and recommended approach for any web software. By doing this, you can perform validations in the same place, in the same file reducing the risk of human error of not doing any logical validation before showing the form.

Additionally — form will be fully aware of the data it will be receiving, so instead of reading form data from $_POST, you can get the same data from the form object.

Validation

Agile Toolkit introduces only one automated validator — NotNull(). Additional validation can be achieved by adding eval'ed code or by doing manual checks on submission. All the validation is always performed on server-side. Since form submission is handled through AJAX, it performs same benefits as browser-side validation. If you have disabled form widget on purpose, page will be reloaded and form will keep it's entered values automatically.

For browser-side validation you can make use of some jQuery plugins such as formValidator.

Advanced field types

There are some fields which are bundled with Agile Toolkit core.

$f->addField('DatePicker','next_birthday')
    ->
setFieldHint('Enter the date when you will have your next birthday');

$f->addField('Slider','age')
    ->
setFieldHint('How old are you going to be on your next birthday?');

Re-using forms

class Form_Greeting extends Form {
    function 
init(){
        
parent::init();
        
$f=$this;

        
$f->addField('line','name');
        
$f->addSubmit('Greet Me');

        if(
$f->isSubmitted()){
            
$f->js()->univ()->alert('Email '.
                    
$f->get('email').' is valid')->execute();

        }
    }
}

Sample form and form design philosophy

Most PHP frameworks this is as far as functionality goes. Agile Toolkit brings a lot of powerful ways to enhance forms, which are explained in further sections.

Common questions answered about forms

I want to change HTML/Layout of the form!
What about file uploads?
Is there way to re-order fields in the form, after they are defined?