MatrixMate plugin for Craft CMS

Welding Matrix into shape, mate!

Requirements

This plugin requires Craft CMS 4.0.0 or later.

‼️MatrixMate has been retired and will not be available for Craft 5. See this issue for more info.
Also see this comment for some hints and tips towards migrating away from MatrixMate 🚀

Installation

To install the plugin, either install it from the plugin store, or follow these instructions:

Install with composer via composer require vaersaagod/matrixmate from your project directory.
Install the plugin in the Craft Control Panel under Settings -> Plugins, or from the command line via ./craft plugin/install matrixmate.
For MatrixMate to do anything, you need to configure it. But first, continue reading!

MatrixMate overview

MatrixMate enables you to improve the Matrix authoring experience by sorting block types into groups and block type fields into tabs.

Additionally, MatrixMate offers these nifty features:

Maximum limits can be set per block type
Ungrouped block types can be hidden, or displayed as native Matrix buttons
A single block type can be added to multiple groups (sometimes it makes sense!)
Block types can be explicitly hidden, even without using the grouping feature
A single Matrix field can be configured differently for different contexts (e.g. sections, entry types, category groups etc)

alt text

I can't believe it's not Pimp My Matrix!

MatrixMate began life as a fork of famed Craft plugin Pimp My Matrix (aka Spoon for Craft 3), and we give big props to its author Josh Angell for inspiring MatrixMate.

The featureset overlap between Spoon and MatrixMate is pretty obvious, but a big difference is that unlike Spoon, MatrixMate does not feature a field configuration UI inside Craft's Control Panel. Instead, MatrixMate is completely configured using a PHP config file.

Nested Matrix fields

MatrixMate does not support Matrix fields that are nested in other fieldtypes (e.g. SuperTable). If you need SuperTable support, you should consider using Spoon instead.

Configuring MatrixMate

MatrixMate is configured by creating a config file named matrixmate.php in your Craft config folder (i.e. where your general.php and db.php files sit).

The config file should look something like this:

<?php

return [
    'fields' => [
        'matrixFieldHandle' => [
            'groups' => [[
                'label' => 'Content',
                'types' => ['text', 'images', 'video'],
            ], [
                'label' => 'Listings',
                'types' => ['news', 'employees'],
            ]],
            'types' => [
                'text' => [
                    'tabs' => [[
                        'label' => 'Text',
                        'fields' => ['heading', 'text'],
                    ], [
                        'label' => 'Settings',
                        'fields' => ['columns'],
                    ]],
                    'hiddenFields' => ['backgroundColor', 'textColor'],
                ],
                'news' => [
                    'maxLimit' => 1,
                ],
            ],
        ],
        'anotherMatrixFieldHandle' => [
            ...
        ],
    ],
];

To explain what the above example would do:

For a Matrix field with the handle matrixFieldHandle, the above configuration would create two block type groups called "Content" and "Listings". The fields inside the text block type would be sorted into two tabs called "Text" and "Settings", and the news block type would be limited to a single block, using the maxLimit setting.

Additionally, two fields called backgroundColor and textColor in the text block type are hidden, using the hiddenFields setting (added in MatrixMate v. 1.2.0).

For a more detailed overview of the different settings available when configuring MatrixMate, see the Configuration settings section.

Config contexts

By default, a MatrixMate field config will apply everywhere that the field is used. However, you can use context keys to apply different configs for the same field across different types of content:

<?php

return [
    'fields' => [
        'matrixFieldHandle' => [ 
            '*' => [
                'groups' => [
                    ...
                ],
            ],
            'section:news,section:blog' => [
                'groups' => [
                    ...
                ],
            ],
        ],
    ],
];

The above example would apply a specific configuration for a Matrix field with the handle "matrixFieldHandle" when that field is used in entries belonging to the sections news and blog (note that a comma separated list is used to apply the same configuration to multiple contexts).

Additionally, a "global" config that will apply everywhere else is added using the asterisk (*) key. The global config is completely optional - it's totally fine to only have specific context keys declared (in which case the Matrix field will render natively; i.e. without any modifications, everywhere else).

Supported contexts

section:{handle} - Apply for all entry types in a particular section
entryType:{handle} - Apply for entries with a particular entry type
categoryGroup:{handle} - Apply for categories in a particular category group
globalSet:{handle} - Apply for a particular global set
volume:{handle} - Apply for assets in a particular volume
users - Apply for user account edit pages
productType:{handle} - Apply for Commerce products with a particular product type

Config context inheritance

‼️ MatrixMate config contexts are not recursively merged – unlike, for example, Craft's multi-environment configs. This means that if you have a global config context (i.e. *) and a context targeting, for example, a specific section (e.g. 'section:news'), the settings for the global config are not inherited by that 'section:news' context. Essentially, you start fresh for every context. This is not a bug, but a feature!

...in cases where you'd prefer that config contexts were merged, you can work around this behavior by adding a bit of PHP logic to the config file:

<?php

$globalConfig = [
    'groups' => [
        ...
    ],
];

return [
    'fields' => [
        'matrixFieldHandle' => [ 
            '*' => $globalConfig,
            'section:news,section:blog' => array_merge_recursive($globalConfig, [
                'groups' => [
                    ...
                ],
            ]),
        ],
    ],
];

Configuration settings

The below settings apply to a Matrix field configuration, e.g.

<?php

return [
    'fields' => [
        'matrixFieldHandle' => [
            // Field configuration here
        ],
    ],
];

defaultTabName [string|bool]

Default: 'Fields'

If any of the block types in a field config is setup with custom tabs, MatrixMate will put any fields that isn't added to a tab into a "default" tab called "Fields". To change the name for the default tab, add a key called 'defaultTabName' to the field config:

<?php

return [
    'fields' => [
        'matrixFieldHandle' => [
            'defaultTabName' => 'Misc',
        ],
    ],
];

To not render any default tabs (effectively hiding all fields that aren't put into tabs), defaultTabName can be set to false:

<?php

return [
    'fields' => [
        'matrixFieldHandle' => [
            'defaultTabName' => false,
        ],
    ],
];

This setting only applies to block types that are configured to use tabs, and can be overridden on a per-type basis (see 'types' config section below).

defaultTabFirst [bool]

Default: false

By default, the default tab will render after any custom tabs. To put the default tab first, set defaultTabFirst to true.

<?php

return [
    'fields' => [
        'matrixFieldHandle' => [
            ...
            'defaultTabName' => 'Misc',
            'defaultTabFirst' => true,
        ],
    ],
];

groups [array]

Block types can be grouped by adding a key 'groups' to a field configuration.

A single group is declared by adding an associate array to 'groups', containing the keys 'label' (string, the name of the group) and 'types' (array with the handles for the block types the group should contain):

...
'matrixFieldHandle' => [
    'groups' => [[
        'label' => 'Content',
        'types' => ['text', 'heading'],
    ], [
        'label' => 'Misc',
        'types' => ['newsletter', 'feed'],
    ]],
],

Note that empty groups (or groups containing a types array without any actual/valid block type handles) as well as groups missing labels, will not be rendered.

types [array]

Using the 'types' key in a field configuration enables you to sort block type fields into tabs, and/or add a maximum limit to the number of instances a particular block type is allowed to have.

The 'types' array should use relevant block types' handles as keys, with each block type's configuration as an array for the values:

...
'matrixFieldHandle' => [
    'types' => [
        'text' => [
            // Block type config here
        ],
        'news' => [
            // Block type config here
        ],
    ],
],

Creating tabs

To sort a block

Matrixmate

Install / Use

README