Download the PHP package / without Composer

Simplon/Forms

Simplon/Forms helps to validate data and, if needed, to build a form view with a couple of widgets by leveraging Semantic-UI library.

1. Quick example
   1.1 Fields
   1.2 Validation
   1.3 View
2. Fields
   2.1 General fields
   2.2 Fields with options
   2.3 Rules
   2.4 Filters
3. View
   3.1 Simple example
   3.2 Blocks & Rows
   3.3 Elements
4. Block fields cloning
   4.1 Building fields
   4.2 Building view
   4.3 Building templates
5. Settings
   5.1 Field required/optinal label
6. Examples

1. Quick example

1.1 Fields

In order to validate data we need to create at least one field which can hold any number of rules to define its validity. A field can also hold any number of filters which will be applied to the field value.

Some field examples

Pre-populating your fields

We can pre-poluate our fields with data we already have - not request data:

1.2 Validation

FormValidation is expecting at least one set of FormFields. Let's pick up the example from above with an additional name field. We set an empty array for our request data. You can take the value from any source as long as its organised as an array.

FormValidator::hasBeenSubmitted checks if our received data are empty or filled. In case we received data we can go ahead and run all applied rules over our defined fields by FormValidator::validate and FormValidator::isValid tells us if all fields passed their requirements.

In case of success we can collect all field values by FormFields::getAllData. Otherwise you can check for errors by collecting the error messages via FormValidator::getErrorMessages or by collecting all error fields FormValidator::getErrorFields. The latter also holds all error messages by field.

1.3 View

In order to render your fields we need to apply them to Elements. These elements can be applied to the FormView directly or to a FormBlock which renders our form automatically in a set structure. We will continue with our before defined fields:

We could set much more options but that should do it for now. Let's pass on our view to a template. For the following example we assume that we have access to the $formView variable. We simply pass on a form template to the FormView::render method and include all core assets:

We separate our main template from the actual form template so that we can automatically render the required <form></form> tags with all required attributes at the beginning and the end of the template. We also inject automatically the FormView instance as $formView variable.

Any validation errors would be rendered on top of the template. After this follows our defined block with the ID default. This statement will render both of your fields next to each other with equal spacing. At the end you can place your Submit element which comes in our example as an automatically set element. You can also define this field yourself.

2. Fields

Fields are an abstraction of your data and are by design very generic. The goal was that fields should work with incoming API requests as well as with the usual html forms.

2.1. General fields

Most of the fields simply require one rule and a filter. These would be most commonly RequiredRule and the TrimFilter. The latter comes already by default. What you definitely need is a field-id which needs to be passed on with the constructor.

2.2. Fields with options

You might have fields which accept only a given set of values. In that case you can add options as meta data to the field. Classic example would be an address field or a country selection.

2.3. Rules

There are a couple of common rules which we used so for all our form requirements. You can find them below. However, if you are in need to have some more rules it's very easy to add/extend rules. Just take a look at one of the existing rules to see how to do that.

RequiredRule

Mark a field to be required.

UrlRule

Make sure that the field's value validates against a URL format.

EmailRule

Make sure that the field's value validates against an email format.

ExactLengthRule

Make sure that the field's value validates against an exact length.

MaxLengthRule

Make sure that the field's value validates against a maximum length.

MinLengthRule

Make sure that the field's value validates against a minimum length.

CallbackRule

Sometimes you need to run a check against the database or maybe to a cross-reference with some other fields. In that case this rule comes in handy. It lets you handle the validation and requires only the return of a boolean value to determine if the value is valid. We use it e.g. to make sure that the given email address is unique before we accept a new user registration.

First parameter takes the callback and the second parameter is an optional error message.

IfFilledRule

Sometimes we have optional fields which should only validate against a set of rules if they have a value. For this case we have this rule in place.

FieldDependencyRule

This rules lets you add rules to another field. Imagine that your actual field is an optional one and only if filled you want to validate some other fields.

WithinOptionsRule

Semantic-UI's drop-down field saves its selection in a hidden field. For multi-selection fields the selected values will be separated by a comma within that hidden field. To make sure that the submitted values still match your given options we can make use of WithinOptionsRule.

2.4. Filters

A filter is run over your submitted field values. For instance, to make sure that a textfield does not include any white space characters you can add TrimFilter to your field and simplon\form will make sure that your field value is cleared before processed further. Below is a list available filters but as for the rules you are able to add your own filters. Just take a look at one of the filters. Lastly, filters are combinable.

CaseLowFilter

Transform the field value to all lower-case.

CaseTitleFilter

Uppercase the first character of each word in the field's value.

CaseUpperFilter

