tonyair/silverstripe-userforms
1
0
Fork 0
mirror of https://github.com/silverstripe/silverstripe-userforms.git synced 2024-10-22 17:05:42 +02:00
Code Issues Projects Releases Wiki Activity

Update docs with images and better wording

Browse Source 
Sourced from pre existing documentation
This commit is contained in:
Damian Mooyman 2014-08-04 16:49:47 +12:00
parent e8e41826da
commit 3f91cf017a
4 changed files with 120 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
docs/en/_images/add-fields.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 50 KiB

BIN
docs/en/_images/create-new-form.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 58 KiB

BIN
docs/en/_images/form-in-content.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 47 KiB

184
docs/en/user-documentation.md
View File

@ -1,91 +1,131 @@
# User Documentation
Instructions on how to create, use, and maintain user forms in the CMS.
In this section:
## Setting up a User Form
* Learn how to create and edit forms
* Learn how to add fields to a form
* Learn how to view submissions and reply to them automatically
1. Create a page in the CMS of type 'User Defined Form'
2. Go to the 'Form' tab and select the fields you'd like to have displayed on your form.
1. For each field, select a type from the dropdown and press 'Add'
2. In the empty text box type out the label for the field.
3. Expand the "Show Options" to show additional options. Notes on options for each field can be found below.
4. Checking the "Is this field Required?" checkbox to make this field mandatory, and optionally set a custom
error message.
3. Set the thank you message under the 'Configuration' tab. This will be displayed to the user when they
successfully complete the form.
4. Setup recipients by clicking on the 'Configuration' tab.
1. Press the "Add Email Recipient" button and fill out the fields.
2. Setup the "Email subject" that the user would receive in their email.
3. Set the "Send email from" as an email address which exists on the same domain as your site.
E.g. if your site is www.example.com you would use contact@example.com.
4. The "Email for reply to" and "Send emails to" email address fields can either by typed out, or you can
select a form field to draw the value for that field from.
5. Alternatively, if submissions should be stored on the server only but not emailed, it is not necessary to
add any recipients, but ensure that the "Disable Saving Submissions" to server is unchecked. These can be
accessed or downloaded in CSV format on the "Submissions" tab.
## Before we begin:
## Field Types
* Make sure you are in the "Pages" section on the Navigation Tabs.
### Checkbox Field
## Creating and editing forms
A basic check (boolean) field to store a true or false value.
To create a new form, first decide where in the site you want your form to be. If you
would like your form to be a "subpage" of an already existing page, click on the
parent page in the left-hand Page Tree in the Contents Pane you would like to
create the subpage in. If you want your form to be in the top level navigation
for your site, you should click on the root of the site - the first item listed
in the Contents Pane.
On the top of the Contents Pane, you will find a button marked "Create." Click it, and a
drop-down menu will show up. Select "User Defined Form" Then hit the "Go" button.
![Create new form](_images/create-new-form.png)
You will notice that a new page has been created, with the name of "New UserDefinedForm."
Simply click on the new page in the content page to bring it up in the editing pane.
<div class="note" markdown="1">
### Notes:
Don't worry if you create your page in the "wrong" place. Pages can be moved and re-ordered
easily, and we will cover that under "Managing Your Site."
</div>
## Combining forms and content
Much like editing any form page, you can add context, such as text or images, in the Main
section of the Contents tab on in the Editing Pane. Form pages are slightly different,
however. You will notice in a newly created form page, there is some text in the content
of the editing menu to begin with: "$UserDefinedForm"
The purpose of this little block of text is to tell the website where in the page you
would like to put the form. The form will appear on the website wherever the "$UserDefinedForm"
appears in the editing pane, whether it is before text, after text, inside a table, etc.
If $UserDefinedForm is deleted by accident or on purpose, SilverStripe automatically
puts the form at the end of all the content.
![Form in content](_images/form-in-content.png)
## Adding fields
To add a field to the form, click on the "Form" tab under the "Content" tab in the
Editing Pane. Select the type of field you want to add from the drop-down menu and
press the "Add" button. You can label any field by typing in the appropriate label field in the backend.
![Adding fields](_images/add-fields.png)
### Field types
#### Checkbox Field
Selecting a checkbox field adds a single checkbox to a form, along with a place to
store a label for that checkbox. This is useful for getting information that has a
"Yes or No" answer, such as "Would you like to be contacted?" or "Have you
understood the Terms and Conditions?"
Marking this field as required will require it to be checked.
### Checkbox Group
#### Checkbox Group
Enables a set of options to be displayed, grouped together under a common title.
Once this field has been added you can add each of the sub-options by clicking "Show Options"
and then "Add Option". Each sub-option can only be assigned a single string value.
Selecting a checkbox group adds a field for multiple checkboxes to a form, along with a
place to store a label for the group. This is useful for getting information that has
multiple discrete answers, such as "Which continents have you visited?" or "Which
software programs do you use on a daily basis?" You will need to click on the "Show
options" link to add user-selectable options.
Marking this field as required will require at least one option to be checked.
### Country Dropdown
#### Country Dropdown
A list of all countries drawn from the internal list of known countries.
### Date Field
#### Date Field
A date entry field. This does not include time.
Selecting a date field adds a field for a date in a form. The time of day is not selectable, however.
If your theme enables it, a date picker popup will be displayed to the user on the frontend.
### Dropdown Field
#### Dropdown Field
A dropdown list field.
Selecting a drop-down field adds a dropdown field to a form. This is useful for getting
information that has only one answer among several discrete choices, for example,
"Which region do you live in?" or "What subject is your question about?" You will
need to click on the "Show options" link to add user-selectable options.
Once this field has been added you can add each of the options by clicking "Show Options"
and then "Add Option". Each sub-option can only be assigned a single string value.
#### Email Field
### Email Field
Selecting an Email field adds a textbox where an email address can be entered. Using the Email
field, instead of a normal text field, to store email addresses, allows you to use that email
address in many automated tasks. For example, it allows the CMS to send reply email
automatically when a form is filled out.
A text field with email address validation.
#### File Upload Field
### File Upload Field
Enables the user to attach a file to their submission.
Selecting a File Upload Field adds a field where users can upload a file from their
computers. This is useful for getting documents and media files.
The folder that this field uploads to can be customised by selecting "Show Options"
and then selecting a new folder from the "Select upload folder" option. If no folder
is selected it will upload by default to the "Uploads" folder.
### Heading Field
#### Heading
This inserts a fixed heading into your form, and is not a field editable by the user.
Once this field has been added you can select a heading level (1 to 6) by clicking
"Show Options" and using the "Select Heading Level" field.
Selecting a Heading allows adds a place where you can put a heading for a form, or for
a section of your form. You can choose which level of heading to use (from 1-6) from
the "Show options" link.
If you do not check the "Hide from reports" checkbox then this field will be displayed
in submission reports.
### HTML Block
#### HTML Block
This inserts a fixed block of HTML into your form, and is not a field editable by the user.
Once this field has been added you can change the content of the HTML by clicking
"Show Options" and entering your content into the "HTML" field.
Selecting an HTML block allows you to add any HTML code you wish into your form.
You can edit the HTML blog from the "Show options" link.
If you do not check the "Hide from reports" checkbox then this field will be displayed
in submission reports.
@ -93,28 +133,44 @@ in submission reports.
Note: Take care not to allow input from unauthorised sources or users, as custom script
or code could be injected into your form.
### Member List Field
#### Member List Field
This displays a dropdown list containing all users that belong to the specified group.
To set the group to display, after adding this field to your form, click "Show Options"
and select the source group under the "Group" field.
Selecting a Member List Field adds a dropdown field which includes various groups of website
members (such as administrators or forum members) to the form. You can choose which group
of members from the "Show Options" link.
Note: Take care that you do not expose confidential or personal information about your CMS
or front end users as these names will become publicly visible.
### Numeric Field
#### Numeric Field
A basic text field that will only accept numeric values (numbers and decimals only).
### Radio Field
#### Radio Field
A list of options, similar to the Checkbox Set Field, but one which allows only a single value to
be selected from a list.
Selecting a Radio field adds a field filed with "Radio button" options to a form.
Radio buttons are similar to checkboxes, except that only one button in a radio
field can be checked at a time. This is useful for getting information that has
only one answer among several discrete choices, for example, "What country do
you live in?" or "What subject is your question about?" It is similar to a
dropdown field, but it is more useful for providing larger labels to responses.
For example, a dropdown field may have one or two-word inputs, while a radio
button may have choices that are paragraphs in length. You will need to click
on the "Show options" link to add user-selectable options.
Once this field has been added you can add each of the sub-options by clicking "Show Options"
and then "Add Option". Each sub-option can only be assigned a single string value.
#### Text Field
### Text Field
Selecting a Text field adds a text field to the form. You can click on "Show options"
to determine the size and the number of rows in a text field.
A basic text field.
**Put another way, if you'd like to create a question that...**
* Has a yes or no answer - use [Checkbox Field](#checkbox-field).
* Has multiple possible answers, from a list of choices - use [Checkbox Group](#checkbox-group).
* Has one answer, from a list of choices - use [Dropdown Field](#dropdown-field) (for short answers) or
[Radio Field](#radio-field) (for longer answers).
* Requires a written answer - use [Text Field](#text-field).
**Or perhaps you'd like to add informational content to your form?**
* Use [HTML Block](#html-block), with the appropriate level [Heading](#heading).