Form Manager Overview

Form manager ships with LogiCreate 2.9 and later releases. Form manager was built to provide developers a way to handle form creation, validation and error handling. Let's face it, our lives as a web application developers are mostly spent taking input from one user, storing it in a database and retrieving that information for another user. Error checking a forty field form can be a tedious process and creating complex drop downs that re-select themselves if there is a user error can be time consuming. Form manager addresses these and other problems and tries to take the work out of creating forms for a LogiCreate developer. The next few sections we'll cover how to create forms in LogiCreate using this tool and give you some advanced uses of how you can extend form manager to meet your site's needs.

Features

• Handles required vs optional fields
• Configurable table properties
• Forms are built through a web interface (LogiCreate Hercules Control Center)
• Validates / cleans input
• Guards against cross-site attacks
• Developer focused
• Built using PHP (obviously)
• Object oriented
• Database driven
• Handles blank rows with style sheets (great for breaking the form up for usability)
• Extensible (extend lib/SiteForms.php for extra functionality)
• Built-in error checking
• Allows for database driven custom fields

Using the interface

Site Forms

The interface to create, add, and modify forms is accessible via the Hercules Control Center (which is included in LogiCreate). In the Site menu in Hercules (located on the left hand side of the screen) locate the link that says Site Forms. Select this link by clicking on it. As normal with the Hercules control panel, the interface for the application will appear in the right hand side of the screen.

At the top of the screen you will see two links: Site Forms and Add a New Form. The Site Forms link will take you back to the screen you are on. We'll touch more on Add a New Form later on. Below this top section you will see 'Existing Forms'. This area will display all of the forms you have created using form manager. To see the fields and modify the properties as well as add new form elements click on the link Modify.

Form Fields

Underneath the link Site Forms in the site control panel you'll see the link Form Fields. Pressing this link will take you to a list of all of the different types of form fields which you can add to your forms. In the list you will see some of the following: add a form, text input, textarea, etc. Each of these fields are essentially self contained forms. In other words when you modify the 'text input' form, what you are modifying is the form that allows you to create a text input field in form manager. Unless you really know what you are doing we suggest to not modify any of these forms as doing say may break the forms on your site. Consider this to be an administrative control panel for Form Manager.

The form fields section is used to create the form fields in your forms. Let's say for example you wanted to add a 'phone' field so you can easily add it to your forms. You would first create a new form and give it the type 'phone'. You would then add the specific fields you wanted to create for a phone field for your forms. Another way to accomplish this is to create a "custom field" which we'll cover later on.

Pre-built Forms

Form manager ships with two pre-built forms: Contact Us and User Profile. If you are using the open source version of LogiCreate you can download the 'contactus' module located in the document library at http://www.logicreate.com. The contact us form is a very simple form which can be used to allow people to contact different departments of your business online. By installing the contact us module it will use this form automatically. The user profile form is used in the include LogiCreate module 'users' and is called by the service 'editProfile.lcp'. Feel free to modify these two forms to suite your needs for your site.

Creating a new form

At the top of the main page is the link Add a New Form. Pressing this link will take you to the form which allows you to create new forms. Let's cover the different options for this screen.

Enter the above information as need to create the initial foundation for your form. Essentially this is creating all of your default form properties of the form object (most all of which you can change inside your code at run-time if needed).

Adding fields to your form

Once you have created a form you are ready to start placing fields onto your form. From the main Site Forms page, the form you just created should appear in the list. Select the Modify link to the right of your new form. The next screen will give you a lot of different options. Let's cover what each of these are.

Form Management

This section will appear at the top of any form you are modifying.

Click below to add a Form Field to this form

Press any of the above options to add this field type to your form. As a web developer these should be self-explanatory. There are two special form fields listed above that we will cover that are form manager specific.

Custom fields - If you wish to create custom form fields for your site you will use the Custom Fields option. See the 'Creating Custom Fields' section for developer information on how to accomplish this.

Row - Although row is not a form field we use it to add form labels or help information to your forms. You can attach a style sheet to a row for extra decoration as well. For example if you have 15 fields on a form, usability testing shows it is best to break these up into 3 blocks of 5. With this in mind you may want to start with a row with "Step One - User information" and then later on add another row "Step Two - Optional Information" and so on.

Date Drop Down - Date drop down is a special form field created in form manager to handle just about any type of date or time you may need. Although it is a very advanced use of an extra field type, it is very useful and easy to use. Date drop down supports the following fields: month, day, year, hour, minutes, am/pm. You can select any combination of the fields needed and also determine the start and end dates for your year. The date drop down method in the form object will accept almost any type of date and pre-populate the drop downs with that date.

