Inspired by the Silverstripe's Taxonomy module, Chrometoaster's Advanced taxonomies module also adds the capability to manage hierarchical taxonomies within Silverstripe.
It also provides generic CMS interfaces to assign taxonomy terms (tag) to pages and files, and provides means how to extend this functionality to any other data objects, such as e.g. Elemental blocks.
Beyond basic terms tagging, the module aims to help professional information architects and content designers who wish to use taxonomies to classify most - if not all - of the content across a site, using a suite of interrelated hierarchical taxonomies. Advanced logic makes the use of taxonomies a more robust option for content-wide relationships, especially where multiple taxonomies must be used in conjunction.
Please note that this module is intended to replace Silverstripe's taxonomy module, it's not an extension to it. This module discards taxonomy type as a standalone model, accommodating the type atrributes via top-level taxonomy terms, sometimes referenced as types throughout the code base for legibility and context.
Main features of the taxonomy term model and associated extensions, helpers, validators etc.
- Extra names to be used in different situations, both on front-end and in the back-end
- A term description used throughout the CMS (e.g. within grid fields) to aid editors while tagging (useful when there are similar terms under different taxonomies).
- Author facing definition to be used within the CMS
- End-users facing definition, e.g. used in glossaries
- A taxonomy can be defined as 'single-select' or 'multi-select', depending on the nature of the terms/concepts — being synergistic or mutually exclusive.
- Validation rules apply when authors tag data objects with a single-select taxonomy term (i.e. only one term can be tagged at a time).
- A taxonomy can be dedicated as internal only, i.e. it won't be visible to end-users, marking the taxonomy to be used for 'administrative purposes' only — creating lists of items in the CMS, filtering etc.
- Any term can be configured with one or more Required taxonomies.
- Required taxonomies will prompt authors to select a term from other taxonomies, too, when the current term is assigned to a data object.
- If required taxonomies are set on the root term, then all descendant terms will inherit the requirements. Inheritance can be manually overridden, and further requirements configured, on individual terms.
- A globally unique slug, currently globally unique (this constrain may be relaxed going forward to allow the same segments under different parents).
- SilverStripe 4.x
- PHP ^7.3 (PHP8 not tested)
composer require chrometoaster/silverstripe-advanced-taxonomies
By default, the module applies the DataObjectTaxonomiesDataExtension extension to SiteTree and File classes
in the config.yml.
To add the extension to your project-specific data models, create a yaml config file similar to the example below:
App\Models\YourDataModel:
extensions:
- Chrometoaster\AdvancedTaxonomies\Extensions\DataObjectTaxonomiesDataExtension
App\Models\YourOtherCustomDataModel:
extensions:
- Chrometoaster\AdvancedTaxonomies\Extensions\DataObjectTaxonomiesDataExtensionThere are some settings that can be modified in this module, depending on requirements. These are listed below.
The Chrometoaster\AdvancedTaxonomies\Validators\TaxonomyRulesValidator produces error messages in a HTML format.
This behaviour can be sometimes problematic, especially in a React-like parts of the CMS, e.g. the assets admin.
For this purpose the validator offers a method to disable the HTML output, effectively applying plaintext term
decorators instead of richtext ones.
If you need to use the same behaviour, i.e. output just a plaintext error messages, set the attribute after getting an instance of the validator e.g. in a data extension like:
use Chrometoaster\AdvancedTaxonomies\Validators\TaxonomyRulesValidator;
$validator = TaxonomyRulesValidator::create();
$validator->setHTMLOutput(false);
// get the validation error or empty string
$requiredTypesValidationError = $validator->validateRequiredTypes($this->getOwner()->Tags());
// use the validation message further
// ...In the 'asset-admin' interface, when tags are assigned to a file, the message only appears after saving the file, whereas within the pages section (any non-react context), the validation is performed on the fly when adding the terms through the 'Add tag' gridfield interface.
This project follows the standards defined in:
If you are helping out, please also follow the standards above.
We would like to support multiple languages in the long term, however only some aspects of the codebase are translated at the moment.
Please refer to the "i18n" topic on docs.silverstripe.org for more details if you wish to contribute in this are of development.