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
parent
32b9b42f3a
commit
da8c5af6e5
34
README.md
34
README.md
|
|
@ -9,7 +9,7 @@ and without getting involved in any PHP code.
|
|||
|
||||
## Maintainer Contact
|
||||
|
||||
* Will Rossiter (Nickname: wrossiter, willr) `<will (at) fullscreen (dot) io>`
|
||||
* Will Rossiter (Nickname: wrossiter, willr) `<will (at) fullscreen (dot) io>`
|
||||
|
||||
## Requirements
|
||||
|
||||
|
|
@ -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,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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
|
|
@ -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.
|
||||
Loading…
Reference in New Issue