Download the PHP package simplon/form without Composer
On this page you can find all versions of the php package simplon/form. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Informations about the package form
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.
- Quick example
1.1 Fields
1.2 Validation
1.3 View - Fields
2.1 General fields
2.2 Fields with options
2.3 Rules
2.4 Filters - View
3.1 Simple example
3.2 Blocks & Rows
3.3 Elements - Block fields cloning
4.1 Building fields
4.2 Building view
4.3 Building templates - Settings
5.1 Field required/optinal label - 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
All versions of form with dependencies
simplon/phtml Version 0.1.*
fightbulc/moment Version 1.25.*
simplon/component_form Version 0.0.*
simplon/component_semanticui Version 0.0.*
ext-json Version *