Quick Start Guide

Here we will run through a quick and dirty setup and install of func on the Django development server using the test harness provided in the application.

We'll start off by downloading the most recent version of formunculous.

After that, extract the tar.gz file to a convenient directory. In this instance, I'll be using the django directory in my home path on Linux. However, anywhere will work, and it shouldn't be too different for any other Python/Django supported OS.

After extracting the file, change into the formunculous-version/harness directory. The harness directory is there specifically for trying this type of stuff out.

To get everything running, now that we are in the right directory is just run:

python manage.py syncdb

You should then see something like:

cd django/formunculous-2.1.0-final/harness/
#[12:56:56] cgee@l1132a-pc01:~/django/formunculous-2.1.0-final/harness $
python manage.py syncdb

Creating table formunculous_applicationdefinition
Creating table formunculous_subapplicationdefinition
Creating table formunculous_fielddefinition
.
.
.
You just installed Django's auth system, which means you don't have any superusers defined.
Would you like to create one now? (yes/no): Please enter either "yes" or "no": yes

Go ahead and create a superuser account, and after it finishes installing indexes run:

python manage.py runserver

To get the built-in server running the application. You should see output similar to:

python manage.py runserver
Validating models...
0 errors found

Django version 1.1.1, using settings 'harness.settings'
Development server is running at http://127.0.0.1:8000/
Quit the server with CONTROL-C.
	

Take note of where the server is running. In this case it is running at http://127.0.0.1:8000/, so go ahead and hit that URL in a browser and you will see a wonderful error message ;).

You might notice the valid URLs that this is not. The harness is set to run at the apply/ URL by default, but we first want to head the /admin/ section, so hit http://127.0.0.1:8000/admin/ and login with the superuser account you created earlier.

We want to go ahead and add a form since we don't have any, so go ahead and click that link to start form creation.

Form Definition Creation

This creation form has quite a few definitions, and it may seem a bit confusing at first, but just type in a name, an e-mail, and the start and end dates and it should be good to go. The defaults are what we want them to be. For start and end dates, if we want to have the form active, should be before and after when you are working on this to be visible to the end user.

There are a few save options, but we'll go ahead and use Save and Edit Form since we will need to create the fields for our form. Here is where we are presented with the main form editing interface. This interface uses a lot of drag-and-drop, and java script AJAX functions, so we definitely need to have java script turned on in the browser.

We'll start by simply dragging over an Email Address field from the left side of the editor, and drop it into the gray box in the center in order to create a new field.

After the field has been dragged, all of the field options show up. Once again there are quite a few options here, but in general we don't have to worry about them. There are options for adding help text, whether the field is required, whether we want the field to show up in the review table, whether we want it to be a drop-down box, and any pre and post html markup we would like applied to it. For the e-mail field, we don't need any of this, so we just give it a label and move onto the next field.

For our contact form we would also like to ask for the subject of the inquiry, and the message they wish to send us. To do this, we just drag a Text Input field for the subject and a Large Text Area for the message. We name them both appropriately and then Save and Continue Editing. After saving, we preview the form to make sure everything looks right.

Make sure everything looks alright, and go ahead and Save and Finish to head back out to the Form Definitions section, noticing our new form in the list.

That's it, now it is just time to go ahead and fill out the form, and review the submission.

Using and Reviewing Forms

Go ahead and click on the Form Index link at the top right of the Form Definitions page to go to the end user's view of all the available forms.

If we created the form within an acceptable start and end date, we should see it listed on the Available Forms page.

Go ahead and click on the Contact Us link and fill out the form. You can always try putting in bad data to see how error's are handled.

Now that we have a form submitted, we can take a look at how reviewing forms works in Formunculous. Since we took the defaults when creating the form definition, our superuser account is not marked as a reviewing for this form, and thus we are unable to review the form. We want to go ahead and head back to the Django admin section and the Form Definitions page. Under the Actions header, we want to go ahead and choose the Change option to modify our definition.

Once here, we want to go ahead and scroll down to the Reviewers section and select our user account from the list. We may also choose to have reviewers notify, or any of the other options, now that we are more familiar with how forms work.

Once we are done, click Save and Finish and click on the Form Index link again. You'll notice there is a change in how this page looks. There has been a Review Forms tab added to the top of page, go ahead and click there, and notice that the Contact Us form shows up.

Here we are presented with the main form reviewing index page. There are links to export all the data as a spreadsheet (csv), download all the files associated with a form, and view any statistics retrieved from the form. The index is also search-able, sortable, and pages when there are more than 25 submissions (default). You can also delete and get detailed information for a specific form. Note that the fields presented here are those for which the Header option in the form editor has been selected.

For this instance we will go ahead and click on the contact us form we submitted earlier. On this page you will notice you see all of the submission fields (assuming they weren't all displayed on the index page), as well as the submission date and time of the form, the option to delete the form, and to add a comment.

It is important to note that as a feature, you can create fields that viewable and usable only by designated reviewers by adding a field normally and selecting the Reviewer option for the field. This can be extremely helpful for tracking what has been done with forms or adding additional information such as a responded to date.

That is pretty all there is to it. Obviously we created a very simple form, but there are tons of additional features we haven't covered and ways to create extremely complex and interesting forms in a fairly straight forward and simple manner.

Thank you for following along.