From 3cde64a7aae585b3abac216a6607238140f49780 Mon Sep 17 00:00:00 2001
From: Steve Boyd <emteknetnz@gmail.com>
Date: Tue, 3 Nov 2020 14:24:42 +1300
Subject: [PATCH] DOC Document the file usage table Co-authored-by: Bryn Whyman
 <bryn.whyman@silverstripe.com>

---
 .../14_Files/07_File_Usage.md                 | 84 +++++++++++++++++++
 docs/en/04_Changelogs/beta/4.7.0-beta1.md     | 15 ++++
 2 files changed, 99 insertions(+)
 create mode 100644 docs/en/02_Developer_Guides/14_Files/07_File_Usage.md

diff --git a/docs/en/02_Developer_Guides/14_Files/07_File_Usage.md b/docs/en/02_Developer_Guides/14_Files/07_File_Usage.md
new file mode 100644
index 000000000..a92ec8cf2
--- /dev/null
+++ b/docs/en/02_Developer_Guides/14_Files/07_File_Usage.md
@@ -0,0 +1,84 @@
+---
+title: File usage
+summary: See file usage and customising the file "Used on" table
+icon: compress-arrows-alt
+---
+
+# File Usage
+
+CMS users can view where a file is used by accessing the Used On tab in the Files section. This feature allows them to identify what DataObjects depend on the file.
+
+In the Files section of the CMS, click on a file to see file details.  Within the file details panel there is a
+Used on tab that shows a table of Pages and other DataObjects where the file is used throughout the website.
+
+## Customising the File "Used on" table in the Files section (asset-admin)
+
+Your project specific DataObject will automatically be displayed on the Used on tab. This may not always be desirable, especially when working with background DataObjects the user can not interact with directly. Extensions can be applied
+to the `UsedOnTable` class to update specific entries.
+
+Extension hooks can be used to do the following:
+- Exclude DataObjects of a particular type of class from being fetched from the database
+- Exclude individual DataObjects that were fetched for showing on the used on table
+- Link ancestors of a DataObject so they show on the same row of the used on table
+
+### Example PHP file:
+
+```php
+<?php
+namespace My\App\Extensions;
+
+use SilverStripe\Core\Extension;
+use SilverStripe\ORM\DataObject;
+
+class UsedOnTableExtension extends Extension
+{
+
+    // This extension hook will prevent type(s) of DataObjects from showing on the Used on tab in the Files section
+    // This will prevent a MyDataObjectToExclude::get() call from being executed
+    public function updateUsageExcludedClasses(array &$excludedClasses)
+    {
+        $excludedClasses[] = MyDataObjectToExclude::class;
+    }
+
+    // This extension hook will alter a DataObject after it was fetched via MyDataObject::get()
+    // This allows a greater level of flexibility to exclude or modify individual DataObjects
+    // It is less efficient to use this extension hook that `updateUsageExcludedClasses()` above
+    public function updateUsageDataObject(DataObject $dataObject)
+    {
+        if (!($dataObject instanceof MyDataObject)) {
+            return;
+        }
+        // Exclude DataObject from showing
+        if ($dataObject->Title == 'lorem ipsum') {
+            $dataObject = null;
+        }
+        // Show the DataObject's Parent() instead
+        $dataObject = $dataObject->Parent();
+    }
+
+    // This extension hook is used to to show ancestor DataObjects in the used on table alongside the
+    // DataObject the File is used on.  This is useful for two reasons:
+    // - It gives context more context, for instance if File is used on a Content block, it can be used to show the
+    //   Page that Content Block is used on
+    // - The DataObject may not have a `CMSEditLink()` implementation, though the ancestor DataObject does.
+    //   The CMS frontend will fallback to using the Ancestor `CMSEditLink()` for when a user clicks on a row on
+    //   the used on table
+    public function updateUsageAncestorDataObjects(array &$ancestorDataObjects, DataObject $dataObject)
+    {
+        if (!($dataObject instanceof MyDataObjectThatIWantToLink)) {
+            return;
+        }
+        $parentObjectIWantToIgnore = $dataObject->MyParentComponent();
+        $grandParentObjectIWantToLink = $parentObjectIWantToIgnore->MyParentComponent();
+        // Add $grandParentObjectIWantToLink to ancestors, but not $parentObjectIWantToIgnore
+        $ancestorDataObjects[] = $grandParentIWantToLink;
+    }
+}
+
+### Example YML file:
+
+```yml
+SilverStripe\Admin\Forms\UsedOnTable:
+  extensions:
+    - My\App\Extensions\UsedOnTableExtension
+```
\ No newline at end of file
diff --git a/docs/en/04_Changelogs/beta/4.7.0-beta1.md b/docs/en/04_Changelogs/beta/4.7.0-beta1.md
index 6a272b3cf..e3c12a9f6 100644
--- a/docs/en/04_Changelogs/beta/4.7.0-beta1.md
+++ b/docs/en/04_Changelogs/beta/4.7.0-beta1.md
@@ -10,6 +10,21 @@
 
 ## New features
 
+### Updated file usage table
+
+CMS users can view where a file is used by accessing the Used on tab in the Files section. This feature allows them to identify what DataObjects depend on the file.
+
+The following changes have been made to the Used on table:
+- Data is now sourced from has_one and many_many relations instead of the ownership API
+- This means more data relationships should be shown than before
+- Uses the new RelatedDataService API in the framework module which can also be used for other non-file use cases
+- Support for linking ancestor relationships in the same table row, for instance showing the Page a Content Block is on
+- Ability to click on a row and navigate to the most relevant `CMSEditLink()`
+- Removal of draft badges
+- Styling tweaks such as reduced padding
+
+Your project specific DataObjects will automatically be displayed on this Used on tab. This may not always be desirable, especially when working with background DataObjects the user can not interact with directly. It is recommended you view the CMS Developer Guide for more information on this change, see the [File Usage section](docs/en/02_Developer_Guides/14_Files/07_File_Usage).
+
 ### Experimental support for PHP 8
 
 You can now run Silverstripe CMS on PHP 8, which is due for release in November 2020. PHP 8 includes