Calculator configuration: Form fields
The form fields will be the user inputs you will show at your front-end form. Type a name for your new field and click 'Add new field' button to add a new field to your calculator. It will show at the left column menu where you can select any field to complete its internal configuration.
Each field will have a name, this is a free text so you can identify the field, a 'variable', which is an internal named used for the calculations, excel mappings, etc and that must follow naming conventions (A valid variable name starts with a letter or underscore, followed by any number of letters, numbers, or underscores), and a type, depending on the kind of input you need to recover from your users. These are the types available:
- Option List
- Multiple Option List
- Linked List
- Linked List SQL
- Yes / No
- Text Autocompleter
- Upload File
Each type will render a different field input at your front end form:
Shows a default input text restricted only to numbers, performing validations about decimal places allowed, and maximum/minimum values allowed.
Shows a date input followed by a calendar chooser. It will validate date format against the format set at Preferences. (See preferences configuration)
- Option List:
Combo box with a single option to choose. You can manually set the options available adding values to the multivalues section, use a sql query to recover dynamic values from your database, or load a csv text to create the options.
When using SQL query to recover values, you can use #_ to replace your database tables preffix, so your query will still be valid when exporting calculators from one site to another or changing the preffix.
For each option you must enter two values, it's name (the option label user will see at the dropdown), and the value of the option (the value you want to recover to use at calculations).
When option 1 is selected, the variable at code section $mainl will have a value equal to “T1”
You can also recover the label selected at the combobox, another variable named $xxx_name (where xxx is the variable name of the list) is available with the label selected, for this example at the code we can get $mainl_name to get the label “Option 1”
- Multiple option:
This field type will create as many checkboxes as options included. You must configure the options as you do with a option list, with a label and a value for each option available.
To recover options selected, you will receive a list of options checked, in form of array type. So you should access the array using a loop or counter, if we named our multiple field as 'multiple', then we will have at $multiple the first value selected, at $multiple the second option selected, and so on.
We can find out how many options are selected using php function count count($multiple) to have the number of checkboxes checked.
- Linked list:
This is an advanced input type. It is an special kind of dropdown list, that filters its options depending on a previous option list selection. To configure the linked list you must follow a naming convention, as follows:
You must name its variable like xxx_linked, where xxx is the name of the main list we want this linked list to be dependant on. Let's assume we had already a default option list named 'mainl', so this one will be named as mainl_linked.
Its options will be filtered according with the value selected from the first list. Each option must have a value named as zzz_yyy where zzz is the value of the first list which enables this option, and yyy is the unique value you want to set for the option.
With this configuration, 'SubOpt 1,1' and 'SubOpt1,2' options will only be available when 'Option 1' is selected from the first list. 'Option 3' will only be available when 'Option 3' of the first list is selected.
Following same structure than default option lists, you can recover the label selected at this linked list using $xxx_linked_name ($mainl_linked_name for this example)
When using linked lists, the value recovered is the one set at 'value' of each option, so you will get the whole string “zzz_yyy” (“T1_1”) when using $mainl_linked variable. In order to split the value from the main list option and get only the unique text for this option, you can use:
This expression will place the value “1” at your new variable “myvalue”;
- Linked list (SQL):
This special linked list is able to query the database to recover valid options when according to other values of the form. For this type you will have to select the 'trigger field', which is other field of your form that launches the update of the linked list when changed. And also write down the query to the database to recover valid options, where you can use other values of the form using the ## sintax, for ex:
select id,name from #__users where name = ##fieldname##
This query will fill your option list with all users named after 'fieldname', that can be any other input field of your form.
It's configured same way as a dropdown list, with a set of options (manually, using csv or a query to database). The form will display a radiobutton group where only one option can be selected. You will get at the code section the value of the option selected.
It will show a single check to select. When recovering value of this field type you will get “Y” if the check was selected, no value otherwise.
Shows a default input text field.
Shows a multi-line input text field.
- Text autocompleter:
This is an advanced subtype of option list (see option list configuration below). When your option list contains a high number of entries, you can help your users to filter them using this type. You must configure it exactly as a default option list, but it will display at your form this way:
The whole list is initialy hidden. As soon as user begins to input text, options are filtered and shown to be selected.
- Inline result:
This is a result that you want to show inside the input form. Just place it at the form layout as any other input, and assing it any value at the code section. You will see each time the input is changed, the inline results will recalculate themselves and show the result automatically at the input form without pressing calculate button.
Used to ensure human beings are using your form, you can add this field to show a text validator it will be executed automatically when sending the form. The input form already has an invisible spam-protector, so you should not have need to use this type field, include it only if you want to add a 'visual' protection for your form.
- Upload file:
With this input type you will allow file upload from your input form. Users will use 'Select files' button to select one or more files from localhost, and 'upload files' to send them to the server.
Options to configure number of files allowed and other restrictions (like max size, destination folder, types allowed..etc) are set at 'Preferences tab', please check that section for further detail
Use this section to configure specific behaviour for this field
- Order in this list of fields: You can manually reorder the fields left menu changing numeric values here.
- Default: Default value that will show at the frontend form
- Placeholder: Specifies a short hint that describes the expected value of an input field. The hint is displayed in the input field when it is empty, and disappears when the field gets focus.
- Css class: Adds these values to class attribute of the field. You could also use it to add validators (Jquery validation : http://docs.jquery.com/Plugins/Validation).
- Reload Inline events: check for launching inline calculations everytime this field value changes.
You will find here different sections enabled, according to the field 'type' you choose for this field.
You will be able to fill in configuration for decimal positions and max/min values for numbers, or list of values allowed for option lists...etc.
Last modified on