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?

WARNING

Form implementation in Agile Toolkit may change. Do not rely on internal structure of the form, they are explained here for to help you understand how form actually works.

Form workflow

A sample work-flow of a form is explained in the diagram on the right. Like all other objects, form is added to your page or anywhere else during init phase. At that moment, form is not yet producing any output nor will it try to load any input. It is just being configured.

If you do not call $form->isSubmitted(); then a default form::submitted() method will be called automatically if form was submitted by a user. An alternative to isSubmitted() method is calling onSubmit() which is used to set form's submission handler.

Form Rendering

Upon initialization form will clone several templates from it's main template. Those templates are then manipulated to create contents of the form. For example, fields are inserted into tag "Content" of the form, but they are using "form_line" template. If form layout is used, the form_line is not used and fields are inserted directly into the template.

Loadig Data

If you specify setSource() for the form along with ID, then method loadData() will be called before init and render phases which will load default data into the form. If you are using MVCForm, then the data is loaded when you call loadData() method. If you are executing isSubmitted() inside init(), then this will automatically loadData() before form submission is handled.

Error handling

Form relies on fields to perform their validation. Form will execute 'validate()' method for all it's children.

List of default features supported by Forms

Additionally functionality How Forms in Agile Toolkit are different with Forms in other Frameworks? Forms in Agile Toolkit are fully self-sufficient. Once you initialize the form, it will stand on the page on it's own, it will handle submission properly, it will automatically validate itself, encode received output and integrate with JavaScript. Other frameworks tend to focus primarily on form display

Forms are also designed for flexibility and with minimalism in mind. As developer you might be putting dozen of forms on your page and you would want them to work quickly and without conflicts.

Finally — Fields in Agile Toolkit are designed to cover basic data types. Additional input elements, such as sliders, can be created through progressive enhancement, where a numeric field is transformed into slider through JavaScript.

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)

Forms in Agile Toolkit can be integrated with Models. This way you will need to define field once for the model, then model will take care of necessary calls to MVCForm->addField().

Even when you are using form with Model, you still can add some additional fields manually as explained below.

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

gui/form#example1

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.

gui/form#example2

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.

gui/form#example3

Common questions answered about forms

I want to change HTML/Layout of the form!

Usually changing HTML of the form is bad idea. Forms ought to be consistent throughout your application. You might want to create a couple of form styles through your CSS to position fields, labels and hints.

If you need a more customized layout of your form, you can define a form layout. This allow to specify HTML for the form with placeholder for each field. This technique is described in later section.

Agile Toolkit does not offer any more-advanced form layout beyond what's normally possible through CSS.

What about file uploads? Agile Toolkit have a built-in support for file uploads using iframe (alternatively — flash) approach. This means that files are uploaded while you completing entering data into your form. Is there way to re-order fields in the form, after they are defined? Yes. See class "Order", which can be used for ordering fields sequence too