Check box - Creates a set of check box options in your form. This option creates one, or multiple check boxes.

Radio button - Creates a set of radio buttons options in your form. This option can be used to create one or multiple radio button options.

Submit button - Creates a submit button. (using images on submit buttons not currently supported)

Text Area - Creates a text area on your form. Also allows you to select the WYSIWYG option.

File Upload - Creates a form option to upload a file via a form.

Text Input - Creates a normal input form field.

Hidden - Creates a hidden field. In LogiCreate this is used primarily for triggering your next event.

Select - Creates different select options such as drop downs or multiple selects.

Creating a Form Field

There are a set of standard fields that we need to cover so you understand how to create the different form fields listed above. Below we cover most of the options when building a form. Not all of the options below are on every element.

• Enter the field name - This option is typically the name of your database field or the name of the field your data object is called. For example, if you are using PBDO as your data object and the field in the database is called "first_name", then you would use "firstName" in this field. If you are using other tools, adjust your name appropriately.
• Display Name - This is the name the user of your form will see. If the user is to enter their first name, then you would enter "First Name" for example.
• Is this a required field? - Select yes if your field is required and no if it is not. By selecting yes, an '*' will automatically appear next to this option to alert the user the option is required. Also, if the field is required, the user *MUST* adhere to the rules you have established in the additional fields covered next.
• Field size - This option is only found on the text input type of field. Enter how many characters long your text input field should be. Enter numbers only. For example, if you want someone to enter their state initials, set this to the value of 2.
• Maximum Field Length - This option is found on the text input type of field. Just because you set the field size to 2 characters, doesn't mean the person cannot enter more than 2 characters. The maximum field length equates to the 'maxlength' option in a text input field. You would want to enter 2 characters here as well to not allow the user to enter more than 2 characters for this field. Typically you will match this field with the length of your database. For example, if your database is a varchar(25) field, then you should enter 25 in this option so the user cannot enter more text than what is allowed in your database.
• Enter the default value for this form field - The default value is used on several different field types. On text input fields it is what will appear in the field automatically when the user first views the form. Any changes they make are then saved. On other fields such as a select drop down, this can assist in auto selecting a drop down field for example.
• Regular Expression - For those of you that are regular expression junkies, you can go wild here. If you need to validate this input field with a certain regular expression, then you can use this option to enter your regular expression. If the input the user enters fails this expression, the user is notified with an error.
• Choose form validation type - Be careful when selecting this option. For text input fields, you should typically use 'Default' or one of the pre-built regular expressions for you. If you are building a select drop down, you *MUST* choose "Select Drop Down" for this option. If you do not, this will cause your user to not be able to submit the form properly.
• Instructions or help - If you need to provide additional help enter the help in the area provided. Any text entered in this option will appear in the line below the form. Example (01-01-2002) to help the person know how you want the date entered.
• Strip HTML Tags? - If you do not want the user to enter HTML tags on the field, select Yes. Selecting yes will automatically remove any HTML tags from the field.
• Allowed HTML Tags - If you want to allow a few HTML tags, enter the tags in this option. This is only used if you have selected to strip the HTML tags. To allow bold tags for example you would enter <b></b>.
• Minimum Input Length - This field is only used if you are doing a 'required' field. Enter the minimum number of characters allowed for this field. To use the state example again, we must have 2 initials for all states so we would enter the number 2 here.
• Maximum Length Allowed - This field is only used if you are doing a 'required' field. Enter the maximum number of characters allowed for this field. This is typically set to the maximum number of characters allowed in your database or that is specific to your data type.
• Is this element checked? - Used on check boxes and radio buttons, select yes if you wish the element to automatically be checked for the user.
• Is this a multiple select form? - There are two types of select fields, one is a drop down, another is a multiple select box. Select yes to turn the select field into a multiple select field. All values that are selected by a user (by them holding down CTRL or the apple key) are returned as an array to the developer.
• Field Size - If you are doing a multiple select form, enter how many options you want to display to the user. For example, if you have 10 options, you may want to enter 5 so all 10 options are not displayed. If you are not doing a multiple select, the value of 1 should be entered.
• Use value instead of key - Depending on how you build your drop down options you may want to store the value instead of a key. For example, if you enter 1-Alabamba,2=Arizona, etc. for states. You may want to store Alabama in the DB not, 1. Selecting 'Yes' on this option will solve this. The word 'key / val' get their names from key value pairs.
• Enter your drop down options - To create drop down options you enter your key / value pairs separated with commas. Be sure you have no spaces. Here is an example: MI=Michigan,TX=Texas,FL=Florida,MS=Mississippi,LA=Louisiana When the user views the form they will see the names of the states as a drop down option.
• Enter number of cols / rows - Used on the text area form field, enter the number of columns and rows you wish to display for your text area.

