RSForm!Pro - Components

This section describes the basic functionality of RSForm!Pro. We have included almost every component used in forms, so there shouldn't be any problem in finding the right one for you. Every form 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).

General description of a form field

In this section, you'll learn about the parts that make a component. From our point of view, a component has three distinct areas:

The General tab provides information such as:

• Name: the name of the form component. This needs to be unique for each form. It can contain only alphanumeric chars. The name of the field is only used for internal reference - it will not be displayed in the front-end area.
• Caption: the caption or label is the text or HTML that is being displayed in the actual form.
• Default value: the value will be automatically filled in when displaying the form. This is available for Text boxes or Text areas. Inside the Default Value area you can use custom PHP codes in between the //<code> and //</code> tags.
• Items: this is available for drop-downs (or select lists), radio groups and check-box groups. The items should be specified one per line. This too, can incorporate custom scripts in between the code tags.

  The selectable items are composed out of two parts: value and label, separated by the pipeline character (|).
  

  For example: Steve Matt|Steve Matt, marketing director.
  
  Using this formula, the selection will display Steve Matt, marketing director, but Steve Matt will be stored into the database.

  You can even have an option selected by default, by using the [c] syntax.
  

  For example: Steve Matt|Steve Matt, marketing director[c]

  Or you can choose to disable a particular option, by using the [d] syntax.
  

  For example: Steve Matt|Steve Matt, marketing director[d]

  Since RSForm! Pro revision 43, you can use the placeholder {field_name:text} in the Thank You message or Email messages(the value "field_name" should be replaced with the actual name of the field). The placeholder will return the label of the selection and not the actual value and it is available for radio button, checkbox and drop-down fields. If the placeholder is not correctly replaced in the messages, please update to the latest version of the component by using the method presented here.

• Description: text/HTML area that provides a description of the field. This can be useful for providing explanations or indications for that particular field.

Before a form can be submitted, all fields need to pass the validation rules.

• Required: Yes / No - if this is enabled some text needs to be typed in or a selection to be made.
• Validation Rule:
  • Email: if selected, only email valid email addresses (format wise) will pass the validation rule.
  • Email Address /w DNS check: besides the email address format check, RSform!Pro performs an additional email domain check, thus reducing the chance to validate dummy email addresses.
  • Numeric: only numbers will be accepted
  • Unique Field: if enabled, this validation will only allow a field value that hasn't been submitted before, for that particular form.
  • USA ZIP Code: only valid ZIP numbers (format wise) can be submitted. Valid formats are 5 numeric values only or 5 numeric along with a dash ("-"), followed by another group of 4 numeric values. Examples of accepted formats: "12345", "12345-1234".
  • Phone Number: only the following phone number format will be validated: "123-456-7890"
  • Credit Card: if selected, credit card numbers from the following vendors will be validated: AMEX, Diners, Discover, Master Card and Visa
  • Alphanumeric: numbers and letters (ASCII standard) are accepted.
  • Alpha: only standard letters will be accepted
  • Custom Validation: this can be used in combination with any other validation rule (apart from "password"). Using this you can validate additional chars. This is particularly usefull if your language has special chars - thus these can be validated.
  • Passphrase: the typed in value will be accepted only if it matches with the value specified in the Default Value area. This is oftently used for password fields, but can be applied for plain text box fields.
  • IP Address: will only validate valid IP addresses. Example: 192.168.1.1
  • Valid URL: will only validate a valid URL. Example: http://site.com, https://site.com/path/here. Note that the protocol specification is required (http/https).
  • Regex: this can be used for more advanced users to create their own validation patterns. Standard regular expressions specifications can be used.
  • Same Value as Other Field: using this will check if two fields have the same value, selecting this validation another field will appear called "Field Name To Compare With" where you can add that field's exact name you want it to compare to.
• Validation Message: text / HTML area that will allow you to set up a message that will be displayed if the field validation fails.

The Attributes area allows you to add Javacript triggers, custom style (for that particular field), impose size restrictions, etc. Anything filled in this area, will be added directly to the HTML tag. Each field type can have its own specific attributes (we will provide details in the field listing types).

Form Fields

Standard HTML input text box. Besides the General and Validation options, the text box, has the following specific Attributes:

• Size: Sets or returns the width of a text field (in number of characters)
• Max size: how many chars can be typed in
• Additional Attributes: anything filled in this area, will be added directly to the HTML input tag. For example:
  Javacript: onkeyup="your_function();" - this will trigger a Javascript function whenever you type in something in that particular textbox.
  CSS: style="color:red" - the text will have a red color.
  Input property: readOnly="readonly" - you will not be able to type into it.

