Skip to content

DOC Document new class_description and deprecated DBEnum::flushCache() #626

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
emteknetnz merged 1 commit into from
Nov 14, 2024
Merged

DOC Document new class_description and deprecated DBEnum::flushCache() #626

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions en/02_Developer_Guides/00_Model/01_Data_Model_and_ORM.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,8 @@ use SilverStripe\ORM\DataObject;

class Player extends DataObject
{
private static $class_description = 'Sports player';

private static $table_name = 'Player';

private static $db = [
Expand Down
16 changes: 16 additions & 0 deletions en/08_Changelogs/5.4.0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ title: 5.4.0 (unreleased)
- [Features and enhancements](#features-and-enhancements)
- [Option to change `ClassName` column from enum to varchar](#classname-varchar)
- [Reports quality of life updates](#reports-quality-of-life-updates)
- [New `class_description` configuration on `DataObject`](#class-description)
- [Other new features](#other-new-features)
- [API changes](#api-changes)
- [Bug fixes](#bug-fixes)
Expand Down Expand Up @@ -45,6 +46,18 @@ The changes include:
- Reports list is now paginated
- [`Description`](api:SilverStripe\Reports\Report::description()) is now displayed in the list as a column

### New `class_description` configuration on `DataObject` {#class-description}

[`SiteTree`](api:SilverStripe\CMS\Model\SiteTree) and [`BaseElement`](api:DNADesign\Elemental\Models\BaseElement) both seperately implemented a `description` configuration property which was used to describe the purpose of a given subclass. For `SiteTree` this is used when creating a new page in the CMS. For `BaseElement` this is used in the elemental blocks report. In both cases the purpose is the same - it provides additional context about the intended use case for a given subclass.

We've now implemented this concept in `DataObject` directly with the new [`DataObject.class_description`](api:SilverStripe\ORM\DataObject->class_description) configuration property. It is now considered best practice to add a description of `DataObject` subclasses using this configuration. You can use the new [`DataObject::classDescription()`](api:SilverStripe\ORM\DataObject::classDescription()) and [`DataObject::i18n_classDescription()`](api:SilverStripe\ORM\DataObject::i18n_classDescription()) methods if you need a description of any `DataObject` class. Those methods already existed on `SiteTree` but have been moved up the hierarchy so they can be called on any `DataObject` class.

For now this is only used in the same places that used to use the deprecated configuration, but future minor releases are likely to broaden the scope of its usage.
Copy link
Member Author

@GuySartorelli GuySartorelli Nov 11, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I could see it being used as a tooltip when hovering over elemental blocks in the "Add new block" list and added to the GridFieldAddNewMultiClass component in gridfield extensions at the very least.


As a part of this change, the [`SiteTree.description`](api:SilverStripe\CMS\Model\SiteTree->description) and [`BaseElement.description`](api:DNADesign\Elemental\Models\BaseElement->description) configuration properties are now deprecated. Use `class_description` instead.

The `SilverStripe\CMS\Model\SiteTree.DESCRIPTION` localisation key (along with the `.DESCRIPTION` suffix for any `SiteTree` subclass) will stop being used in a future major release. Use `SilverStripe\CMS\Model\SiteTree.CLASS_DESCRIPTION` instead.

### Other new features

- A new [`BaseKernel::getBooted()`](api:SilverStripe\Core\BaseKernel::getBooted()) method has been added for checking whether the kernel has been booted yet or not.
Expand Down Expand Up @@ -166,6 +179,9 @@ The changes include:
- [`TemplateParser`](api:SilverStripe\View\TemplateParser) has been deprecated. It will be renamed to `SilverStripe\TemplateEngine\TemplateParser`.
- [`ElementalAreaController::removeNamespacesFromFields()`](api:DNADesign\Elemental\Controllers\ElementalAreaController::removeNamespacesFromFields()) has been deprecated. It will be removed without equivalent functionality to replace it.
- [`BaseElement::updateFromFormData()`](api:DNADesign\Elemental\Models\BaseElement::updateFromFormData()) has been deprecated. It will be removed without equivalent functionality to replace it.
- [`DBEnum::flushCache()`](api:SilverStripe\ORM\FieldType\DBEnum::flushCache()) has been deprecated. Use [`DBEnum::reset()`](api:SilverStripe\ORM\FieldType\DBEnum::reset()) instead.
- The [`BaseElement.description`](api:DNADesign\Elemental\Models\BaseElement->description) configuration property has been deprecated. Use [`DataObject.class_description`](api:SilverStripe\ORM\DataObject->class_description) instead.
- The [`SiteTree.description`](api:SilverStripe\CMS\Model\SiteTree->description) configuration property has been deprecated. Use [`DataObject.class_description`](api:SilverStripe\ORM\DataObject->class_description) instead.

## Bug fixes

Expand Down