README

This plugin helps dealing with translated categories, providing a field with cross-languages sync + unique ids, and a few field methods.

Overview

This plugin is completely free and published under the MIT license. However, if you are using it in a commercial project and want to help me keep up with maintenance, please consider making a donation of your choice or purchasing your license(s) through my affiliate link.

1. Installation
2. Panel setup
3. Options
4. Frontend usage
5. Alternatives
6. License

1. Installation

Download and copy this repository to /site/plugins/categories

Alternatively, you can install it with composer: composer require sylvainjule/categories

2. Panel setup

The intent of the categories field is to allow an editor to easily create and manage multi-language categories, while keeping the field's content synced between languages in order to keep IDs unique. It will only work in multi-language setups.

It requires two steps:

First, add the field anywhere in your blueprints:

fields:
  categories:
    label: Categories
    type: categories

Second, you need to tell the plugin which template => fieldname to watch and sync accross languages, by adding this option to your config file:

// site/config/config.php
return [
    'sylvainjule.categories.watch' => [
        'template' => 'fieldname',
        'template' => ['fieldname1', 'fieldname2'],
    ]
];

For example, if you have a blog template with a categories field, and a projects template with clients + techniques fields, you will need to set:

// site/config/config.php
return [
    'sylvainjule.categories.watch' => [
        'blog'     => 'categories',
        'projects' => ['clients', 'techniques'],
    ]
];

You can then set the categories created with the field as dynamic options of select, multiselect, checkboxes, etc.

category:
  label: Category
  type: select
  options: query
  query:
    fetch: page.parent.categories.toCategories
    text: "{{ structureItem.text }}"
    value: "{{ structureItem.id }}"

3. Options

3.1. Prefix

The plugin stores an ID for each list item : {{prefix}}-{{index}}. The index is automatically incremented everytime a new category is added, but you can choose the prefix you'd like for each field (default is category-):

fields:
  countries:
    label: Countries
    type: categories
    prefix: country- # the field will store country-1, country-2, etc.

3.2. defaultFirst

By default, languages are displayed in alphabetical order. If you want to have the default language appear first, set this option to true. Default is false.

fields:
  countries:
    label: Countries
    type: categories
    defaultFirst: true

4. Frontend usage

There are few available methods to make handling categories easier. To get the whole categories list:

// returns a Structure
$categories = $page->categories()->toCategories();

foreach($categories as $category) {
    echo $category->text();
    // ... see below the list of all properties
}

From there you have access to a Structure Object with the following properties:

# content of a category
id: category-1       # $category->id()
text: 'My category'  # $category->text()
translations:        # $category->translations(), Array
  en: 'My category'  # $category->translations()['en']
  fr: 'Ma catégorie' # $category->translations()['fr']

If you have set a select, multiselect, checkboxes, etc. options from a categories field, the field will have stored the ID of the category. To get the text from there:

// toCategory($list, $lang = false)
$list = $page->parent()->categories();
$text = $page->category()->toCategory($list); // returns the category's text in the current language
$text = $page->category()->toCategory($list, 'fr'); // returns the category's text in French

// turns
'category-1' into 'My category' // returns a string
// or
'category-1,category-2' into ['My category', 'My category 2'] // returns an array

5. Alternatives

The plugin aims to solve a very specific use-case: managing single-text categories. If you need to have more data associated with each category, this is not the one.

In this case I'd recommend working with pages + autoid, one page per category where you can associate as much metadata as you'd like. You will need to remove them from your index / searchable pages / … later on.

Let me know if you have other convenient ways to deal with complex multi-language categories, I'll add them here.

6. License

MIT

sylvainjule / categories

Maintainers

Details