Uppercase the the complete field's value.

TrimFilter

Each field holds this filter by default. Strip whitespace (or other characters) from the beginning and end of the field's value.

You can override the default trimming characters by passing them through the filter's constructor:

Instead of overriding the default trimming characters you can simply add characters:

TrimLeftFilter

Same as for the TrimFilter but only for the left-side of the field's value.

TrimRightFilter

Same as for the TrimFilter but only for the right-side of the field's value.

XssFilter

Use this filter to avoid XSS. The filter will try to catch and remove all html-related elements which seem to appear in your field's value.

3. View

A view helps you to collect your fields in a structured way and to render them to display your form.

3.1. Simple example

For this example we would like to create a form for entering an email address. Remember that html structure is build on top of Semantic-UI's grid and widgets.

Code

Page template

Form template

3.2. Blocks & Rows

In the prior example we built our view by adding the email element directly to our view. Blocks and rows help us to automatically arrange our elements with ease.

Blocks

Blocks are directly added to your view and hold a unique ID which is needed to reference them later in your template. You can add as many block as you wish.

Rows

Rows are added to your blocks and hold your elements. A row structures your elements in columns. There is no row limit for your blocks. Let's continue the blocks example:

You can see that we are using autoColumns() for setting our element. This means that the element will take as much space as is available for this row. For instance if we would have set second element for this row both elements would take 50% of the row's width.

It is also possible to set a specific width for each element respectively to combine auto-width with a specific-width.

3.3. Elements

Most of the elements require a FormField in order to be build. The following elements come delivered with your simplon\form release. You can always build your own elements which should inherit the abstract Element class.

InputTextElement

This builds a single-line text field.

InputPasswordElement

This builds a single-line password field. This field inherits from InputTextElement.

InputHiddenElement

This builds a hidden field. This field inherits from InputTextElement.

TextareaElement

This builds a multi-line text field.

CheckboxElement

We use checkbox elements for fields which offer one or more options to choose from - but in general only a few options. It requires at least one option. If any option has been selected you will receive an array of the selected options.

Example for multiple values. We only need to add more options. Also, notice that it's sufficient to define a value for each our options. The value will be used for the label.

RadioElement

We use radio elements for fields which offer only a few options but where we require only one selection. Your selected option will be Note that it's sufficient to define a value for each our options. The value will be used for the label.

SubmitElement

This builds a submit button which can be added to your FormView. It does not require any field but you may set a button label and add css classes.

DropDownElement

We use drop-down elements for fields which offer one or more options to choose from. It requires at least one option. If any option has been selected you will receive it as a string within your request data. Multiple selections are passed on as string separated with commas.

Drop-down elements can either accept one- or multiple-selected options. We are also able to add new options on the fly. Further, we are able to filter through all options.

TimeListElement

This element renders a drop-down with time options in the given minute interval. This field inherits from DropDownElement.

DateListElement

This element renders a drop-down with date options starting from a given start date for a set number of days. This field inherits from DropDownElement.

DateCalendarElement

We can also implement a proper calendar which is build on top of a calendar extension for Semantic-UI. Here are a couple of the look & feel of this extension. We are also making use of momentjs for rendering the actual dates while respecting locale information.

Date/Time options: You can see that there is an option dateOnly() which limits the calendar to let the user only select a date. By default the user is asked for a date/time combination. Related options are:

• timeOnly()
• monthOnly()
• yearOnly()

Format options: Next to setDateFormat() there are also the following format options: setTimeFormat() and setDateTimeFormat().

Defining a range: It is also possible to two have two calendars being directly related so that the user can define a specific date range:

DropDownApiElement

This element enables you to send a search request against a defined API and to display its results. This can work with any API since handling the response is up to you. Out of the box we support Algolia place search and [Semantic-UI's API response handling]().

ImageUploadElement

This element handles the client side of an image upload for you.

Following a snippet which shows an example of an implementation of an ImageUploadElement.

The uploaded image will be provided as dataURI so it's up to you how you will process these data after the form has been successfully validated.

4. Block fields cloning

This feature gives the user the possibility to clone respectively remove field blocks dynamically. For instance, imagine you have to enter an unknown set of people addresses. In that case you have a set of core fields which can be cloned by a simple click so that you can enter a new address straight away until you are done entering all addresses.

4.1. Building fields

4.2 Building view

4.3 Building templates

Page template

Form template

5. Settings

5.1 Field required/optional label

Fields can be marked being required or optional - so either one of the both states depending on your preference. You will also have the possibility to override the default displayed words/characters e.g. to localise your form.

Toggle between required/optional

Override label texts

6. Examples

Coming soon