Merge pull request #662 from creative-commoners/pulls/5.0/update-docs

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

code/Form/UserForm.php

@@ -17,6 +17,12 @@ use SilverStripe\UserForms\FormField\UserFormsFieldList;
  */
 class UserForm extends Form
 {
+    /**
+     * @config
+     * @var string
+     */
+    private static $button_text = '';
+
     /**
      * @param Controller $controller
      * @param string $name

code/Model/EditableFormField.php

@@ -237,15 +237,14 @@ class EditableFormField extends DataObject
                 CheckboxField::create('ShowInSummary', _t(__CLASS__.'.SHOWINSUMMARY', 'Show in summary gridfield')),
                 LiteralField::create(
                     'MergeField',
-                    _t(
+                    '<div class="form-group field readonly">' .
-                        __CLASS__.'.MERGEFIELDNAME',
+                        '<label class="left form__field-label" for="Form_ItemEditForm_MergeField">'
-                        '<div class="field readonly">' .
+                            . _t(__CLASS__.'.MERGEFIELDNAME', 'Merge field')
-                            '<label class="left">' . _t(__CLASS__.'.MERGEFIELDNAME', 'Merge field') . '</label>' .
+                        . '</label>'
-                            '<div class="middleColumn">' .
+                        . '<div class="form__field-holder">'
-                                '<span class="readonly">$' . $this->Name . '</span>' .
+                            . '<span class="readonly" id="Form_ItemEditForm_MergeField">$' . $this->Name . '</span>'
-                            '</div>' .
+                        . '</div>'
-                        '</div>'
+                    . '</div>'
-                    )
                 ),
                 TextField::create('Title', _t(__CLASS__.'.TITLE', 'Title')),
                 TextField::create('Default', _t(__CLASS__.'.DEFAULT', 'Default value')),

docs/en/compiling-front-end-files.md

@@ -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
-$ 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
-$ 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
 ```

docs/en/installation.md

@@ -1,28 +1,20 @@
 # 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
 
 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
 so they can be viewed later by CMS authors. Small files
 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`
 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`).
 
-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.
 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 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
 
 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.
 
-### 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`:
 
-````
+```yaml
-UserForm:
+SilverStripe\UserForms\Form\UserForm:
   button_text: 'Your Text Here'
-````
+```

docs/en/troubleshooting.md

@@ -5,23 +5,23 @@ 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`
+`?flush=1` to the URL, e.g. `http://yoursite.com/admin?flush=1`
 
 ## 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.
 
 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.
 
-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
 
 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,
-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.

docs/en/userguide/creating-and-editing-forms.md

@@ -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)
 
-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">
 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>
 
 ## 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,
 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"
@@ -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"
 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.
 
 ![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)
 
-## 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)
 
 ## Validation messages
 
 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.
 
 ## Configuration

docs/en/userguide/field-types.md

@@ -39,7 +39,7 @@ need to click on the "Show options" link to add user-selectable options.
 ## 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
+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
 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.
 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
 
 Selecting a Heading allows adds a place where you can put a heading for a form, or for

docs/en/userguide/form-submissions.md

@@ -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
 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.
 
-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/
-
+```
 
 ### 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 condition the field must follow
 * enter for the condition (the 'is blank' and 'is not blank' conditions do not require any text)
-
-
-
-