Update documentation

README.md

@@ -2,47 +2,42 @@
 
 Decorate textarea fields with the [Trumbowyg](https://github.com/Alex-D/Trumbowyg) editor.
 
-Trumbowyg is "A lightweight and amazing WYSIWYG JavaScript editor - 20kB only (8kB gzip)"
-
-It is useful for gathering content where some form of formatting in HTML is required.
-
 This module supports:
-+ content sanitising of submitted content (on the client side and server side)
++ content sanitising of submitted content on the client side using Trumbowyg configuration rules and server side using [HTMLPurifier](https://github.com/ezyang/htmlpurifier))
 + restricted feature set by default ([see documentation](./docs/en/001_index.md))
 
-The module will not support:
+## Use cases
+
+This editor field is useful for gathering content where some form of formatting in HTML is required. It is not intended for use in the administration area (although PRs are welcome for that, for example a restricted content editing field)
+
+As the goal is only a restricted feature set for simple content submissions, the module will not support:
+
 + file uploads
 + image uploads
 + image insertion
 
-Please use dedicated upload fields for that purpose.
-
-This field is not intended for use in the administration area (although PRs are welcome for that)
+Please use dedicated upload fields for handling file uploads.
 
 ## Requirements
 
+Per [composer.json](/composer.json):
+
 + silverstripe/framework ^4
-+ php-xml extension
-+ Trumbowyg depends on jQuery (latest at time of release)
++ jQuery 3.6.0
+
+The field pulls in required Trumbowyg JS and CSS assets from [cdnjs.com](https://cdnjs.com) along with their respective Sub Resource Integrity (SRI) hashes.
 
-The field pulls in required JS and CSS assets from [cdnjs.com](https://cdnjs.com) along with their respective Sub Resource Integrity hashes.
+If you wish to use your own jQuery, set the  `TrumboywgEditorField.use_own_jquery` configuration value to `true` in your project configuration.
 
 ## Installation
 
-```bash
+```shell
 composer require nswdpc/silverstripe-trumbowyg
 ```
 
 ## Usage
 
-```php
-use NSWDPC\Utilities\Trumbowyg\TrumboywgEditorField;
-
-// TrumboywgEditorField extends TextareaField
-$field = TrumboywgEditorField::create('MyEditorField', 'Write something')
-            ->setDescription("This is a description")
-            ->setRightTitle("This is a right title");
-```
+See [the basic example](./docs/en/01_index.md#basic-example)
 
 ## License
 

docs/en/001_index.md

@@ -24,8 +24,6 @@ By default the following tags are allowed in the editor (see _config/config.yml)
 - strong
 - em
 - br
-- h1
-- h2
 - h3
 - h4
 - h5
@@ -37,7 +35,7 @@ By default the following tags are allowed in the editor (see _config/config.yml)
 - strike
 ```
 
-These are also used when saving the field value in the backend.
+Only the `href` attribute is allowed (for links), with http or https schemes.
 
 If no configuration value `tagsToKeep` is available or it is empty, a default set is used. The fallback condition is to restrict to '<p>' tags only.
 
@@ -55,8 +53,7 @@ $options = [
     "autogrow" => true, // allow the text edit zone to extend
     "buttons" => [
         [ "undo", "redo" ],
-        [ "formatting" ], // basic formatting
-        [ "strong", "em" ], // semantic strong and emphasis
+        [ "p","h3", "h4", "h5", "strong", "em" ], // basic formatting
         [ "link", "" ], // support adding <a> links
         [ "unorderedList", "orderedList" ], // ul and ol
         [ "removeformat" ], // clear all formatting to assist with removing cruft
@@ -68,8 +65,86 @@ $options = [
 ];
 ```
 
+## Basic example
+
+In this example, we are collecting a submission in basic HTML from a `UserSubmissionController`. The field setup is the same as a standard `TextareaField`
+
+```php
+namespace MyApp;
+
+
+use NSWDPC\Utilities\Trumbowyg\TrumboywgEditorField;
+use SilverStripe\CMS\Controllers\ContentController;
+use SilverStripe\Forms\Form;
+use SilverStripe\Forms\Fieldlist;
+use SilverStripe\Forms\FormAction;
+
+class UserSubmissionController extends ContentController
+{
+    /**
+     * @var array
+     */
+    private static $allowed_actions = [
+        'UserEditForm' => true,
+    ];
+
+    /**
+     * Return the form for accepting data
+     */
+    public function UserEditForm() : Form {
+        return Form::create(
+            $this,
+            'UserEditForm',
+            Fieldlist::create(
+                TrumboywgEditorField::create(
+                    'UserProvidedContent', // field name
+                    'Write something' // title
+                )->setDescription(
+                    // optional
+                    "This is a description"
+                )->setRightTitle(
+                    // optional
+                    "This is a right title"
+                )
+            ),
+            Fieldlist::create(
+                FormAction::create(
+                    'doSubmission'
+                )
+            )
+        );
+    }
+
+    /**
+     * Handle the submitted content
+     */
+    public function doSubmission($data, $form) {
+        if(empty($data['UserProvidedContent'])) {
+            // error - no content
+        }
+        // UserProvidedContent will be return via
+        // TrumboywgEditorField::dataValue()
+        $sanitised = $data['UserProvidedContent'];
+        // save the content somewhere
+    }
+}
+```
+
+In your template, render the form:
+
+```template
+<% if $UserEditForm %>
+    <h1>Provide some information</h1>
+    <section>
+        {$UserEditForm}
+    </section>
+<% end_if %>
+```
+
 ## Modifying the configuration
 
-Be aware of cross-site scripting issues if certain tags are configured to be allowed. Good resources are:
+Be aware of cross-site scripting issues if certain tags and/or attributes are configured to be allowed.
+
+Good resources are:
 + https://html5sec.org/
 + https://owasp.org/www-community/xss-filter-evasion-cheatsheet