Form Handling
Author: Artur Tomusiak
Purpose
The form handling tools allows business users to visually build custom forms in Cascade Server and have the contents captured back in the CMS database, to designated email addresses, to an Excel file, or connected to a custom script. The script also allows for a combination of the items listed (e.g. captured to email addresses and the CMS database).
Example Usage
The form builder and handler is useful for capturing data from a live web server. Example data that can be captured includes expense reports, event registration, articles, and contact us info.
How it Works
The form builder references the PHP or .NET script to handle the form submission as well as link to a "thank you" page. If the form contents are designated for specific email addresses, the script handles sending out the emails immediately. If the form contents are designated for the CMS database, the script uses SOAP-based web services to interface with the Cascade Server back-end to create the new form result asset. If the form contents are designated for an Excel file, the script appends the results to an XML file which is synchronized with the CMS via web services. If the form contents are designated for a custom script, the script file chooser in the data definition needs to be pointed to the appropriate script.
Background
This document explains how to configure the form information processing script with the CMS. It assumes that you have PHP 5 or .NET 2.0 installed on your web server and that you are comfortable with Cascade. Your version of Cascade Server needs to be at least 4.4. Knowledge of PHP or .NET is also useful, but not necessary to use this guide.
Installation
Please follow these steps to install the service.
1. The file extension of all your pages must be .php or .aspx
2. Create a data definition of any name and copy and paste the content of the file form-config-data-definition.xml as the code of the data definition.
3. Create a new page somewhere in the CMS, let's say in /test/files/form-config.xml and apply the new data definition. Also, apply your configuration set to it but clear it of any blocks and stylesheets.
4. Edit the page. The fields are filled with default values, but you will need to change some of the content depending on where you want to store the information:
a) if you are planning to store information as an email, adjust fields 1 and 2
b) if you are planning to store information as an XML Excel file in the published server, adjust fields 3 and 4
c) if you are planning to store information as an XML file inside a Cascade server, adjust fields 3, 5, 6, 7 and 8
You are able to select more than 1 option. See instructions on each field to correctly fill it out.
After filling the page out, publish it.
5. The file form.php (or form.aspx if you are using .NET) is supposed to serve as a block. Create a new XML Block (let's say /test/_internal/block/formProcess) and copy and paste the content of form.php file into it. When creating the block, you need to change the fourth line of the code where it says:
$configFileName = "[ system-asset:page ]/test/files/form-config.xml[ /system-asset:page ]";
You need adjust the full path to the form-config.xml in case if you saved it in a different directory. Make sure that the [ system-asset:page ] tags are around it.
This block will have to have its place in a template of a page that will process the information, so in your template, you need to create a new region for this block. In that region, select the block you just created.
6. Create a new XSL stylesheet, let's say it will be /test/_internal/stylesheet/form. When creating, copy and paste the code of the file form-stylesheet.xsl into it.
7. Now, create a form processing page. Create a new page, let's say /test/formProcess. Apply a configuration set to it that has a template with your region for the formProcess block. Apply the block that you created in #5 to this page. Publish that page.
8. Now, you can create a new page, let's say it will be /test/myform. This page will contain your form.
- Add a Data Definition to this form from Data Definitions/Marketing/Form. Make sure to check "Use Data Definition".
- In configurations, as the DEFAULT region, select block from common/blocks/current page
- As well, in the DEFAULT region, select the stylesheet you just created (in our case it will be /test/_internal/stylesheet/form)
9. Submit and edit the page:
- As "Action" select the form processing page you just created in #7
- Enter the Opening Text that will be a heading of your form
- Select "Send Email(s)" if you want the information from the form to be sent as email, "Save to CMS" if you want the information to be sent to an XML file inside CMS, or "Save to Excel File" if you want the information to be sent to an XML file in the published sever. * Remember that depending on what you chose here, you need to make sure that you filled out corresponding fields in #4.
- Create you own form using the "Form Item" area (you can add elements using '+' button)
- If you chose "Send Email(s)" option, you also need to enter the email address(es), TO which the emails will be sent (remember that in #4 you entered the email address FROM which the emails will be sent).
- Type a text that should appear in the submit button in "Submit Button Text"
10. Your form is ready to be published.
Form Handling Files
- form-config-data-definition.xml
This is the data definition that drives the XML config file. - form-config-xml-php.txt
This is an example XML config file. - form-stylesheet.xsl
This is an example stylesheet that will display form results for the user inside the CMS. - form-php.txt
This is the main script that does the form processing. - form-xml-php.txt
This is an example XML data storage file for the form responses. - form.zip
This is a zip file with all the necessary scripts for form handling. - form-data-definition.xml
This is the form builder data definition XML. - form-aspx.txt
This is the .NET version of the form handler. - form-aspx-cs.txt
This is the .NET code behind script.