DOCS Update dev and userguide docs for SS4, new screenshots, etc

This commit is contained in:
Robbie Averill 2017-09-20 16:31:12 +12:00
parent 96c1cc5986
commit 98731f42b6
16 changed files with 65 additions and 109 deletions

View File

@ -1,29 +1,23 @@
# Compiling Front-End Files # Compiling front-end files
UserForms stylesheets are written in SASS, so to make changes you'll need to have Compass installed. UserForms stylesheets are written in SASS and JavaScript follows ES6 syntax. Both are compiled with Webpack into distributable, minified files.
## Debian/Ubuntu To get started, you will first need NodeJS, NPM, Webpack and Yarn installed. For more information on this process, [see "Build Tooling" in the SilverStripe documentation](https://docs.silverstripe.org/en/4/contributing/build_tooling/).
## Watching for changes
As you make changes to SASS or JavaScript, you can ask Yarn to watch and rebuild the deltas as their are saved:
```sh ```sh
$ apt-get update yarn watch
$ apt-get install ruby
$ gem install compass
``` ```
## OSX This will not minify the dist files.
[Install homebrew](http://brew.sh). Then: ## Compile assets for production
When you're happy with your changes and are ready to make a pull request you should run a "build" command to compile and minify everything:
```sh ```sh
$ brew update yarn build
$ brew install ruby
$ gem install compass
```
## Compile assets
Make your changes to `scss/UserForm.scss` or `scss/UserForm_cms.scss`. Then navigate to the `userforms` folder and run:
```sh
$ compass compile
``` ```

View File

@ -1,28 +1,20 @@
# Installation # Installation
Installation can be done either by composer or by manually downloading a release. Installation should be done using Composer:
## Via composer ```
composer require silverstripe/userforms
`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.
5. Install the dependencies. See the "require" section of [composer.json](https://github.com/silverstripe/silverstripe-userforms/blob/master/composer.json)
## Configuration ## Configuration
After installation, make sure you rebuild your database through `dev/build`. 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. You should see a new page type in the CMS called 'User Defined Form'. This has a new 'Form' tab which has your form builder.
## File Uploads and Security ### File uploads and security
The module optionally allows adding a "File Upload Field" to a form. The module allows adding a "File Upload Field" to a form.
The field enables users of this form to upload files to the website's assets The field enables users of this form to upload files to the website's assets
so they can be viewed later by CMS authors. Small files so they can be viewed later by CMS authors. Small files
are also attached to the (optional) email notifications are also attached to the (optional) email notifications
@ -33,63 +25,37 @@ and default to a safe set of files (e.g. disallowing `*.php` uploads).
You can define further exclusions through the `EditableFileField.allowed_extensions_blacklist` You can define further exclusions through the `EditableFileField.allowed_extensions_blacklist`
configuration setting. configuration setting.
The allowed upload size can be set in the cms as long as it doesn't exceed the PHP configuration The allowed upload size can be set in the CMS as long as it doesn't exceed the PHP configuration
for this website (the smaller value of `upload_max_filesize` or `post_max_size`). for this website (the smaller value of `upload_max_filesize` or `post_max_size`).
The field is disabled by default since implementors need to determine how files are secured. ### Securing uploaded files
Since uploaded files are kept in `assets/` folder of the webroot, there is no built-in
permission control around who can view them. It is unlikely By adding a File Upload Field to your user form you can allow your website users to upload files, which will be stored in a user-defined folder in your SilverStripe system. You can access these files via the "Submissions" tab, or from the "Files" area in the admin interface.
that website users guess the URLs to uploaded files unless
they are specifically exposed through custom code. Please be aware that the responsibility of choosing a folder for files to be uploaded into is that of the CMS user. You can set the necessary "can view" permissions for the folder you create and/or choose via the "Files" section, then select that folder in the settings for the File Upload Field in your form.
If you choose a folder that anyone can view you may be exposing files uploaded via your form to the public, as well as anyone with access to the CMS.
You should think carefully about the use case for file uploads. You should think carefully about the use case for file uploads.
Unauthorised viewing of files might be desired, e.g. submissions for public competitions. Unauthorised viewing of files might be desired, e.g. submissions for public competitions.
In other cases, submissions could be expected to contain private data. In other cases, submissions could be expected to contain private data.
In order to enable this field it is advisable to install the
[secureassets](http://addons.silverstripe.org/add-ons/silverstripe/secureassets) module.
This can be done using the below composer command:
```
composer require silverstripe/secureassets ~1.0.4
```
This step will have the following effects:
* The "File Upload Field" will be enabled through the CMS interface
* By default any new file upload fields will be assigned to a default folder, `SecureUploads`,
which can only be accessed by admins.
* Any existing file upload fields, if they are not assigned to a folder, will now upload
to this folder.
* Any existing file upload fields which are assigned folders will have the security settings
for those folders updated so that only admins can access them.
This functionality can be configured in the following ways:
* Assigning another group to the `SecureUploads` folder will allow users from that group
(rather than admins only) to access those files.
* The folder name can be configured using the `EditableFileField.secure_folder_name` config option.
* Security functionality can be disabled (although this is not advisable) by setting
`EditableFileField.disable_security` to true.
### Custom email templates ### Custom email templates
If you want to use custom email templates set the following config option. If you want to use custom email templates set the following config option.
```` ```yaml
UserDefinedForm: SilverStripe\UserForms\Model\UserDefinedForm:
email_template_directory: your/template/path/ email_template_directory: mysite/templates/custom_userforms_emails/
```` ```
Any SilverStripe templates placed in your `email_template_directory` directory will be available for use with submission emails. Any SilverStripe templates placed in your `email_template_directory` directory will be available for use with submission emails.
### Custom Multi-Step button Text ### Custom multi-step button text
If you want to change the button text when using the Multi-Step/Page Break feature, simply add the following to your `config.yml`: If you want to change the button text when using the Multi-Step/Page Break feature, simply add the following to your `config.yml`:
```` ```yaml
UserForm: SilverStripe\UserForms\Form\UserForm:
button_text: 'Your Text Here' button_text: 'Your Text Here'
```` ```

View File

@ -5,23 +5,23 @@ Check the below if you have any issues during installation or use
## Installation Issues ## Installation Issues
After installation make sure you have done a `dev/build` you may also need to flush the admin view by appending 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` `?flush=1` to the URL, e.g. `http://yoursite.com/admin?flush=1`
## UserForms EditableFormField Column Clean task ## UserForms EditableFormField Column Clean task
This task is used to clear unused columns from EditableFormField This task is used to clear unused columns from EditableFormField database tables.
The reason to clear these columns is because having surplus forms can break form saving. 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, 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 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. are surplus.
To run the task login as Admin and go to to http://yoursite/dev/tasks/UserFormsColumnCleanTask To run the task, log in as an administrator and go to to http://yoursite/dev/tasks/UserFormsColumnCleanTask in your browser, or run `sake dev/tasks/UserFormsColumnCleanTask` from the command line.
## My CSV export times out or runs out of memory ## My CSV export times out or runs out of memory
You likely have too many submissions to fit within the PHP constraints You likely have too many submissions to fit within the PHP constraints
on your server (execution time and memory). If you can't increase these limits, on your server (execution time and memory). If you can't increase these limits,
consider installing the [gridfieldqueuedexport](https://github.com/silverstripe/silverstripe-gridfieldqueuedexport) module. It uses [queuedjobs](https://github.com/silverstripe-australia/silverstripe-queuedjobs) to export consider installing the [gridfieldqueuedexport](https://github.com/silverstripe/silverstripe-gridfieldqueuedexport) module. It uses [queuedjobs](https://github.com/symbiote/silverstripe-queuedjobs) to export
submissions in the background, providing users with a progress indicator. submissions in the background, providing users with a progress indicator.

Binary file not shown.

Before

Width:  |  Height:  |  Size: 37 KiB

After

Width:  |  Height:  |  Size: 24 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 40 KiB

After

Width:  |  Height:  |  Size: 31 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 58 KiB

After

Width:  |  Height:  |  Size: 75 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 49 KiB

After

Width:  |  Height:  |  Size: 41 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 47 KiB

After

Width:  |  Height:  |  Size: 54 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 45 KiB

After

Width:  |  Height:  |  Size: 26 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 82 KiB

After

Width:  |  Height:  |  Size: 11 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 49 KiB

After

Width:  |  Height:  |  Size: 39 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 169 KiB

After

Width:  |  Height:  |  Size: 44 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 48 KiB

After

Width:  |  Height:  |  Size: 32 KiB

View File

@ -12,18 +12,16 @@ drop-down menu will show up. Select "User Defined Form" Then hit the "Go" button
![Create new form](_images/create-new-form.png) ![Create new form](_images/create-new-form.png)
You will notice that a new page has been created, with the name of "New UserDefinedForm." You will notice that a new page has been created, with the name of "New User Defined Form." You will be taken to edit the page once you click "Create."
Click on the new page in the content page to bring it up in the editing pane.
<div class="note" markdown="1"> <div class="note" markdown="1">
Don't worry if you create your page in the "wrong" place. Pages can be moved and re-ordered 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." easily.
</div> </div>
## Combining forms and content ## Combining forms and content
Much like editing any form page, you can add context, such as text or images, in the Main 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, 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 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" of the editing menu to begin with: "$UserDefinedForm"
@ -32,7 +30,7 @@ The purpose of this little block of text is to tell the website where in the pag
would like to put the form. The form will appear on the website wherever the "$UserDefinedForm" 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. 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 If $UserDefinedForm is deleted by accident (or on purpose), SilverStripe automatically
puts the form at the end of all the content. puts the form at the end of all the content.
![Form in content](_images/form-in-content.png) ![Form in content](_images/form-in-content.png)
@ -46,18 +44,18 @@ Save or publish the form to start editing your new field's properties.
To get details of the available form fields and what they do see [form field type documentation](field-types.md) To get details of the available form fields and what they do see [form field type documentation](field-types.md)
## Adding fieldgroups ## Adding field groups
Creating fieldgroups is as simple as clicking the 'Add fieldgroup' button, this create two 'markers' which act as the beginning/end for the fieldgroup. Any fields place between these two markers will be automatically included within the fieldgroup. Creating field groups is as simple as clicking the 'Add Field Group' button. This creates two 'markers' which act as the beginning and end for the field group. Any fields place between these two markers will be automatically included within the field group.
![Adding fieldgroups](_images/fieldgroups.png) ![Adding fieldgroups](_images/fieldgroups.png)
## Validation messages ## Validation messages
Validation messages are displayed below invalid fields by default. By checking the 'Display error messages above the form' Validation messages are displayed below invalid fields by default. By checking the 'Display error messages above the form'
option, an additional set of validation messages are displayed, at the top of the form. option in the 'Configuration' tab, an additional set of validation messages are displayed at the top of the form.
When a user submits an invalid form, they are directed to the top of the form, where they can review the messages. When a user submits an invalid form they are directed to the top of the form where they can review the messages.
Each message links to it's corresponding field so users can easily make the required changes. Each message links to it's corresponding field so users can easily make the required changes.
## Configuration ## Configuration

View File

@ -1,6 +1,6 @@
# Field types # Field types
## Checkbox Field ## Checkbox Field
Selecting a checkbox field adds a single checkbox to a form, along with a place to 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 store a label for that checkbox. This is useful for getting information that has a
@ -39,7 +39,7 @@ need to click on the "Show options" link to add user-selectable options.
## Email Field ## Email Field
Selecting an Email field adds a textbox where an email address can be entered. Using the Email 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 field to store email addresses instead of a normal text field allows you to use that email
address in many automated tasks. For example, it allows the CMS to send reply email address in many automated tasks. For example, it allows the CMS to send reply email
automatically when a form is filled out. automatically when a form is filled out.
@ -56,6 +56,8 @@ Only certain file extensions are considered safe for upload,
e.g. webserver script files will be denied but images will be allowed. e.g. webserver script files will be denied but images will be allowed.
The webserver environment also imposes a limit on file size by default. The webserver environment also imposes a limit on file size by default.
You can set any permissions requirements on the upload folder by finding it in the "Files" area, clicking on it to edit and going to the "Permissions" tab.
## Heading ## Heading
Selecting a Heading allows adds a place where you can put a heading for a form, or for Selecting a Heading allows adds a place where you can put a heading for a form, or for
@ -112,7 +114,7 @@ to determine the size and the number of rows in a text field.
**Put another way, if you'd like to create a question that...** **Put another way, if you'd like to create a question that...**
* Has a yes or no answer - use [Checkbox Field](#checkbox-field). * 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 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 * Has one answer, from a list of choices - use [Dropdown Field](#dropdown-field) (for short answers) or
[Radio Field](#radio-field) (for longer answers). [Radio Field](#radio-field) (for longer answers).
@ -120,4 +122,4 @@ to determine the size and the number of rows in a text field.
**Or perhaps you'd like to add informational content to your form?** **Or perhaps you'd like to add informational content to your form?**
* Use [HTML Block](#html-block), with the appropriate level [Heading](#heading). * Use [HTML Block](#html-block), with the appropriate level [Heading](#heading).

View File

@ -55,18 +55,18 @@ You can check this if you do not wish for the email recipient to see the form su
You can check this if you want to remove all of the HTML from the email, this means the email You can check this if you want to remove all of the HTML from the email, this means the email
will have no custom styling and the recipient will only see the plain text. will have no custom styling and the recipient will only see the plain text.
If `Send email as plain text?` is unselected, several additional options for HTML editing are displayed. If "Send email as plain text?" is unselected, several additional options for HTML editing are displayed.
If sending as HTML, there is the option to preview the HTML that is sent in the editor. Additionally, a HTML If sending as HTML, there is the option to preview the HTML that is sent in the editor. Additionally an HTML
template can be selected to provide a standard formatted email to contain the editable HTML content. template can be selected to provide a standard formatted email to contain the editable HTML content.
The list of available templates can be controlled by specifying the folder for these template files in yaml config. The list of available templates can be controlled by specifying the folder for these template files in YAML config.
:::yaml ```yaml
UserDefinedForm: UserDefinedForm:
email_template_directory: mysite/templates/useremails/ email_template_directory: mysite/templates/useremails/
```
### Custom Rules ### Custom Rules
@ -85,7 +85,3 @@ This decides whether to send the email based on two options
* Select the field which you want the custom rule to apply to * Select the field which you want the custom rule to apply to
* Select the condition the field must follow * Select the condition the field must follow
* enter for the condition (the 'is blank' and 'is not blank' conditions do not require any text) * enter for the condition (the 'is blank' and 'is not blank' conditions do not require any text)