diff --git a/README.md b/README.md index 3ebf531..0009f8a 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ and without getting involved in any PHP code. ## Maintainer Contact - * Will Rossiter (Nickname: wrossiter, willr) `` + * Will Rossiter (Nickname: wrossiter, willr) `` ## 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 diff --git a/docs/_manifest_exclude b/docs/_manifest_exclude new file mode 100644 index 0000000..e69de29 diff --git a/docs/en/index.md b/docs/en/index.md new file mode 100644 index 0000000..49ccb27 --- /dev/null +++ b/docs/en/index.md @@ -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) `` + +## 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. diff --git a/docs/en/installation.md b/docs/en/installation.md new file mode 100644 index 0000000..7c93fc5 --- /dev/null +++ b/docs/en/installation.md @@ -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. diff --git a/docs/en/troubleshooting.md b/docs/en/troubleshooting.md new file mode 100644 index 0000000..2c655ee --- /dev/null +++ b/docs/en/troubleshooting.md @@ -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 diff --git a/docs/en/user-documentation.md b/docs/en/user-documentation.md new file mode 100644 index 0000000..21fd331 --- /dev/null +++ b/docs/en/user-documentation.md @@ -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.