diff --git a/.doclintrc b/.doclintrc new file mode 100644 index 0000000..57af3a4 --- /dev/null +++ b/.doclintrc @@ -0,0 +1 @@ +docs/en/ \ No newline at end of file diff --git a/composer.json b/composer.json index 51a301f..953df98 100644 --- a/composer.json +++ b/composer.json @@ -22,7 +22,8 @@ "phpunit/phpunit": "^9.6", "squizlabs/php_codesniffer": "^3", "silverstripe/standards": "^1", - "phpstan/extension-installer": "^1.3" + "phpstan/extension-installer": "^1.3", + "silverstripe/documentation-lint": "^1" }, "suggest": { "symbiote/silverstripe-gridfieldextensions": "Allows sorting of TaxonomyTerm objects via drag-and-drop", @@ -35,7 +36,11 @@ "SilverStripe\\Taxonomy\\Tests\\Behat\\Context\\": "tests/behat/src/" } }, - "extra": [], + "config": { + "allow-plugins": { + "dealerdirect/phpcodesniffer-composer-installer": true + } + }, "minimum-stability": "dev", "prefer-stable": true } diff --git a/docs/en/01_basic_usage.md b/docs/en/01_basic_usage.md new file mode 100644 index 0000000..77db600 --- /dev/null +++ b/docs/en/01_basic_usage.md @@ -0,0 +1,78 @@ +--- +title: Basic usage +summary: How to set up your taxonomy relations and fields +--- + +# Basic usage + +The main model you'll be interacting with is [`TaxonomyTerm`](api:SilverStripe\Taxonomy\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: + +```php +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](https://userhelp.silverstripe.org/en/optional_features/taxonomies/) 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. + +> [!WARNING] +> 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](https://docs.silverstripe.org/en/developer_guides/model/how_tos/dynamic_default_fields/) +> and ensure they cannot be deleted by [implementing an Extension](https://docs.silverstripe.org/en/developer_guides/extending/extensions/) +> with the `canDelete()` method. + +To implement this filtering, call [`TreeMultiselectField::setFilterFunction()`](api:SilverStripe\Forms\TreeMultiselectField::setFilterFunction()) with the filtering logic: + +```php +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: + +```ss +<% loop $Terms %> + $Name +<% end_loop %> +``` diff --git a/docs/en/developer.md b/docs/en/developer.md deleted file mode 100644 index 1a7aa61..0000000 --- a/docs/en/developer.md +++ /dev/null @@ -1,205 +0,0 @@ -# Taxonomy usage - -## Applying Taxonomy - -A taxonomy is of extremely limited use by itself. To make use of it, you need to associate it with `Page` or other -`DataObject` elements in your site. - -To add the the ability to associate `Page` with `TaxonomyTerm`, you need to add the many-many relation to `Page`: - -```php -use SilverStripe\Taxonomy\TaxonomyTerm; -// ... -private static $many_many = array( - 'Terms' => TaxonomyTerm::class -); -``` - -And also add the reverse of the relation in an extension: - -```php -class TaxonomyTermExtension extends DataExtension -{ - private static $belongs_many_many = array( - 'Pages' => Page::class, - ); -} -``` - -Then add the extension by including this in your `mysite/_config/config.yml`: - -```yaml -SilverStripe\Taxonomy\TaxonomyTerm: - extensions: - - TaxonomyTermExtension -``` - -Run a `dev/build?flush=all` and you should see the table created. But you still can't do anything with it! You can fix -that by using a `GridField` to edit the associated terms. The sample code below will let your content editors add -existing terms with an autocomplete tool, unlink linked terms, but not edit them or add new ones. - -```php -public function getCMSFields() -{ - $fields = parent::getCMSFields(); - - $components = GridFieldConfig_RelationEditor::create(); - $components->removeComponentsByType(GridFieldAddNewButton::class); - $components->removeComponentsByType(GridFieldEditButton::class); - - $autoCompleter = $components->getComponentByType(GridFieldAddExistingAutocompleter::class); - $autoCompleter->setResultsFormat('$Name ($TaxonomyName)'); - - $dataColumns = $components->getComponentByType(GridFieldDataColumns::class); - $dataColumns->setDisplayFields(array( - 'Name' => 'Term', - 'TaxonomyName' => 'Taxonomy' - )); - - $fields->addFieldToTab( - 'Root.Tags', - GridField::create( - 'Terms', - 'Terms', - $this->Terms(), - $components - ) - ); - - return $fields; -} -``` - -You can apply that code to a `DataObject` to make use of it in the `ModelAdmin` area. - -## Filtering by type - -If you have implemented taxonomy types, you can filter them for the GridField autocompleter to ensure that certain -areas of your CMS will only autocomplete certain types of taxonomy terms. This can be useful, for example, if you want -to separate your terms between files/images/documents and CMS pages. - -To implement, add an extra line to your `getCMSFields` after the `$autoCompleter` has been created: - -```php -$autoCompleter->setSearchList(TaxonomyTerm::get()->filter(array('Type.Name:ExactMatch' => 'CMS Page'))); -``` - -## 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 %> - $Name -<% end_loop %> -``` - -See the two sections below for suggestions on how to create intelligent links from those tags. - -## Filtering with Taxonomy Terms - -You might have a news section in which you want to show only news items that have been tagged with a particular term. - -To start, it might be useful to get a list of all relevant terms. That is, all the terms that have been used in a list -of pages or dataobjects. This is one example that pulls a list of all tags that are used by children of this page: - -```php -public function ChildTags() -{ - $tags = TaxonomyTerm::get() - ->innerJoin( - 'Page_Terms', - '"TaxonomyTerm"."ID"="Page_Terms"."TaxonomyTermID"' - )->innerJoin( - 'SiteTree', - "\"SiteTree\".\"ID\"=\"Page_Terms\".\"PageID\" AND \"SiteTree\".\"ParentID\"='$this->ID'" - )->sort('Name'); - - return $tags; -} -``` - -You could use the output of this to display a list of tags that the user could filter by. - -You can then filter a result set by performing an inner join on it to restrict it to only those that have the required -term in their many-many relation (referenced by "$tagID"): - -```php -$pages = $this->Children()->filter(['Terms.ID' => $tagID]); -``` - -This will work for a single term. You could add more complex SQL to get any from a set of terms or to exclude terms. - -## Taxonomy Navigation - -You might want a page that acts as a parent to all pages with a certain tag. This way it can act as a dynamic directory -that will always display content about a certain topic, automatically adding pages as they get created. - -### Using a custom page type -To do so, you'll need to create a new page type (called `TaxonomyDirectory` here) and specify the tag or tags that -you'd like the page to display. In this example we'll just re-use the existing many-many relationship on `Page` but if -it's necessary for you to have two then you can create an extra many-many relationship. - -The only two functions that this page type needs to define are `stageChildren` and `liveChildren`. Instead of getting -children from the usual parent-child relationship, they look up children based on their taxonomy: - -```php -class TaxonomyDirectory extends Page -{ - public function stageChildren($showAll = false) - { - return Page::get() - ->exclude('ID', $this->ID) - ->filter(['Terms.ID' => $this->Terms()->getIDList()]); - } - - public function liveChildren($showAll = false, $onlyDeletedFromStage = false) - { - return $this->stageChildren($showAll); - } -} -``` - -### Using the provided default controller implementation -If you want to use the provided directory implementation named `TaxonomyDirectoryController`, more or less based on the previous example, the only thing -you need to do is enable access to the controller functions using a custom `routes.yml` file - -```yaml - ---- -Name: directoryroutes -After: '#coreroutes' ---- -SilverStripe\Control\Director: - rules: - 'tag/$ID!': 'SilverStripe\Taxonomy\Controllers\TaxonomyDirectoryController' -``` - -In this example, any request made to `/tag/` would render a page which contains a list of pages that uses the -Taxonomy Term specified by ``. You can override the provided template `TaxonomyDirectoryController.ss` -in your own theme. - -Currently the following variables are available to the template; -1. `Title` - the Taxonomy Term you are searching for -1. `Term` - the Taxonomy Term you are searching for -1. `Pages` - a list of `Page` objects - -An example for a template; -```html - -

