Added user documentation.

Split README.md and docs/en/index.md so that One is targeted towards users visiting the github repo, and the other for browsing a documentation repository.
This commit is contained in:
Damian Mooyman 2014-07-22 14:03:03 +12:00
parent 32b9b42f3a
commit da8c5af6e5
6 changed files with 209 additions and 21 deletions

View File

@ -27,39 +27,31 @@ and without getting involved in any PHP code.
## Installation
Installation can be done either by composer or by manually downloading a release.
### Via composer
```
composer require "silverstripe/userforms:dev-master"
```
`composer require "silverstripe/userforms:*"`
### Manually
1. Download the module from the link above.
1. Download the module from [the releases page](https://github.com/silverstripe/silverstripe-userforms/releases).
2. Extract the file (if you are on windows try 7-zip for extracting tar.gz files
3. Make sure the folder after being extracted is named 'userforms'
4. Place this directory in your sites root directory. This is the one with framework and cms in it.
### Configuration
After installation, make sure you rebuild your database through `dev/build`. You should see a new PageType in the CMS 'User Defined Form'. This has a new 'Form' tab which has your form builder.
After installation, make sure you rebuild your database through `dev/build`.
## Troubleshooting
You should see a new PageType in the CMS 'User Defined Form'. This has a new 'Form' tab which has your form builder.
After installation make sure you have done a `dev/build` you may also need to flush the admin view by appending `?flush=1` to the URL like `http://yoursite.com/admin?flush=1`
## Documentation
## Tasks
### UserForms EditableFormField Column Clean task ###
This task is used to clear unused columns from EditableFormField
The reason to clear these columns is because having surplus forms can break form saving.
Currently it only supports MySQL and when it is run it queries the EditableFormField class for the valid columns,
it then grabs the columns for the live database it will create a backup of the table and then remove any columns that
are surplus.
To run the task login as Admin and go to to http://yoursite/dev/tasks/UserFormsColumnCleanTask
* [Index](docs/en/index.md)
* [Installation instructions](docs/en/installation.md)
* [Troubleshooting](docs/en/troubleshooting.md)
* [User Documentation](docs/en/user-documentation.md)
## Thanks

0
docs/_manifest_exclude Normal file
View File

36
docs/en/index.md Normal file
View File

@ -0,0 +1,36 @@
# UserForms
UserForms enables CMS users to create dynamic forms via a drag and drop interface
and without getting involved in any PHP code.
## Maintainer Contact
* Will Rossiter (Nickname: wrossiter, willr) `<will (at) fullscreen (dot) io>`
## Requirements
* SilverStripe 3.1
## Features
* Construct a form using all major form fields (text, email, dropdown, radio, checkbox..)
* Ability to extend userforms from other modules to provide extra fields.
* Ability to email multiple people the form submission
* View submitted submissions and export them to CSV
* Define custom error messages and validation settings
* Optionally display and hide fields using javascript based on users input
* Pre fill your form fields, by passing your values by url (http://yoursite.com/formpage?EditableField1=MyValue)
## Documentation
* [Installation instructions](installation.md)
* [Troubleshooting](troubleshooting.md)
* [User Documentation](user-documentation.md)
## Thanks
I would like to thank everyone who has contributed to the module, bugfixers,
testers, clients who use the module and everyone that submits new features.
A big thanks goes out to [Jan Düsedau](http://eformation.de) for drawing
the custom icon set for the form fields.

20
docs/en/installation.md Normal file
View File

@ -0,0 +1,20 @@
# Installation
Installation can be done either by composer or by manually downloading a release.
## Via composer
`composer require "silverstripe/userforms:*"`
## Manually
1. Download the module from [the releases page](https://github.com/silverstripe/silverstripe-userforms/releases).
2. Extract the file (if you are on windows try 7-zip for extracting tar.gz files
3. Make sure the folder after being extracted is named 'userforms'
4. Place this directory in your sites root directory. This is the one with framework and cms in it.
## Configuration
After installation, make sure you rebuild your database through `dev/build`.
You should see a new PageType in the CMS 'User Defined Form'. This has a new 'Form' tab which has your form builder.

View File

@ -0,0 +1,20 @@
# Troubleshooting
Check the below if you have any issues during installation or use
## Installation Issues
After installation make sure you have done a `dev/build` you may also need to flush the admin view by appending
`?flush=1` to the URL like `http://yoursite.com/admin?flush=1`
## UserForms EditableFormField Column Clean task
This task is used to clear unused columns from EditableFormField
The reason to clear these columns is because having surplus forms can break form saving.
Currently it only supports MySQL and when it is run it queries the EditableFormField class for the valid columns,
it then grabs the columns for the live database it will create a backup of the table and then remove any columns that
are surplus.
To run the task login as Admin and go to to http://yoursite/dev/tasks/UserFormsColumnCleanTask

View File

@ -0,0 +1,120 @@
# User Documentation
Instructions on how to create, use, and maintain user forms in the CMS.
## Setting up a User Form
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.
## Field Types
### Checkbox Field
A basic check (boolean) field to store a true or false value.
Marking this field as required will require it to be checked.
### 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.
Marking this field as required will require at least one option to be checked.
### Country Dropdown
A list of all countries drawn from the internal list of known countries.
### Date Field
A date entry field. This does not include time.
If your theme enables it, a date picker popup will be displayed to the user on the frontend.
### Dropdown Field
A dropdown list field.
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
A text field with email address validation.
### File Upload Field
Enables the user to attach a file to their submission.
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
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.
If you do not check the "Hide from reports" checkbox then this field will be displayed
in submission reports.
### 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.
If you do not check the "Hide from reports" checkbox then this field will be displayed
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
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.
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
A basic text field that will only accept numeric values (numbers and decimals only).
### 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.
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
A basic text field.