#69

Product support

Get help in the plugin support forum.

Categories

  • Developer Tools
  • Miscellaneous
  • Utility

Introduction

This plugin extends the Cumulus Core with those components:

  1. CumulusDashboard
  2. CumulusSettings
  3. UpdateCluster

UpdateCluster is just typical frontend component to manage cluster details, so for now let's talk about CumulusDashboard and CumulusSettings.

They both work similar - if you embed one of them on page is like embedding all components registered as dashboard- or settings- one.

It shows of course only those components that cluster has access to.

Dashboard components are rendered in grid-stack grid so that every component has it's own grid item box (with customizable height, width and order). Settings components are rendered as tabs, so that every settings component can register its own tab with label, description and order.

You can register every component to be dashboard's or settings's one with register methods you already know from OctoberCMS!

Why is it great?

This functionality is great for every Cumulus based system. Every time I created dashboard for my system or settings page I was struggling with checking if user can or cannot see the form or dashboard. Using this plugin you can create great dashboard and settings page in seconds using components you already have or those newly created.

These plugin(s) are required for the plugin:

Two tabs in settings page. All rendered by ClusterSettings component.

Dashboard

ClusterDashboard component uses grid-stack and lodash. As a consequence you have to have jQuery included in you project. What is more, by default it uses Bootstrap 3 syntax, so it is a good idea to include it as well (but of course views can be overridden as in every other component).

In order to register your component as dashboard component you have to use registerCumulusDashboards method in your Plugin.php file.

Example definition of registerCumulusDashboards with explanation:

public function registerComponents()
{
    return [
        'Initbiz\MyModule\Components\MyModuleDashboard'  =>  'myModuleDashboard'
    ];
}

public function registerCumulusDashboards()
{
    return [
        'myModuleDashboard' => [
            'permissions' => 'mymodule', //slug of module to restrict visibility
            'properties'  => ['slug' => '{{:slug}}'], //properties to pass to component, default: ['clusterSlug' => '{{:cluster}}']
            'height'      => 1, //Height of the "widget"
            'width'       => 12, //Width of the "widget"
            'order'       => 100, //order in cluster dashboard, lower first, default: 500
        ]
    ];
}

Key of the array is the name of component in registerComponents method. In the example above we have component registered as myModuleDashboard.

The grid in dashboard is 12-columns, so in this example the box will be full width. By for now boxes are positioned automatically.

If you want to manipulate other components parameters before passing them to views you can use initbiz.cumulusplus.beforeDashboardRender event. It passes definitions of all components by reference.

Settings

ClusterSettings component by default uses Bootstrap 3 tabs, so it is a good idea to include it as well (but of course views can be overridden as in every other component). By default tabs are named as you translate it and their IDs are slugs of the translations. Moreover, CumulusPlus by default adds functionality to go to tab using #tab-id in URL.

In order to register your component as settings component you have to use registerCumulusSettings method in your Plugin.php file.

Example definition of registerCumulusSettings with explanation:

public function registerComponents()
{
    return [
        'Initbiz\MyModule\Components\MyModuleSettings'  =>  'myModuleSettings'
    ];
}

public function registerCumulusSettings()
{
    return [
        'myModuleSettings' => [
            'tab'         => 'initbiz.mymodule::lang.settings.tab_label', //Tab registration
            'permissions' => 'mymodule', //slug of module to restrict visibility
            'properties'  => ['slug' => '{{:slug}}'], //properties to pass to component, default: ['clusterSlug' => '{{:cluster}}']
            'order'       => 100, //order in cluster settings page, lower first, default: 500
        ]
    ];
}

You define order only for components, tab order will be inherited by the most important component in tab.

Key of the array is the name of component in registerComponents method. In the example above we have component registered as myModuleSettings.

If you want to manipulate other components parameters before passing them to views you can use initbiz.cumulusplus.beforeSettingsRender event. It passes definitions of all components by reference.

Hints

Overriding views

Right now settings and dashboards components does not support component aliases - if you want to override your settings and dashboards components views, you can use the mechanism of creating directory in partials named the same as component.

Translations

It is not required, but a good idea to use RainLab.Translate plugin. It is great for every project.

1.0.5

Removing logo using updateCluster

Aug 22, 2018

1.0.4

Small translation fix

Jun 29, 2018

1.0.3

Updated updateCluster component. Now it can update cluster's logo

Jun 27, 2018

1.0.2

Changed concept of registering settings components

Jun 21, 2018

1.0.1

First version of CumulusPlus

Jun 20, 2018