Taxonomy directory

- -

Results for '$Term'

- - - - -``` - - -Note: the default directory implementation assumes that you've setup the reverse relation specified by `BasePage`. diff --git a/docs/en/index.md b/docs/en/index.md new file mode 100644 index 0000000..e88f1b5 --- /dev/null +++ b/docs/en/index.md @@ -0,0 +1,13 @@ +--- +title: Taxonomies +summary: Provides the capability to add and edit simple taxonomies for categorising data +icon: link +--- + +# Taxonomies + +Make sure that your Silverstripe CMS installation has [`silverstripe/taxonomy`](https://github.com/silverstripe/silverstripe-taxonomy/) installed. + +This module provides a "Taxonomies" section in the CMS, and a couple of `DataObject` models. + +[CHILDREN includeFolders] diff --git a/docs/en/userguide/index.md b/docs/en/userguide/index.md index 1d2def4..8259009 100644 --- a/docs/en/userguide/index.md +++ b/docs/en/userguide/index.md @@ -5,44 +5,44 @@ summary: Add and edit simple taxonomies in the CMS. # Creating and using taxonomies -## In this section: +## In this section -* Taxonomy usage -* Taxonomy terms and types -* Taxonomy creation and removal -* Permissions +- Taxonomy usage +- Taxonomy terms and types +- Taxonomy creation and removal +- Permissions -## Before we begin: +## Before we begin -* Make sure you have the SilverStripe [taxonomy](http://addons.silverstripe.org/add-ons/silverstripe/taxonomy) module installed +- Make sure you have the Silverstripe [taxonomy](http://addons.silverstripe.org/add-ons/silverstripe/taxonomy) module installed -# Taxonomy usage +## Taxonomy usage This module provides a raw skeleton for maintaining taxonomies in the CMS. Taxonomies are used to group content, making it easy to find related pieces of information. By default, the module provides the interface described below to create and manage taxonomies, using Taxonomy Terms and Taxonomy Types. -## Taxonomy terms and types +### Taxonomy terms and types The Taxonomy Term is the equivalent of the taxonomy itself - it serves to provide it's name, and as a holder of all the taxonomy's types. For example, a taxonomy term called 'News' could have multiple taxonomy types such as 'National', 'International', and 'Sport'. These help make your content easier to find by refining the focus. -## Taxonomy creation +### Taxonomy creation -To create a taxonomy, navigate to the **_Taxonomies_** section. +To create a taxonomy, navigate to the "Taxonomies" section. -The list that appears contains all existing taxonomies - there could be many in parallel. If the list is empty, you will want to create a Taxonomy Type first. To do so, navigate to the **_Taxonomy Types_** tab, click **_Add Taxonomy Type_**, specify the name (e.g. "News") and click **_Create_**. +The list that appears contains all existing taxonomies - there could be many in parallel. If the list is empty, you will want to create a Taxonomy Type first. To do so, navigate to the "Taxonomy Types" tab, click "Add Taxonomy Type", specify the name (e.g. "News") and click "Create". -To create first layer of terms within the taxonomy, switch to the **_Taxonomy Terms_** tab. Click **_Add Taxonomy Term_** and this time create "National". Switch to the **_Children_** tab, and nest another term underneath: (e.g. "Weather"). You have just +To create first layer of terms within the taxonomy, switch to the "Taxonomy Terms" tab. Click "Add Taxonomy Term" and this time create "National". Switch to the "Children" tab, and nest another term underneath: (e.g. "Weather"). You have just created a three-level hierarchy of "News > National > Weather". ![Example of taxonomy](_images/taxonomies-terms.jpg) You can easily navigate around the hierarchy by using breadcrumbs at the top as you would with other areas in -SilverStripe CMS. +Silverstripe CMS. -## Taxonomy removal +### Taxonomy removal -The taxonomies can be recursively removed. To remove an entire taxonomy, you can click the button **_More options_** which is shown as an ellipses icon and choose **_Delete_**. All terms belonging to it will be removed. +The taxonomies can be recursively removed. To remove an entire taxonomy, you can click the button "More options" which is shown as an ellipses icon and choose "Delete". All terms belonging to it will be removed. -You can also remove parts of the taxonomy tree - just descend into the children terms, and use the **_More options_** button next to +You can also remove parts of the taxonomy tree - just descend into the children terms, and use the "More options" button next to the top-level item of the subtree to be removed. ## Permissions @@ -51,6 +51,6 @@ the top-level item of the subtree to be removed. Site administrator can specify permissions around taxonomies. There are three permissions that can be set on groups: -* **_Create a taxonomy term_**: allows adding new terms to existing taxonomies. -* **_Delete a taxonomy term and all nested terms_**: allows to delete items recursively. -* **_Edit a taxonomy term_**: allows members of the group to update the taxonomy details. +- "Create a taxonomy term": allows adding new terms to existing taxonomies. +- "Delete a taxonomy term and all nested terms": allows to delete items recursively. +- "Edit a taxonomy term": allows members of the group to update the taxonomy details.