Standard HTML input textarea. Besides the General and Validation options, the textarea, has the following specific Attributes:

• Cols: Specifies the visible width of a text-area
• Rows: Specifies the visible number of rows in a text-area
• Enable WYSIWYG Editor: if enabled the default configured editor will be added
• Additional Attributes: anything filled in this area, will be added directly to the HTML input tag. For example:
  Javacript: onkeyup="your_function();" - this will trigger a Javascript function whenever you type in something in that particular textbox.
  CSS: style="font-weight:bold" - the text will have be bold.
  Input property: disabled="disabled" - the field will be completly disabled. You will not be able to type in, and its value will not be submitted.

Standard HTML select tag. As a validation rule, this can only be set to be Required or not. Attributes:

• Size: how many items will be displayed. By default this has an empty value - making it a drop-down element. If a size is specified, this will be displayed as a select list.
• Multiple: yes / no - if enabled, you will be able to have multiple selections by holding the CTRL or SHIFT keys
• Additional Attributes: as with other fiel types, you can use this area to customize the specific form element. For example:
  Javacript: onchange="your_function();" - this will trigger a Javascript function a selection will be made.
  CSS: style="width:200px" - the drop-down / select list will have a 200px width.
  Input property: disabled="disabled" - the field will be completly disabled. You will not be able to type in, and its value will not be submitted.

A select option can be selected by default using the [c] syntax. Example, on how the Items section will look like:

Select options can also be gruped. Usually the grup title can't be selected. The grup title should be marked with [g]. Example, on how the Items section will look like:

Standard HTML input checkbox tag. If multiple checkbox items are used, these will need to be specified each on a new line, in the Items area. As a field validation it can be set as required or not. Attributes:

• Flow: Horizontal / Vertical - If horizontal flow is set, the items will be displayed in one row. If vertical is set, the items will be displayed one below the other
• Additional Attributes:
  Javacript: onclick="your_function();" - this will trigger a Javascript function when a checkbox will be clicked.
  CSS: style="margin-left:20px" - this will set a 20px margin on the left side.
  Input property: disabled="disabled" - the field will be completly disabled. You will not be able to type in, and its value will not be submitted.

Standard HTML input radio tag. A radio group can be set to be required or not. As in the case of checkbox, the radio group has the same Attributes:

• Flow: Horizontal / Vertical - If horizontal flow is set, the items will be displayed in one row. If vertical is set, the items will be displayed one below the other
• Additional Attributes:
  Javacript: onclick="your_function();" - this will trigger a Javascript function when a checkbox will be clicked.
  CSS: style="margin-left:20px" - this will set a 20px margin on the left side.
  Input property: disabled="disabled" - the field will be completly disabled. You will not be able to type in, and its value will not be submitted.

Standard HTML input password field. Essentially being input text element, it has the same properties, just that the typed in values are obscured. It can be required and can have any validation rule.

One special mention is the Passphrase validation rule. If enabled, the field will pass the validation if the typed in value is the same as the one specified in the Default Value area.

Standard HTML input upload field. In the Validations area the field can be set to be required or not. Attributes:

• File size: the maximum size of an accepted file. This should be specified in KB.
• Accepted files: a list of accepted file extensions. These should be specified each on a new line.
• File prefix: to prevent file replacements in the upload folder, RSForm!Pro adds a random prefix to the uploaded file names. If you specify a prefix - this will be added instead. Note that you can also use a PHP code to generate the prefix dynamically. This should be specified in between the //<code> and //</code> tags.
• Destination: the path to the upload folder.
• Attach: the file can be attached to the User, Admin emails and as well as to the configured Additional Emails.
• Additional Attributes

As of rev. 45, the {your_field_name:localpath} placeholder was added for the PDF Plugin, that replaces "your_field_name's" value with the local path of the image found on the server (eg. /home/public_html/path/to/uploaded/image.jpg). You can use this placeholder when adding the values of your file upload fields in the PDF attachment.

As of rev. 46, a new placeholders was added : {your_field_name:filename}. You can use this placeholder in order to return the name of the uploaded file as it is saved in the database.

The Free text form element is a simple HTML block. This can be very useful when trying to add a form header or footer for example. Since this is a static text, it does not have any configuration parameters, apart from Name and Content.

The calendar can be used for specifying a date. Using this method you can be sure that everyone will specify the date in the same format with just a few simple selection clicks.
Validations:

• Required: you can choose to make the calendar mandatory.
• Date Modifier: used to modify another calendar(within the same form) which will inherit the minimum or maximum possible date, based on what is selected in this calendar.
• Validation Message: here you can type your own validation message.

