RSform!Pro - Professional Form Management Component 

RSForm is a popular form creation tool for Joomla. It can be used by noobs and pros alike, giving the user extended flexibility in the matter of forms creation. With RSForm Pro, some new features were added, especially to improve user experience and functionality.

In this document you will find everything about RSForm Pro, the concepts behind the component, some tips and tricks and finally some examples about how to implement certain, more fancy forms.

Concepts [Read All]

This section will explain the basic concepts about RSForm Pro. The most important (we think :p ) feature is that the components themselves and the way that they are shown to the user are now separate (something like the Model-View-Controller, for you gurus out there). For the noobs out there, think like this: first you say `ok, these are the components that the form will have', then you say `the components that I just defined will be shown in the front-end like this'.

We added this feature because in the past version, the layout of the component was pretty hard to design (I'm sure everyone that used RSForm Lite remembers the FieldStyle attribute when creating a component). The user had to edit each element by hand, thus loosing the big picture about form layout.

Now, things are pretty simple. First of all, the user has to specify in the administration part of RSForm 2.0 the components that the form will contain. When this stage is complete, the user selects one of the predefined layouts for the component and voilà, the form layout is created.

Hardcore coders and designers, chill. We haven't forgotten you. If you want to make a custom form layout, you can create your own, using HTML and some simple placeholders we defined for your ease of use. And because work should be Really Simple (RS powered), you can take a predefined layout and customize it or start from scratch.

Throughout this document, we will use some typing conventions, as described below

• Important note!: when encountering this, focus you reading, as this note describes a very important setting / feature / component property
• (!): this symbol means experts only. In other words, don't mess up with the specified setting / feature / component property unless you know what you're doing.
• User: by user, we mean the person using the form (i.e. whoever is inputing data on your website). Not to be confused with Administrator (in this case, you) that customizes the components' look and behavior.

   

Components [Read All]

Layouts [Read All]

Anatomy of a component [Read All]

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

• Caption: the text that describes shortly the component.
• Body: the actual component.
• Description: the components' extended description, as defined when creating the component.
• Validation: the validation message shown whenever the component doesn't comply with the desired validation rules or the required property.

Now that we know what a component looks like, let's see how you can insert these parts into your layout. We defined a simple placeholder system. The general rule used is:

Emails [Read All]

With RSForm 2.0, you can send custom emails to the users that submitted the form. Naturally, you can customize RSForm 2.0 to send another email to you, as administrator. These two types of email are configured separately, in the two corresponding tabs of the back-end form management. In both cases, you can use simple placeholders to display information.
Because both forms are identical, we will cover them both

Let's see what fields can be configured.

• Email Form data to: the address where the email should be sent.
• Email Form data FROM: whenever the user receives the email, this will be be the senders' address (i.e. from who the mail came from).
• Email From Name: whenever the user receives the email, this will be be the senders' name (i.e. the person's name the mail came from).
• Email Subject: the subject of the email.
• Email Mode: you can send your email as plain text, or, if you wish to add more `color' to your message, you can send a HTML email.
• Email Text: the actual text of the email. If you set the last parameter (Email mode) to HTML, then you'll be able to put here HTML code, for a nicer email look.

  Important note! If you write here HTML tags BUT haven't set the Email mode option to HTML, the HTML tags will not be interpreted and the user, instead of seeing a nice bold message, may see something like Hello dear user in his email. Please take caution.

In all of these fields you can use placeholders to write important data. We defined for your ease of use general and form specific placeholders. Form specific placeholders are used just like layout placeholders are. Supported options for component placeholders are:

• value: this returns the value typed by the user in the corresponding component.
• name: the name of the component, as defined in the back-end.
• caption: the caption of the component, as defined in the back-end.

Let's see a short example. Suppose that among others, your form has a text field that required the user to input his/her name. This component is called user_name. If you want to use that value in your user message, write this in your email text field: language=HTML commentstyle= basicstyle= tabsize=2

If an user typed `Albert Einstein', the email that he would receive after he submitted the form will be: language=HTML commentstyle= basicstyle= tabsize=2

Let's see now the second category, general placeholders. General placeholders are used like this:

Custom validation rules (!) [Read All]

RSform! Pro allows to add custom validation rules for the components that allow validation rules.

In order to add a new validation rule, navigate in your Joomla file list, go to components/com_rsform/controller/validation.php. In this file you will find all the validation rules defined. In order to add a new validation rule, edit the file validation.php in the following manner:

