README

Overview

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

Main features of the taxonomy term model and associated extensions, helpers, validators etc.

Singular and Plural display names

Extra names to be used in different situations, both on front-end and in the back-end

Description

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).

Definition fields

Author facing definition to be used within the CMS
End-users facing definition, e.g. used in glossaries

Single-select option

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).

Internal only option

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.

Required taxonomies

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.

URLSegment

A globally unique slug, currently globally unique (this constrain may be relaxed going forward to allow the same segments under different parents).

Usage

Requirements

SilverStripe 4.x
PHP ^7.3 (PHP8 not tested)

Installation

composer require chrometoaster/silverstripe-advanced-taxonomies

Configuration

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\DataObjectTaxonomiesDataExtension

There are some settings that can be modified in this module, depending on requirements. These are listed below.

Developer's notes

HTML in validation messages

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
// ...

Validation in the CMS and the assets-admin section

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.

Contributing

Code guidelines

This project follows the standards defined in:

If you are helping out, please also follow the standards above.

Translations

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.

chrometoaster / silverstripe-advanced-taxonomies

Maintainers

Details