Version 5 supported

Basic usage

The main model you'll be interacting with is TaxonomyTerm. This class represents the actual taxonomy terms you will apply to your data.

A taxonomy is of extremely limited use by itself. To make use of it, you need to associate it with DataObject models in your site.

To add the the ability to associate a model with TaxonomyTerm, you need to add the many-many relation:

namespace App\Model;

use SilverStripe\Forms\TreeMultiselectField;
use SilverStripe\ORM\DataObject;
use SilverStripe\Taxonomy\TaxonomyTerm;

class MyModel extends DataObject
{
    // ...
    private static $many_many = [
        'Terms' => TaxonomyTerm::class,
    ];

    public function getCMSFields()
    {
        $fields = parent::getCMSFields();
        // ...
        $fields->addFieldToTab('Root.Main', TreeMultiselectField::create(
            'Terms',
            $this->fieldLabel('Terms'),
            TaxonomyTerm::class
        ));
        return $fields;
    }
}

Run a dev/build?flush=all and you'll be able to add taxonomy terms to your record - but now you need to create some terms! See the userhelp documentation for information about functionality from a content author perspective.

Filtering by type

If you have implemented taxonomy types, you can filter them to ensure that only taxonomy terms of a given type or types can be selected. This can be useful, for example, if you want to separate your terms between files/images/documents and CMS pages.

This relies on TaxonomyType records which have specific names being set up in the CMS. You will need to coordinate with content authors to ensure these are always available, or else ensure they are created by default by populating defaults and ensure they cannot be deleted by implementing an Extension with the canDelete() method.

To implement this filtering, call TreeMultiselectField::setFilterFunction() with the filtering logic:

use SilverStripe\Forms\TreeMultiselectField;
use SilverStripe\Taxonomy\TaxonomyTerm;
use SilverStripe\Taxonomy\TaxonomyType;

/** @var TreeMultiselectField $treeField */
$typeID = TaxonomyType::get()->find('Name', 'CMS Page')?->ID;
$treeField->setFilterFunction(fn (TaxonomyTerm $term) => $term->TypeID === $typeID);

Showing taxonomy terms

So you've got a set of terms associated with a page, and you want to show them on your site. You can loop through them like any other relation:

<% loop $Terms %>
    <span class="tag">$Name</span>
<% end_loop %>
Edit on Github