Sulu-Buttons

The husky-toolbar-component needs to be passed data, which defines what buttons it should render or what happens when somebody clicks on a button. Essentially Sulu-Buttons are about passing buttons to the toolbar-component in an easier and more elegant way than just copying the same buttons all over the place. With Sulu-buttons you can define buttons in a specific place, extend other buttons and override properties really easily.

Introduction

The admin-bundle contains an aura-extension in which all default buttons are specified as well as methods to get buttons and add buttons to the pool of default buttons.

An example for such a button is:

{
    name: 'save',
    template: {
        icon: 'floppy-o',
        title: 'public.save',
        disabled: true,
        callback: function() {
            app.sandbox.emit('sulu.toolbar.save', 'edit');
        }
    }
}

As you can see a button gets registered with a name and a template, which is the actual button meeting the specifications of the husky-framework.

The same holds for dropdown-items, for which also defaults are specified in the admin-bundle. For example:

{
    name: 'delete',
    template: {
        title: 'public.delete',
        callback: function() {
            app.sandbox.emit('sulu.toolbar.delete');
        }
    }
}

Retrieve buttons

The aura-extension in the admin-bundle extends every sandbox of a javascript-component with the method sulu.buttons.get. In your own component you can call this function like for example:

var generatedButtons = this.sandbox.sulu.buttons.get({
    edit: {},
    save: {
        options: {
            callback: function() {//do something//}
            }
        },
        settings: {
            options: {
                dropdownItems: {
                    delete: {}
                }
            }
        }
    }
});

The sulu.buttons.get method returns an array of buttons which meet the specification of the husky-framework. In our example this array contains the template of the edit-button, the template of the save`-button but with the callback-property replaced with our own one and the template of the ``settings-button which has the template of the delete-dropdownItem as the only dropdown-item.

If you want the settings-button two times in the same toolbar with - let’s say - different dropdown-items you can make use of the parent property;

var generatedButtons = this.sandbox.sulu.buttons.get({
    settings1: {
        parent: 'settings',
        options: {
            dropdownItems: {
                delete: {}
            }
        }
    },
    settings2: {
        parent: 'settings',
        options: {
            dropdownItems: {
                table: {}
            }
        }
    }
});

Add your own buttons

Additionally to the sulu.buttons.get method the aura-extension provides the following methods:

• sulu.buttons.add: takes a name and a button-template

• sulu.buttons.dropdownItems.add: takes a name and a dropdownItem-template

• sulu.buttons.push: takes an array of objects which all must contain a name and a template property

• sulu.buttons.dropdownItems.push: takes an array of objects which all must contain a name and a template property

• sulu.buttons.getApiButton: takes the name of a button-template and returns the actual template. Can be used to extend an existing button-template.

So with this methods you can easily add your own buttons and dropdown-items to the pool. These buttons are then globally available via the sulu.buttons.get method.

When adding your own button the preferable place to specify them is in a requirejs-component named sulu-buttons.js within the extensions-folder of your bundle. Adding the buttons and dropdown-items to the pool should then be done in the js/main.js file of your bundle in which the sulu-buttons.js file is required.

If you want to specify your own button which extends another existing button you can do the following. In this example the settings button is extended with a custom title.

var copyOfSettings = app.sandbox.sulu.buttons.getApiButton('settings');
copyOfSettings.title = 'My own title';
this.sandbox.sulu.buttons.add('my-settings-button', copyOfSettings);

Note

Don’t overuse the possibility to extend an existing button and provide a new one. Extending and providing your own button should only be done if the same button comes up in multiple places. If you just need to overwrite some properties of a default button in a single-place just use the sulu.buttons.get method.