1. Add a new function that allows only one parameter. The name of the function will be the name of the validation rule, as displayed when adding a new component.
2. On success, the function should return true. On fail, the function should return false.

Custom code(!) [Read All]

RSform! Pro allows you to add your custom PHP code in various parts of you form.

You can define code that will be executed upon form form display. To do this, select the form you wish to customize, go to the Scripts tab and add your custom code in the "Script called on form display " textarea. Please add this script without the PHP delimiters ()

You can also add custom PHP code once the form has been submitted. In order to do that, add the appropriate lines of code in the "Script called on form process ". Once the form is submitted, this piece of code is executed and after that the submissions are added to the database.

Another place where you can insert your code is when using hidden fields.  

Updates procedure [Read All]

In order to update your RSform!Pro, go to the main component panel. You'll find here a button that says "Check for updates". Click it. A new windows appears that may contain one of the three messages below:

1. Your version is up to date, no downloads available. If you see this message, you have the newest version of RSform!Pro. No need to update
2. A new version is available. Click here to download the update. If you see this message, follow these steps:
1. Download the updates using the link provided (the text "Click here to download the update" is a link that will point you to the download).
   
2. Once the component is downloaded, go to the main screen of RSform!Pro, click on "Check for updates". You'll notice in the bottom of the screen an upload component. Click "Browse", point to the update file that you downloaded.
3. Click "Update" and RSform!Pro should be up to date.
   
3. Please make sure you entered your license code correctly in the configuration script. If you see this message, then you haven't entered your license code correctly.

Adding a form to a menu [Read All]

RSform!Pro has three different ways of adding a form to a menu item.

1. Go to Administrator > RSform!Pro > Manage Forms > and click on the Add to menu button listed on each form row. Select the menu where you want your form and give it a title
2. Go to Administrator > Menus > Mainmenu > New > Internal Link > RSform!Pro then give it a title, and in the Form ID type the number that you see on the last column of the Forms Manager screen (usually 1, 2..)
3. In the Forms Manager, click on Preview, and copy the generated link, then go to Administrator > Menus > Mainmenu > New -> External Link and paste the previously copied link

We advice you to use the first or the second method since it is compatible with all the 3rd Party SEF extensions for Joomla. 

Using Multi Language forms with Joomfish [Read All]

If you wish to use multi-language forms in RSform!Pro, you have to follow these steps:

1. Let's assume that you have English and Spanish languages installed in your Joomfish. Create your English form first(Form Id = 2).
2. Copy the form using the copy function, and translate it in Spanish. The new form will have Form id = 3 for example
3. Go to Menus > Mainmenu > New > RSform!Pro > and set the Form Id to point by default to the english version (Form Id = 2)
   
4. Go to Joomfish > Translation > English > Menus and select the previously created menu item, then in the Form ID type 2 as that is the English Form
5. Go to Joomfish > Translation > Spanish > Menus and select the same menu item, only this time type 3 in the Form ID to show the Spanish Form

How to display the submissions in the front-end [Read All]

Submissions can be displayed in the front-end using the mod_rsform_list module. First you'll have to download, install and configure the mod_rsform_list module. You can download it by logging in to your RSjoomla! account, and going to the Support Center > RSform!Pro Downloads > Modules > mod_rsform_list.zip

If you want to display the submissions inside an article, you have to follow these additional steps:

1. You have to place the module in a module position like user4 for example(somewhere where there's no other module published)
2. In your article you'll have to use the {mosloadposition user1} for Joomla 1.0.x and {loadposition user4} for Joomla 1.5.x syntax which triggers the LoadPosition plugin

The Scripts Tab [Read All]

Database Mappings [Read All]

This function allows you to save the data from your submissions to an external table or tables, depending on your configuration. Using this functionality, RSform!Pro can be used to add data into whatever application you have installed in your Joomla powered site.

Please take into account that this function should only be used by professionals.

In order to map a submission value to one or more table columns you must have a form with all the components already configured. In order to define a mapping, please follow these steps:

1. Go to "Manage forms" in the main panel of RSform!Pro
2. Select the appropriate form by clicking on it
3. Here, build your form by adding components
4. Once you are done adding components, please go to the "Mappings" tab located to he right
5. Here, select as follows
1. The component (identified by it's name) that it's value you wish to save
2. The table where you want the specified submission value to be saved to
3. The column from the selected table you want the specified submission value to be saved to

Get your license code [Read All]

RSform!Pro Custom scritps and customizations [Read All]

How ro migrate forms from RSform! to RSform!Pro [Read All]