Overview.
Custom form fields facility allows you to manage user, listing, review, message and widget form fields via administrator panel.
It is possible to set field validation rules, predefine options for multi-choice fields, enable listing fields to be searchable.
You can control the field visibility by linking it to listing type products and categories. This option is available for listings, reviews and messages.
Field Name, Label, Description and Placeholder.
Field label is a descriptive word or phrase that appears to the left of the field.
Field name is usually a lower case alphanumeric representation of the label. No spaces or extra symbols are allowed. Use "acceptedcurrencies" for the label of "Accepted Currencies".
Field description is placed below the field and may include detailed description of the expected value or other field instructions.
Field placeholder appears as a short hint in the input field before user enters a value. Placeholder is supported by Email, Number, Phone, Price, Text, Textarea, Website URL and YouTube field types.
Field Types.
The following field types are supported:
| Checkbox | Lets user select one or more values of a predefined list of options. |
| Color | HEX color picker. |
| Date | A javascript-based locale-dependable date picker. |
| Datetime | Is similar to "Date" but includes time setting. |
| File | An advanced drag-and-drop implementation of the file upload form field. |
| Opening Hours | |
| HTML Textarea | An WYSIWYG text input. |
| Keywords | A comma separated keywords list. |
| Multiple Select | |
| Number | This field accepts integers and decimals. Transforms values according to the user localization. |
| Phone | |
| Price | Supports decimal values with two digits after the decimal point. |
| Radio | Is similar to the "Checkbox" field but allows one selection only. |
| Rating | A star rating picker. Accepts a range of 0 to 5 with the step of 0.5. |
| Dropdown / Select | |
| Separator | Is used to visually separate fields in the form. |
| Text | A single-line text input. |
| Textarea | A multi-line text input field. |
| Time | |
| Timezone | |
| Toggle | A two-state switch that can be enabled or disabled. |
| Website URL | |
| YouTube | The field accepts a YouTube video URL. |
Validation Rules.
One or several validation rules can be applied to any custom form field.
Some of the fields have a built-in value validation: Color, Date, Datetime, Email, Number, Phone, Price, Rating, Time, Timezone, Website URL, YouTube.
Most of the rule names are self-explanatory.
Validation Rules Compatibility.
| Field | Compatible Rules |
|---|---|
| Checkbox | Length, Maximum Length, Minimum Length, Required. |
| Color | Required. |
| Date | Required. |
| Datetime | Required. |
| File | Required File. |
| Banned Words, Length, Maximum Length, Minimum Length, Required. | |
| Opening Hours | |
| HTML Textarea | Banned Words, IP Address, Length, Maximum Length, Minimum Length, Required. |
| Keywords | Banned Words, Length, Maximum Length, Minimum Length, Required. |
| Multiple Select | Length, Maximum Length, Minimum Length, Required. |
| Number | Length, Maximum Length, Minimum Length, Maximum Numeric Value, Minimum Numeric Value, Required. |
| Phone | Banned Words, Length, Maximum Length, Minimum Length, Required. |
| Price | Length, Maximum Length, Minimum Length, Maximum Numeric Value, Minimum Numeric Value, Required. |
| Radio | Required. |
| Rating | Required. |
| Dropdown / Select | Required. |
| Separator | |
| Text | Banned Words, IP Address, Length, Maximum Length, Minimum Length, Maximum Numeric Value, Minimum Numeric Value, Required. |
| Textarea | Banned Words, IP Address, Length, Maximum Length, Minimum Length, Maximum Numeric Value, Minimum Numeric Value, Required. |
| Time | Required. |
| Timezone | Required. |
| Toggle | Required. |
| Website URL | Banned Words, Length, Maximum Length, Minimum Length, Required. |
| YouTube | Required. |
Please note that Length, Maximum and Minimum Length rules will control the number of characters for a text field and the number of selected values for a multi-choice field.
Validation Rule Parameters.
Some of the validation rules require one or multiple comma separated parameters:
| Rule | Parameter Type | Parameter Description |
|---|---|---|
| Length | Integer | The exact number of characters or selected choices required. E.g: 255 |
| Maximum Length | Integer | The maximum number of characters or selected choices allowed. E.g: 255 |
| Minimum Length | Integer | The minimum number of characters or selected choices allowed. E.g: 3 |
| Maximum Numeric Value | Integer | The maximum integer value allowed. E.g: 500 |
| Minimum Numeric Value | Integer | The minimum integer value allowed. E.g: 1 |
| Unique Value | Mixed | Performs a database table lookup to make sure the inserted value is unique. Requires at least 2 paramaters: a database table name that uses the standard script prefix and a table field name to check. Third parameter is available if you want to skip one record by its ID, e.g.: the following parameter will lookup the 'first_name' field in the 'users' table to make sure the name is unique: users,first_name. You can add an id to this parameter to skip the user record with id 1, e.g.: users,first_name,1 |
Banned Words may be edited under "Administrator - Settings - Settings - Other - Banned Words". Place one word or phrase per line.
Field Options.
Custom form fields of "Dropdown / Select", "Multiple Select", "Checkbox" and "Radio" types require a predefined list of options.
Each option requires a unique key. Usually option key is a lower case alphanumeric representation of the value. E.g: use "airconditioned" as a key for the value of "Air-conditioned".
System Form Fields.
There are some predefined form fields required for the script to function properly. Those fields can not be removed, limited or disabled but can be edited to change the field label and field position in the form.
Below is the list of system fields for different form types:
| Form Type | System Fields |
|---|---|
| User | First Name, Last Name, Email, Password, Address, Zip, Location, Latitude, Longitude, Map Zoom, Timezone |
| General Listing | Title, Slug, Summary, Description, Address, Zip, Location, Latitude, Longitude, Map Zoom, Meta Title, Meta Keywords, Meta Description, Timezone |
| Event Listing | General Listing + Event Start Date, Frequency, Interval, Weekdays, Weeks, Event Custom Dates, Event End Date, Allow RSVPs |
| Offer Listing | General Listing + Offer Start Date, Offer End Date, Item Price, Discount Type, Discount Value, Available Offers, Offer Terms and Conditions, Allow Redeeming |
| Review | Title, Review |
| Message | Subject, Message |
Searching Fields.
Listing form fields can be searchable and appear in the "Refine Filters" form on the listing search results page.
To make the field searchable you have to enable the "Searchable" option.
Depending on the field Search Type there are three possible search scenarios:
"Exact Value Match" - will look for the exact value match.
"Partial Value Match" - will look for partial matches.
"Range" - converts fields of "Price" and "Number" types into a numeric range field in the 'Refine Filters' form.
You can set the minumum and maximum value and the step.
Limiting Field Visibility.
"Show on Submit Form" and "Show on Update Form" options restrict the field to appear on submission or update form only.
The field visibility on the listing detailed page and the listing search results page is controlled by "Show on Template" and "Show on Search Results Template" options.