Attributes:

• Date format: the format of the selected date. By default dd.mm.yyyy is being used. Notes: If tripple lettering is used, short day and month naming will be returned (ddd.mmm.yyyy, for example). Four letters can be used to specify the day and month names in full (dddd.mmmm.yyyy).
• Max date: the submitter will not be able to select a date past the one specified in this field. Custom PHP codes can be used in between the //<code> and //</code> tags.
• Min date: the submitter will not be able to select a date below the one specified here. As in the "max date" custom PHP codes can be used in between the //<code> and //</code> tags.
• Calendar layout: Flat / Popup - controls how the calendar si displayed.
• Readonly: Yes / No - If set to No the submitter can type in the date.
• Popup label: if the Popup layout is being used, you can set up the label of the button that triggers it.
• Additional Attributes: anything that is specified here will be reflected on the field that stores the date selection. For example: style="color:red" - this will make the color of the selected date red.

Standard HTML button. This has no submiting function. Attributes:

• Reset: Yes / No. If enabled a complementary reset button will be added.
• Reset Label: the label of the button.
• Additional Attributes: this can be used to trigger a Javascript function or to add a custom style.

Standard HTML input image type. This includes a submit function. Cliking on the image will submit the form. Attributes:

• Image button: the path to the submit image.
• Image reset: the path to the reset image.
• Reset: yes / no.
• Reset label.
• Additional Attributes: can be used for additional style or Javascript triggers. This will only be applied to the submit image.

The captcha field is composed out of a text input and a image that displays some random chars. This is oftenly used to prevent spam form submissions. Attributes:

• Image Generation: Use FreeType / No FreeType / Invisible. If the PHP FreeType is being used, the generated chars will have different fonts, thus making them harder to detect for spammers. If the Invisible captcha type is being used, no input or image will be generated. It uses a Session based value to make the difference between a user and spam bot.
• Length: how many chars will be generated.
• Background Color: the backgrond color code of the generate image. Example: #FFFFFF.
• Text Color: the text color of the generated image. Example: #000000.
• Type: Alpha / Numeric / Alphanumeric - the generated image can contain standard chars and/or numbers.
• Flow: Vertical / Horizontal - the input box can be displayed inline with the image or below it.
• Show Refresh: Yes / No - if enabled a refresh link can be displayed. If clicked, this will generate a new image.
• Refresh Text: the text of the refresh link.
• Size: the font size of the generated chars.
• Additional Attributes: attributes will be added directly into the text input box of the captcha field.

Standard HTML input hidden. This is oftenly used to store additional information that does not need to be displayed.

The RSform!Pro Support field is basically a hidden field that holds a random generated sequence. Attributes:

• Characters: Alphanumeric / Alpha / Numeric - the generated sequence can contain alphabetical chars and/or numbers
• Length: the length of the generated sequence.

Special purpouse fields

If a Pagebreak element is being added, the form will have multiple pages. The actual element is composed out of the buttons: Next and Previous. As configuration parameters, besides the mandatory field Name, it has the following Attributes:

• Next Button Label: the label of the button that will move to the next page.
• Prev Button Label: the label of the button that will move to the previous page.
• Validate When Changing Page: Yes / No. If enabled, all form fileds will be validated when clicking on the Next.
• Additional Attributes: can be used to trigger Javascripts or for custom style. Anything that will be specified here, will be applied to both buttons.

Advanced Form Fields

The Birthday Field element allows the user to select a date.
Validations:

• Allow Incorrect Dates: enabling this will allow users to input any date regardless of being corect or not, example 31-Feb-2013.
• Validation Rule: available validations are From today(including today), From tomorrow, Until today(including today), Until today(excluding today).

Attributes:

• Fields Ordering: you can choose the order of the date drop-downs.
• Date Separator: the date separator, by default "/".
• Show Day Selector: enable/disable the day selector.
• Show 'Please Select' on Day Selector: name of the first item that will represent the according drop-down, leave blank to remove.
• Day Display: select how the numbers will display.
• Show Month Selector: enable/disable the month selector.
• Show 'Please Select' on Month Selector: name of the first item that will represent the according drop-down, leave blank to remove.
• Month Display: select how the numbers will display.
• Show Year Selector: enable/disable the month selector.
• Show 'Please Select' on Year Selector: name of the first item that will represent the according drop-down, leave blank to remove.
• Start Year: the starting year.
• End Year: the ending year.
• Additinal Attributes: can be used to trigger Javascripts or for custom style.

Video tutorial

How to create a simple Joomla! form