Components This section describes the basic functionality of RSForm Pro. Let's have a short overview about components. We have included almost every component used in forms, so there shouldn't be any problem in finding the right one for you. As old users are accustomed, we are receptive to user input and we'll try to add new components as they are requested. Now, let's get back to our main topic. Every component is defined with properties. A property describes a specific part of that components' behavior.
We can find general properties, found in all components (name and caption, for example) and some specific for every component (the possible values that should appear in a select list, for example).
Important note! When adding components, you must always specify a unique, non-empty component name. The component name is essential, as almost every part in both front-end and back-end use the component name. In order to avoid problems, RSForm Pro will not allow you to save a component that has no name (i.e. the Name property is empty) or if another component in the same form has the same name. Naturally, it will display an alert whenever you don't follow these rules. In the following, we'll describe the available components in RSForm Pro, along with the properties associated to every component. Ok, let's begin. Standard HTML text field. The properties that this component supports are - Name: the name of the component. Please remember that this property must a have a non-empty and unique value within a form.
- Caption: the caption associated with this component.
- Required: this property specifies that the current component must have a value, otherwise the form will not be submitted.
- Size: the size that the text box will have upon display.
- MaxSize: whenever a text field is submitted, no more that MaxSize number of characters are saved in the database.
- ValidationRule: verifies that the text in the text area matches a certain pattern, defined by the validation rule. Currently defined validation rules are:
- e-mail: checks for standard e-mail format.
- numeric: checks for numbers.
- alphanumeric: checks for alphanumeric sequences.
- ValidationMessage: whenever the validation rule is not met, this message will show up in the front-end part of RSForm Pro (that's when a user wants to submit something using the form that you've just created).
Be advised that this message is also shown when the Required constraint is not met (let's suppose that we have a text box with no validation rule and with the Required property set to `Yes'. If the user tries to submit an empty text box, the validation message will appear and the the form will not be submitted). - AdditionalAttributes(!): using this property you can set custom attributes inside the HTML tag. The most common use for this property is adding custom CSS style (using style="some style here") or for further javascript processing (like onKeyUp="javscriptFunction()").
Naturally, you can add whatever additional attributes you like, taking into account that they must be valid for this component type. - DefaultValue: you can set a default value to the text field to be displayed in the front end part.
- Description: the description of the text field. This will be displayed in the front end, as a textual help for the user. Use this when the Caption of the component is not self-explanatory.
Standard HTML password field. The properties that this component supports are - Name: the name of the component. Please remember that this property must a have a non-empty and unique value within a form.
- Caption: the caption associated with this component.
- Required: this property specifies that the current component must have a value, otherwise the form will not be submitted.
- Size: the size that the text box will have upon display.
- MaxSize: whenever a text field is submitted, no more that MaxSize number of characters are saved in the database.
- DefaultValue: you can set a default value to the text field to be displayed in the front end part.
- AdditionalAttributes(!): using this property you can set custom attributes inside the HTML tag. The most common use for this property is adding custom CSS style (using style="some style here") or for further javascript processing (like onKeyUp="javscriptFunction()").
Naturally, you can add whatever additional attributes you like, taking into account that they must be valid for this component type. - Description: the description of the text field. This will be displayed in the front end, as a textual help for the user. Use this when the Caption of the component is not self-explanatory.
- ValidationMessage: shown when the Required constraint is not met (let's suppose that we have a text box with no validation rule and with the Required property set to `Yes'. If the user tries to submit an empty text box, the validation message will appear and the the form will not be submitted).
Standard HTML text area. The properties that this component supports are - Name: the name of the component. Please remember that this property must a have a non-empty and unique value within a form.
- Caption: the caption associated with this component.
- Required: this property specifies that the current component must have a value, otherwise the form will not be submitted.
- Cols: the number of columns of the text area component.
- Rows: the number of rows of the text area component.
- ValidationRule: verifies that the text in the text area matches a certain pattern, defined by the validation rule. Currently defined validation rules are:
- e-mail: checks for standard e-mail format.
- numeric: checks for numbers.
- alphanumeric: checks for alphanumeric sequences.
- ValidationMessage: whenever the validation rule is not met, this message will show up in the front-end part of RSForm 2.0 (that's when a user wants to submit something using the form that you've just created).
Be advised that this message is also shown when the Required constraint is not met (let's suppose that we have a text box with no validation rule and with the Required property set to `Yes'. If the user tries to submit an empty text box, the validation message will appear and the the form will not be submitted). - AdditionalAttributes(!): using this property you can set custom attributes inside the HTML tag. The most common use for this property is adding custom CSS style (using style="some style here") or for further javascript processing (like onKeyUp="javscriptFunction()").
Naturally, you can add whatever additional attributes you like, taking into account that they must be valid for this component type. - DefaultValue: you can set a default value to the component to be displayed in the front end part.
- Description: the description of the component. This will be displayed in the front end, as a textual help for the user. Use this when the Caption of the component is not self-explanatory.
Standard HTML select list. The select list can be customized to allow either one value select or multiple values select. The properties that this component supports are - Name: the name of the component. Please remember that this property must a have a non-empty and unique value within a form.
- Caption: the caption associated with this component.
- Size: the size of the select list as displayed in the front end. If you leave it empty, only one element from the select list will be displayed. Changing this option is useful especially when creating multi select lists.
- Multiple: if set to `Yes', the user can select multiple options from the select list.
- Items: this property specifies the options that will be visible in the select list. There are a number of ways you can specify options.
- Simple: just type in the options, separated by newlines (i.e. hit `Enter'), like this.
Example:
option 1
option 2
and so on
If you want that a certain option is selected by default, just add [c] (stands for `checked') at the end of the desired option, like this:
Example:
option 1
option 2[c] //this option will be selected by default
and so on
This feature can also be used when defining multi select. If you had a multiple select list, and wished that some options were selected by default, do like this
Example:
option 1
option 2[c] //selected by default
option 3[c] //selected by default
option 4
option 5[c] //selected by default
Important note! If you define a single value select list (i.e. the user can't choose more than one option), please be careful on defining the default values. Take a look at the following example
Example:
option 1
option 2[c]
option 3[c]
option 4
option 5[c]
This is a perfectly valid example, only that in our case (the user can't choose more than one option) the default option will be `option 5'. So, if you define a single value select list and wish that `option 2', for instance, should be displayed by default, do like this
Example:
option 1
option 2
option 3[c]
option 4
option 5
- Advanced (!): suppose that you want that the select list displays some values, but when the user submits the form, other values should be returned (the text and value attributes in the HTML option tag are not the same). In order to do this, use the pipe ( ) character. The value left of the pipe is the returned value, whilst the value right of the pipe is the value displayed by the select list in the front-end.
Example:
value 1|option 1
value 2|option 2
value 3|option 3
For options that should be checked by default, use the same rule as above
Example:
value 1|option 1[c]
value 2|option 2[c]
value 3|option 3
- Setting a select list to required
If you want to display a select list and make the first option required, you should use this syntax:
|Please select...
Option 1
Option 2
Option 3
As you can see, the first value of the first option is empty (--empty--|Please select..) and setting the Required parameter to Yes will trigger the validation message
- Required: this property specifies that the current component must have a value, otherwise the form will not be submitted. In other words, it means that at least one option must be selected in order that the selection is valid.
- AdditionalAttributes(!): using this property you can set custom attributes inside the HTML tag.
- Description: the description of the component. This will be displayed in the front end, as a textual help for the user. Use this when the Caption of the component is not self-explanatory.
- ValidationMessage: shown when the Required constraint is not met. In other words, if the user doesn't select any option from the select list, this message will be displayed and the form will not be submitted.
Standard HTML checkbox. This component allows the user to define more checkboxes grouped together. The properties that this component supports are - Name: the name of the component. Please remember that this property must a have a non-empty and unique value within a form.
- Caption: the caption associated with this component.
- Items: this property specifies the checkboxes that will be visible . There are a number of ways you can specify checkboxes.
- Simple: just type in the names of the checkboxes , separated by newlines (i.e. hit `Enter'), like this.
Example:
name 1
name 2
and so on
If you want that a certain option is selected by default, just add [c] (stands for `checked') at the end of the desired checkbox name, like this:
Example:
name 1
name 2[c] //this checkbox will be checked by default
and so on
If you want more than one checkboxes checked, do this
Example:
name 1
name 2[c] //checked by default
name 3[c] //checked by default
option 4
option 5[c] //checked by default
- Advanced (): suppose that you want that the checkbox displays some values, but when the user submits the form, other values should be returned. In order to do this, use the pipe ( ) character. The value left of the pipe is the returned value, whilst the value right of the pipe is the value displayed by the checkbox in the front-end.
Example:
value 1|name 1
value 2|name 2
value 3|name 3
For checkboxes that should be checked by default, use the same rule as above
Example:
value 1|name 1[c]
value 2|name 2[c]
value 3|name 3
- Flow: whether the checkboxes should be presented in a vertical or horizontal fashion.
- Required: this property specifies that the current component must have a value, otherwise the form will not be submitted. In other words, it means that at least one checkbox must be checked in order that the checkbox group is valid.
- AdditionalAttributes(!): using this property you can set custom attributes inside the HTML tag.
- Description: the description of the component. This will be displayed in the front end, as a textual help for the user. Use this when the Caption of component is not self-explanatory.
- ValidationMessage: shown when the Required constraint is not met. In other words, if the user doesn't check any checkbox, this message will be displayed and the form will not be submitted.
Standard HTML radio group. This component allows the user to define more radios grouped together. The properties that this component supports are - Name: the name of the component. Please remember that this property must a have a non-empty and unique value within a form.
- Caption: the caption associated with this component.
- Items: this property specifies the radio options that will be visible . There are a number of ways you can specify radio options.
- Simple: just type in the names of the radio options , separated by newlines (i.e. hit `Enter'), like this.
Example:
option 1
option 2
and so on
If you want that a certain option is selected by default, just add [c] (stands for `checked') at the end of the desired radio option name, like this:
Example:
option 1
option 2[c] //this option will be checked by default
and so on
- Advanced (): suppose that you want that the radio group displays some values, but when the user submits the form, other values should be returned. In order to do this, use the pipe ( ) character. The value left of the pipe is the returned value, whilst the value right of the pipe is the value displayed by the radio option in the front-end.
Example:
value 1|option 1
value 2|option 2
value 3|option 3
For radio options that should be checked by default, use the same rule as above
Example:
value 1|option 1[c]
value 2|option 2
value 3|name 3
- Flow: whether the radio options should be presented in a vertical or horizontal fashion.
- Required: this property specifies that the current component must have a value, otherwise the form will not be submitted. In other words, it means that at least one radio option must be selected in order that the radio group group is valid.
- AdditionalAttributes(!): using this property you can set custom attributes inside the HTML tag.
- Description: the description of the component. This will be displayed in the front end, as a textual help for the user. Use this when the Caption of the component is not self-explanatory.
- ValidationMessage: shown when the Required constraint is not met. In other words, if the user doesn't select any radio option, this message will be displayed and the form will not be submitted.
As the name implies, this is a very customizable calendar used for date/time collection. The properties that this component supports are - Name: the name of the component. Please remember that this property must a have a non-empty and unique value within a form.
- Caption: the caption associated with this component.
- Required: this property specifies that the current component must have a value, otherwise the form will not be submitted. In other words, the user must submit a date in the component.
- DateFormat: this property describes how the date will be shown to the user in the front-end part. Please use the folowing table to determine your desired date format.
| Mask | Description |
|---|
| d | Day of the month as digits; no leading zero for single-digit days | | dd | Day of the month as digits; leading zero for single-digit days. | | ddd | Day of the week as a three-letter abbreviation. | | dddd | Day of the week as its full name. | | m | Month as digits; no leading zero for single-digit months. | | mm | Month as digits; leading zero for single-digit months. | | mmm | Month as a three-letter abbreviation. | | mmmm | Month as its full name. | | yy | Year as last two digits; leading zero for years less than 10. | | yyyy | Year represented by four digits. | - CalendarLayout: specifies how the calendar should be shown in the front-end. Possible option are
- Flat: the calendar is displayed directly (i.e. no action is required to show the calendar).
- Popup: to display the calendar, the user must push a button and the calendar is displayed.
- AdditionalAttributes(!): using this property you can set custom attributes inside the HTML tag.
- ReadOnly: applicable only for a popup calendar. This option alows the user to edit manually the text box where the date is displayed.
- PopupLabel: applicable only for a popup calendar. Sets the text on the button that when pressed, shows the calendar.
- Description: the description of the component. This will be displayed in the front end, as a textual help for the user. Use this when the Caption of the component is not self-explanatory.
- ValidationMessage: shown when the Required constraint is not met. In other words, if the user doesn't choose date, this message will be displayed and the form will not be submitted.
As the exclamation mark in the name implies, this component should not be used by the noobs. This is a standard HTML button. The properties that this component supports are - Name: the name of the component. Please remember that this property must a have a non-empty and unique value within a form.
- Caption: the caption associated with this component.
- Label: the text written on the button.
- Reset: if set to `Yes', whenever this button is displayed in the front-end, a reset button will also appear.
- ResetLabel: the text written on the reset button, if it exists.
- AdditionalAttributes(!): using this property you can set custom attributes inside the HTML tag. Useful for adding onClick="someJavaFunction()" tags, in order to run a javascript previously to form submission.
- Description: the description of the component. This will be displayed in the front end, as a textual help for the user. Use this when the Caption of the component is not self-explanatory.
This component behaves like a standard submit button, only that instead of text it displays an image. The properties that this component supports are - Name: the name of the component. Please remember that this property must a have a non-empty and unique value within a form.
- Caption: the caption associated with this component.
- Label: the alternate text of the image that should appear on the submit button.
- ImageButton: the link to the image that should appear on the submit button.
- ImageReset: the link to the image that should appear on the reset button.
- Reset: if set to `Yes', whenever this button is displayed in the front-end, a reset button will also appear.
- ResetLabel: the alternate text of the image that should appear on the reset button, if it exists.
- AdditionalAttributes(!): using this property you can set custom attributes inside the HTML tag. Useful for adding onClick="someJavaFunction()" tags, in order to run a javascript previously to form submission.
- Description: the description of the component. This will be displayed in the front end, as a textual help for the user. Use this when the Caption of the component is not self-explanatory.
This is a standard HTML submit button. This component is mandatory (required) for every form. The properties that this component supports are - Name: the name of the component. Please remember that this property must a have a non-empty and unique value within a form.
- Caption: the caption associated with this component.
- Label: the text written on the button.
- Reset: if set to `Yes', whenever this button is displayed in the front-end, a reset button will also appear.
- ResetLabel: the text written on the reset button, if it exists.
- AdditionalAttributes(!): using this property you can set custom attributes inside the HTML tag. Useful for adding onClick="someJavaFunction()" tags, in order to run a javascript previously to form submission.
- Description: the description of the component. This will be displayed in the front end, as a textual help for the user. Use this when the Caption of the component is not self-explanatory.
Captcha component for user authentication. We recommend using this on all your forms, in order to prevent bogus form submissions by automatic bots. The properties that this component supports are - Name: the name of the component. Please remember that this property must a have a non-empty and unique value within a form.
- Caption: the caption associated with this component.
- Length: the length of the caption. The default is 4.
- BackgroundColor: the background color of the captcha component. Default is #FFFFFF (white). Please specify the color in a hexadecimal way, as shown in the default value.
- TextColor: the text background color of the captcha component. Default is #000000 (black). Please specify the color in a hexadecimal way, as shown in the default value.
- Type: the type of characters used in the captcha component. Currently supported types area:
- alpha: only letters.
- numeric: only numbers.
- alphanumeric: both letters and numbers.
- AdditionalAttributes(!): using this property you can set custom attributes inside the HTML tag.
- Flow: whenever the captcha image is shown, a text box will also appear near it. This property sets whether the text box and the captcha image should appear next to each other (`horizontal' setting) or the text box should appear underneath the captcha image (`vertical' setting).
- Description: the description of the component. This will be displayed in the front end, as a textual help for the user. Use this when the Caption of the component is not self-explanatory.
- Refresh: ever had to fill a captcha, but couldn't quite distinguish whatever was written there? Turning this property to `Yes' will show a `Refresh' button near the captcha that will refresh the captcha image.
- Description: the description of the component. This will be displayed in the front end, as a textual help for the user. Use this when the Caption of the component is not self-explanatory.
- RefreshText: the text that should be displayed in the Refresh button of the captcha.
- ValidationMessage: whenever the captcha is not valid (i.e. the text on the image is not the same as the text entered by the user), this message will be shown in the front-end.
Standard HTML file upload. The properties that this component supports are - Name: the name of the component. Please remember that this property must a have a non-empty and unique value within a form.
- Caption: the caption associated with this component.
- Size: the maximum alowed size for the file. The value is measured in kiloBytes.
- Required: this property specifies that the current component must have a value, otherwise the form will not be submitted. In other words, if the property is set to `Yes', the user must upload a file.
- AcceptedFiles(!): this property should be used whenever you want to accept only certain files. Insert in this property the extension (without the dot, example `doc') of the accepted files, separated by newlines.
- Destination: the absolute path where the upload files will be saved. By default, RSForm 2.0 places uploaded files in component/com_rsform/uploads. You may modify this path. Upon saving, RSForm 2.0 checks whether the specified destination is valid(i.e. is a directory) and writable.
- AdditionalAttributes(!): using this property you can set custom attributes inside the HTML tag.
- Description: the description of the component. This will be displayed in the front end, as a textual help for the user. Use this when the Caption of the component is not self-explanatory.
- ValidationMessage: shown when the Required constraint is not met. In other words, if the user doesn't upload a file or the file is invalid (the size is grater than accepted or the file type is not valid), this message will be displayed and the form will not be submitted.
Simple free text. The properties that this component supports are - Name: the name of the component. Please remember that this property must a have a non-empty and unique value within a form.
- Text: the text that should appear.
Standard HTML hidden field. The properties that this component supports are - Name: the name of the component. Please remember that this property must a have a non-empty and unique value within a form.
- DefaultValue: the default value of the hidden field.
- AdditionalAttributes(): using this property you can set custom attributes inside the HTML tag.
This is basically a hidden field with a preset value. Quite useful if you use RSForm 2.0 for a help and support center. The properties that this component supports are - Name: the name of the component. Please remember that this property must a have a non-empty and unique value within a form.
- Characters: the type of characters the ticket is made of. Currently, you can select from:
- alphanumeric: both letters and numbers.
- alpha: only letters.
- numeric: only numbers.
- Length: the number of characters that the ticket will have.
- AdditionalAttributes(): using this property you can set custom attributes inside the HTML tag.
|
