Merging Elements in TUIX

When the CMS reads your .yaml files, it will first transform the data into a PHP array.

If more than one .yaml file contains a reference to the same Organizer panel or Admin Box, the CMS will read all of the files and then merge the contents together into the same array of data. Any elements or properties from different files that have the same name and path will get merged together. 

Rules for Merging

Files are read in the following order:

  1. First, in order of module dependancy
  2. Second, alphabetically by module
  3. Third, alphabetically by file name

When arrays are merged together they combine their keys; when values are merged together the value that is read first is always replaced by the value that is read last.

Organising your YAML code

This merging means that you can split any definitions you make across multiple .yaml files for better organisation, as they will all be merged back together at the end.

Merging and Planting Elements

You can "plant" your own elements in another module's Organizer panel, Admin Box or Admin Toolbar definition.

A practical example of this would be to extend the functionality of another module by adding your own buttons, columns or refiners to one of it's Organizer panels.

Note that if you did not write the module that you are merging elements into, it is good practice to prefix the name of any elements you add (e.g. with your module's name or your company's name), just to avoid any potential name-clashes with the original module, or with any other module developers who might attempt to do the same as you.

Implications for Dependencies

If you merge elements into another module's Organizer panel, Admin Box or Admin Toolbar definition, then you MUST list the module that you are merging to as a dependency.