From 23bf8d2b3c6ad629c96dca5c0274d4015cce3c13 Mon Sep 17 00:00:00 2001
From: Aaron Carlino <unclecheese@leftandmain.com>
Date: Mon, 11 Jun 2018 15:32:44 +1200
Subject: [PATCH] add docs for new file extension process

---
 .../14_Files/01_File_Management.md            | 58 +++++++++++++++++++
 docs/en/04_Changelogs/4.0.0.md                | 54 +++++++++++++++++
 2 files changed, 112 insertions(+)

diff --git a/docs/en/02_Developer_Guides/14_Files/01_File_Management.md b/docs/en/02_Developer_Guides/14_Files/01_File_Management.md
index 957459099..37b99c9af 100644
--- a/docs/en/02_Developer_Guides/14_Files/01_File_Management.md
+++ b/docs/en/02_Developer_Guides/14_Files/01_File_Management.md
@@ -141,6 +141,64 @@ if ($file) {
 }
 ```
 
+## Adding custom fields to files and images
+
+As with any customisation of a core class, adding fields to the `File` and `Image` classes 
+is a two-phased approach. First, you have to update the model (i.e. the `$db` array) to include
+your new custom field. Second, you need to update the editform to provide a way of editing
+that field in the CMS. For most core classes, this can be done in a single extension, with an
+update to the `$db` array and definition of an `updateCMSFields` function, but for files 
+and images, it works a bit differently. The edit form is generated by another class --
+`FileFormFactory`. You will therefore need two separate extensions.
+
+In this example, we'll add a `description` field to the `File` object and give it an editable
+field in the CMS.
+
+*app/_config/app.yml*
+```yml
+SilverStripe\Assets\File:
+  extensions:
+    - MyProject\MyFileExtension
+SilverStripe\AssetAdmin\Forms\FileFormFactory:
+  extensions:
+    - MyProject\MyFormFactoryExtension
+```
+
+*app/src/MyFileExtension.php*
+```php
+namespace MyProject;
+
+use SilverStripe\ORM\DataExtension;
+
+class MyFileExtension extends DataExtension
+{
+    private static $db = [
+        'Description' => 'Text',
+    ];
+}
+```
+
+*app/src/MyFormFactoryExtension.php*
+```php
+namespace MyProject;
+
+use SilverStripe\Core\Extension;
+use SilverStripe\Forms\FieldList;
+use SilverStripe\Forms\TextareaField;
+
+class MyFormFactoryExtension extends Extension
+{
+    public function updateFormFields(FieldList $fields)
+    {
+        $fields->insertAfter(
+            'Title',
+            TextareaField::create('Description', 'Description')
+        );
+    }
+}
+```
+
+
 ## File versioning
 
 File versioning is extended with the [silverstripe/versioned](https://github.com/silverstripe/silverstripe-versioned/)
diff --git a/docs/en/04_Changelogs/4.0.0.md b/docs/en/04_Changelogs/4.0.0.md
index 70a5ade14..086481fe7 100644
--- a/docs/en/04_Changelogs/4.0.0.md
+++ b/docs/en/04_Changelogs/4.0.0.md
@@ -1095,6 +1095,60 @@ There are a few differences in this new API:
   A generic `manipulate` method may be used, although the callback for this method both is given, and should return,
   an `AssetStore` instance and file tuple (Filename, Hash, and Variant) rather than an Image_Backend.
 
+### Customising file edit form fields {#customising-file-editform}
+
+In 3.x, customisation of the edit form for files and images could be done using the conventional
+`updateCMSFields(FieldList $fields)` hook. In 4.x, this method no longer has any influence
+on the file edit form that gets rendered in asset-admin. Instead, create an extension for
+`FileFormFactory` and use the `updateFormFields(FieldList $fields)` hook.
+
+In this example, we'll add a `description` field to the `File` object and give it an editable
+field in the CMS.
+
+*app/_config/app.yml*
+```yml
+SilverStripe\Assets\File:
+  extensions:
+    - MyProject\MyFileExtension
+SilverStripe\AssetAdmin\Forms\FileFormFactory:
+  extensions:
+    - MyProject\MyFormFactoryExtension
+```
+
+*app/src/MyFileExtension.php*
+```php
+namespace MyProject;
+
+use SilverStripe\ORM\DataExtension;
+
+class MyFileExtension extends DataExtension
+{
+    private static $db = [
+        'Description' => 'Text',
+    ];
+}
+```
+
+*app/src/MyFormFactoryExtension.php*
+```php
+namespace MyProject;
+
+use SilverStripe\Core\Extension;
+use SilverStripe\Forms\FieldList;
+use SilverStripe\Forms\TextareaField;
+
+class MyFormFactoryExtension extends Extension
+{
+    public function updateFormFields(FieldList $fields)
+    {
+        $fields->insertAfter(
+            'Title',
+            TextareaField::create('Description', 'Description')
+        );
+    }
+}
+```
+
 ### File or Image shortcode handler {#file-shortcode}
 
 The `handle_shortcode` methods have been removed from the core File and Image classes