Update docs with images and better wording
Sourced from pre existing documentation
This commit is contained in:
Damian Mooyman
parent
e8e41826da
commit
3f91cf017a
Binary file not shown.
|
After Width: | Height: | Size: 50 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 58 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 47 KiB |
|
|
@ -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.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
|
||||
### 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).
|
||||
Loading…
Reference in New Issue