DOC Document code moved from cms to framework

en/02_Developer_Guides/15_Customising_the_Admin_Interface/07_Status_Flags.md

@@ -0,0 +1,127 @@
+---
+title: Status Flags
+summary: Provide information about the status of content in the CMS
+icon: icon-square
+---
+
+# Status flags
+
+Status flags are short text descriptions of the status for a piece of content. For example, the [`Versioned`](api:SilverStripe\Versioned\Versioned) extension provides status flags to indicate when content in in draft or has been modified, so content authors know there is content that hasn't yet been published.
+
+These flags are displayed at the top of edit forms in the CMS, and in various places next to record names such as the site tree and in grid fields.
+
+![status flags in the CMS](../../_images/status-flag.png)
+
+In the above screenshot, "MODIFIED" and "EN_US" are status flags. The "MODIFIED" flag is provided by the `Versioned` extension, and the "EN_US" flag is provided by [`tractorcow/silverstripe-fluent`](https://github.com/tractorcow-farm/silverstripe-fluent/).
+
+Note that in the site tree only one status flag will be displayed when you're editing a record, due to the limited space available.
+
+Some status flags have additional context which can be viewed by hovering over them with your mouse cursor.
+
+## Adding and removing status flags
+
+You can easily add and remove status flags.
+
+The customization of status flags can be done either directly in the model class by overriding the [`ModelData::getStatusFlags()`](api:SilverStripe\Model\ModelData::getStatusFlags()) method, or by [applying an extension](/developer_guides/extending/extensions/) that implements the `updateStatusFlags` extension hook.
+
+Add status flags by adding new items to the `$flags` array, and remove existing flags by unsetting the relevant key in the array.
+
+### Directly on the model
+
+```php
+namespace App\Model;
+
+use SilverStripe\ORM\DataObject;
+
+class Event extends DataObject
+{
+    // ...
+    private static array $db = [
+        'Scheduled' => 'Date',
+    ];
+
+    public function getStatusFlags(bool $cached = true): array
+    {
+        $this->beforeExtending('updateStatusFlags', function (array &$flags) {
+            if ($this->dbObject('Scheduled')->InFuture()) {
+                $flags['scheduled'] = 'Scheduled';
+            }
+        });
+        return parent::getStatusFlags($cached);
+    }
+}
+```
+
+### Via an extension
+
+```php
+namespace App\Extension;
+
+use SilverStripe\Core\Extension;
+
+class ScheduleExtension extends Extension
+{
+    private static array $db = [
+        'Scheduled' => 'Date',
+    ];
+
+    protected function updateStatusFlags(array &$flags): void
+    {
+        if ($this->getOwner()->dbObject('Scheduled')->InFuture()) {
+            $flags['scheduled'] = 'Scheduled';
+        }
+    }
+}
+```
+
+### Including additional context
+
+Sometimes the text of a status flag won't convey all the information you want it to, since it is so short.
+
+You can include additional context which will be displayed when hovering over your status flags. This is done using an associative array where the main text of the flag is in the `text` key, and the additional information is in the `title` key:
+
+```php
+namespace App\Model;
+
+use SilverStripe\ORM\DataObject;
+
+class Event extends DataObject
+{
+    // ...
+    public function getStatusFlags(bool $cached = true): array
+    {
+        $this->beforeExtending('updateStatusFlags', function (array &$flags) {
+            if ($this->dbObject('Scheduled')->InFuture()) {
+                $flags['scheduled'] = [
+                    'text' => 'Scheduled',
+                    'title' => 'This event has been scheduled for a future date',
+                ];
+            }
+        });
+        return parent::getStatusFlags($cached);
+    }
+}
+```
+
+## Styling status flags
+
+By default custom status flags will have a blue background and dark grey text.
+
+![custom status flags in the CMS](../../_images/status-flags-custom.png)
+
+If you want to customise how your status flags look, you can add some CSS to the CMS that targets the `badge` and `status-<flag-name>` CSS classes. For example the flag added above would have the CSS classes `badge status-scheduled`.
+
+Status flags displayed in the top of an edit form (aka in the breadcrumbs) also have the CSS class `badge--breadcrumbs`, which allows a border to be displayed around the flag in that context.
+
+See [include custom CSS in the CMS](/developer_guides/customising_the_admin_interface/how_tos/extend_cms_interface/#include-custom-css-in-the-cms) for more detailed instructions.
+
+### Status flags in `GridField`
+
+By default, if your [`GridField`](api:SilverStripe\Forms\GridField\GridField) includes a `Title` or `Name` column, that column will be used to display the status flags.
+
+Depending on your requirements, you might want to hide status flags in a given grid field, or change what column is used to display them.
+
+The [`GridFieldDataColumns`](api:SilverStripe\Forms\GridField\GridFieldDataColumns) component provides some methods you can use to control how and if status flags are displayed:
+
+- [`setDisplayStatusFlags()`](api:SilverStripe\Forms\GridField\GridFieldDataColumns::setDisplayStatusFlags()): Pass `false` to stop displaying status flags for this grid field
+- [`setColumnsForStatusFlag()`](api:SilverStripe\Forms\GridField\GridFieldDataColumns::setColumnsForStatusFlag()): Pass an array of column names. The first column found in this list will be used to display status flags.

en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Customise_CMS_Tree.md

@@ -18,7 +18,7 @@ which recursively collects all nodes based on various filtering criteria.
 The node strictly just has to implement the [Hierarchy](api:SilverStripe\ORM\Hierarchy\Hierarchy) extension,
 but in the CMS usually is a [SiteTree](api:SilverStripe\CMS\Model\SiteTree) object.
 
-## Add status lozenges to tree nodes
+## Add status flags to tree nodes
 
 A tree node in CMS could be rendered with lot of extra information but a node title, such as a
 link that wraps around the node title, a node's id which is given as id attribute of the node
@@ -50,53 +50,9 @@ code like this:
 By applying the proper style sheet, the snippet html above could produce the look of:
 ![Page Node Screenshot](../../../_images/tree_node.png "Page Node")
 
-SiteTree is a [DataObject](api:SilverStripe\ORM\DataObject) which is versioned by [Versioned](api:SilverStripe\Versioned\Versioned) extension.
-Each node can optionally have publication status flags, e.g. "Removed from draft".
-Each flag has a unique identifier, which is also used as a CSS class for easier styling.
+In the above screenshot "DELETED" is the status flag.
 
-Developers can easily add a new flag, delete or alter an existing flag on how it is looked
-or changing the flag label. The customization of these lozenges could be done either through
-inherited subclass or [Extension](api:SilverStripe\Core\Extension). It is just really about how we change the return
-value of function `SiteTree->getTreeTitle()` by two easily extendable methods
-`SiteTree->getStatusClass()` and `SiteTree->getStatusFlags()`.
-
-Note: Though the flag is not necessarily tie to its status of **publication** and it could
-be used for flagging anything you like, we should keep this lozenge to show version-related
-status, while let `SiteTree->CMSTreeClasses()` to deal with other customised classes, which
-will be used for the class attribute of <li> tag of the tree node.
-
-### Add new flag
-
-```php
-namespace {
-    use SilverStripe\CMS\Model\SiteTree;
-
-    class Page extends SiteTree
-    {
-        public function getScheduledToPublish()
-        {
-            // return either true or false
-        }
-
-        public function getStatusFlags($cached = true)
-        {
-            $flags = parent::getStatusFlags($cached);
-            $flags['scheduledtopublish'] = 'Scheduled To Publish';
-            return $flags;
-        }
-    }
-}
-```
-
-The above subclass of [SiteTree](api:SilverStripe\CMS\Model\SiteTree) will add a new flag for indicating its
-**'Scheduled To Publish'** status. The look of the page node will be changed
-from ![Normal Page Node](../../../_images/page_node_normal.png) to ![Scheduled Page Node](../../../_images/page_node_scheduled.png).
-
-The getStatusFlags has an `updateStatusFlags()`
-extension point, so the flags can be modified through `Extension` rather than
-inheritance as well.
-
-Deleting existing flags works by simply unsetting the array key.
+To learn how to add, remove, and update status flags see [status flags](/developer_guides/customising_the_admin_interface/status_flags/).
 
 ## Customising page icons
 

en/08_Changelogs/6.0.0.md

@@ -17,6 +17,7 @@ title: 6.0.0 (unreleased)
   - [Changes to the templating/view layer](#view-layer)
   - [Changes to `LeftAndMain` and its subclasses](#leftandmain-refactor)
   - [Changes to password validation](#password-validation)
+  - [Status flags in the CMS](#status-flags-in-the-cms)
   - [Other new features](#other-new-features)
 - [Dependency changes](#dependency-changes)
   - [`intervention/image` has been upgraded from v2 to v3](#intervention-image)
@@ -629,6 +630,14 @@ As a result of these changes, the following classes have had their class hierarc
 
 The `tree_class` configuration property on `LeftAndMain` and its subclasses has be renamed to [`model_class`](api:SilverStripe\Admin\LeftAndMain->model_class). This is used in methods like [`getRecord()`](api:SilverStripe\Admin\LeftAndMain::getRecord()) to get a record of the correct class.
 
+#### Effects of this refactor in other classes
+
+Some classes outside of the `LeftAndMain` class hierarchy have also been affected by the refactoring:
+
+- The `SiteTree.description` configuration property has been renamed to [`class_description`](api:SilverStripe\ORM\DataObject->class_description).
+    This configuration has been added to `DataObject` along with the corresponding [`classDescription()`](api:SilverStripe\ORM\DataObject::classDescription()) and [`i18n_classDescription()`](api:SilverStripe\ORM\DataObject::i18n_classDescription()) methods.
+- The [`Hierarchy`](api:SilverStripe\ORM\Hierarchy\Hierarchy) extension now has a bunch of configuration and methods which used to be exclusive to `SiteTree`.
+
 #### New `SingleRecordAdmin` class and changes to `SiteConfig` {#leftandmain-singlerecordadmin}
 
 A new [`SingleRecordAdmin`](api:SilverStripe\Admin\SingleRecordAdmin) class has been created which makes it easier to create an admin section for editing a single record.
@@ -679,6 +688,18 @@ This has been changed to use the [`PasswordStrength` constraint](https://symfony
 
 You can change the level of entropy required by passing one of the valid [minScore values](https://symfony.com/doc/current/reference/constraints/PasswordStrength.html#minscore) into [`ConfirmedPasswordField::setMinPasswordStrength()`](api:SilverStripe\Forms\ConfirmedPasswordField::setMinPasswordStrength()).
 
+### Status flags in the CMS
+
+In CMS 5 the CMS showed status flags for the [`SiteTree`](api:SilverStripe\CMS\Model\SiteTree) class inside the `/admin/pages` section, and occasionally for other models in grid fields - but this was inconsistent and was done in a variety of different ways depending on what was adding the flags and where they were displayed.
+
+We've standardised this in the new [`ModelData::getStatusFlags()`](api:SilverStripe\Model\ModelData::getStatusFlags()) method to define the flags, and [`ModelData::getStatusFlagMarkup()`](api:SilverStripe\Model\ModelData::getStatusFlagMarkup()) to build the HTML markup for them. This means that status flags can be displayed for *any* model in the CMS.
+
+This is already used to show what locale the data is in for models localised using [`tractorcow/silverstripe-fluent`](https://github.com/tractorcow-farm/silverstripe-fluent/), and what versioned stage it's in for models using the [`Versioned`](api:SilverStripe\Versioned\Versioned) extension.
+
+Status flags are displayed in breadcrumbs at the top of edit forms in the CMS, in the site tree for `CMSMain`, for each row in a grid field, and in [`dnadesign/silverstripe-elemental`](https://github.com/silverstripe/silverstripe-elemental/) and [`silverstripe/linkfield`](https://github.com/silverstripe/silverstripe-linkfield).
+
+See [status flags](/developer_guides/customising_the_admin_interface/status_flags/) for more information.
+
 ### Other new features
 
 - Modules no longer need to have a root level `_config.php` or `_config` directory to be recognised as a Silverstripe CMS module. They will now be recognised as a module if they have a `composer.json` file with a `type` of `silverstripe-vendormodule` or `silverstripe-theme`.
@@ -884,8 +905,8 @@ As part of these changes [`ArrayList::find()`](api:SilverStripe\Model\List\Array
 
 - [`DataObject::write()`](api:SilverStripe\ORM\DataObject::write()) has a new boolean `$skipValidation` parameter. This can be useful for scenarios where you want to automatically create a new record with no data initially without restricting how developers can set up their validation rules.
 - [`FieldList`](api:SilverStripe\Forms\FieldList) is now strongly typed. Methods that previously allowed any iterable variables to be passed, namely [`FieldList::addFieldsToTab()`](api:SilverStripe\Forms\FieldList::addFieldsToTab()) and [`FieldList::removeFieldsFromTab()`](api:SilverStripe\Forms\FieldList::removeFieldsFromTab()), now require an array to be passed instead.
-- [`BaseElement::getDescription()`](api:DNADesign\Elemental\Models\BaseElement::getDescription()) has been removed. If you had implemented this method in your custom elemental blocks, either set the [`description`](api:DNADesign\Elemental\Models\BaseElement->description) configuration property or override the [`getTypeNice()`](api:DNADesign\Elemental\Models\BaseElement::getTypeNice()) method.
-- [`DataExtension`](api:SilverStripe\ORM\DataExtension), [`SiteTreeExtension`](api:SilverStripe\CMS\Model\SiteTreeExtension), and [`LeftAndMainExtension`](api:SilverStripe\Admin\LeftAndMainExtension) have been removed. If you subclass any of these classes, you must now subclass [`Extension`](api:SilverStripe\Core\Extension) instead.
+- `DNADesign\Elemental\Models\BaseElement::getDescription()` and the corresponding `DNADesign\Elemental\Models\BaseElement.description` configuration property have been removed. If you were using either of these in your custom elemental blocks, either set the new [`class_description`](api:SilverStripe\ORM\DataObject->class_description) configuration property or override one of the [`i18n_classDescription()`](api:SilverStripe\ORM\DataObject::i18n_classDescription()) or [`getTypeNice()`](api:DNADesign\Elemental\Models\BaseElement::getTypeNice()) methods instead.
+- `SilverStripe\ORM\DataExtension`, `SilverStripe\CMS\Model\SiteTreeExtension`, and `SilverStripe\Admin\LeftAndMainExtension` have been removed. If you subclass any of these classes, you must now subclass [`Extension`](api:SilverStripe\Core\Extension) directly instead.
 - [`DBCurrency`](api:SilverStripe\ORM\FieldType\DBCurrency) will no longer parse numeric values contained in a string when calling `setValue()`. For instance "this is 50.29 dollars" will no longer be converted to "$50.29", instead its value will remain as "this is 50.29 dollars" and it will throw a validation exception if attempted to be written to the database.
 
 ## Other changes