Creating Custom Fields

As you create more complex forms you will find yourself needing to pull information from a database and render a dynamic drop or other information for example. Form Manager has the ability to accommodate the need for pulling dynamic information and displaying it in the form. The benefit for a developer, is once you create the custom field, you can apply it to any form.

Add field to drop down

1. Let's add the field to form manager so it can be selected in the "Custom Fields" option. To do this, select "Form Fields" in the site menu of Hercules.
2. Find the "Custom Fields" form and select "Modify".
3. Locate the field type of 'select' labeled as 'Select field type (extra)' and modify this field.
4. At the bottom of the page, locate the 'Enter your drop down options' field. Here you are going to enter the name of your custom function, and the drop down name. The 'key' corresponds to the name of the ToHTML method in the SiteForms.php object located in the lib directory. As an example, you should see groups=System Groups already listed. The key 'groups' corresponds directly to the method groupsToHTML() located in SiteForms.php. Name your key the name of your method but leave off the ToHTML as it is added automatically for you.
5. Save this change.
6. If you try adding a custom field to your form, you will now have the option you created.

Creating the method

After you get your new field added to form manager, it is time to start writing what you need to pull or generate. Here is the sample groupsToHTML().

The magic happens in the while loop above. We are pulling back the records we need and then are taking the group ids, and building the key / val string the way we normally do when creating select drop downs. The variable $v that is passed in, holds all of our form specific data. We simply override the $v['selectOptions'] element of the array with the data we need to use.

Integrating Forms Into Your Site / Applications

This section covers how to integrate form manager into your applications and your site. We are going to use the 'contactus' module which can be downloaded from the LogiCreate site via the document library as a starter example. If you haven't built or familiarized yourself with how LogiCreate applications or modules are built you will need to do so before continuing. This section assumes you understand how to build LogiCreate modules and how they are used.

Loading a form

Include SiteForms.php
The first step is to add the following to the top of your LCP file:

include_once(LIB_PATH.'SiteForms.php');

This will provide all of the code you need in order to use form manager. In fact, SiteForms.php includes the main library of LC_forms.php located in the lib directory.

Add a cleaned array property (optional)
You may or may not want to do this depending on how you are using form manager, but for starting out we recommend it. Adding this cleaned array property to your LCP object allows you to have access to the data in the object that has been cleaned after validation. When you validate a form manager form, it automatically cleans the input for you and doesn't return fields that are not allowed in the form. This protects against cross site attacks.

Example: var $cleanedArray = array();

Using the object
Here is the example used in the contact us module.

Let's look at the above example. First we instantiate the object. Next we load up the form via the getForm() method and pass it two parameters. The first one is the 'name' of the form. The second is the cleaned array. The second parameter to getForm() is optional. It is a key / value array of the data that we want to pre-populate our form with. The key's correspond to the field names. The first time this is run, there is nothing in $this->cleanedArray. As we'll see in the few sections, if there is an error after validation, we want to pre-populate the form with the information the user inputted. Whether you have a 3 or a 40 field form, the above three lines of code are all you need to display a form in LogiCreate. Notice that we are storing the form in the template variable so that we only have to echo out $t['form'] in our template. Form manager takes care of the rest.

Validating the Form Input

Once the user submits a form, your event in LogiCreate needs to validate the form input. If it doesn't pass inspection you will want to redirect the user back to the form, otherwise you continue on in your application. The following code shows you how this is done. In the 'contactus' module, this is called emailRun.

Once you instantiate the object call the validateForm() method and pass it the name of the form you wish to validate, and the information in the post var array ($arg->postvars). The validateForm() method loads up the form and then does a series of checking and cleaning the input. The result of this automated error checking returns an error message. As seen above we capture this error message in the template variable. Any information that was entered or selected by the user would automatically be saved as well. The way this gets saved and pushed back to the user is by grabbing the cleaned array from the form object and storing it into the LCP object.

Cleaned Array
The cleaned array that we mentioned earlier is what allows us to give the information back to the user if there is an error. If you notice in the first example we looked at $this->cleanedArray being passed as the second argument.

The cleaned array gets placed back into the object in your submission event. If you need to load information from a database to pre-populate a form, the same method is used.