Table of Contents

Toolbar Button Definitions

you are here (click to zoom) - discover the stack

When you create custom buttons in a floating toolbar you can customize everything including the icon and more. This is explained here.

Warning

Old Complicated Stuff

This is old complicated stuff which you shouldn't need any more. We left it in the docs because we're not sure if some people still use this. But we strongy urge you not to use it, and use the simple toolbar APIs instead.

Buttons are of html, basically a <a click="...">[some-icon]</a>. When the button is created, it must already know what it's for, which is why the command must be prepared when the button is created.

How to use

A short example of a slightly customized button definition:

var btns = [{
    command: { 
        action: "new",
        contentType: "Category"
    },
    title: "create Category"
}, {
    command: { 
        action: "new",
        contentType: "Author"
    },
    title: "create Author"
}];

This simple example shows two new buttons creating different kinds of things, and we customized the label so the mouse-over would tell the editor which button is which.

Let's get a bit more sophisticated

var btn = {
    command: { 
        // some command here
    },
    icon: "icon-sxc-code", 
    title: "this is my special button", 
    classes: "redButton",
};

The above example shows all than can currently be configured one a button.

And here's a much more complex example. This is the full object-structure which the button generator getButton(...) understands:

// full version
var btn = {
    title: "some title - ideally from translation table",
    icon: "some icon like icon-sxc-bomb",
    command: {
        action: "some action name like new",
        moreParamsAsNeeded: "..."
    },
    showCondition: someValueOr function(itemSettings) {
        return true;
    },
    classes: "btn-xyz my-class",
    dynamicClasses: function(itemSettings) {
        if( (new Date()).getDay() === 1 )
            return "color-monday";
    }
};

// typically more compact edition (will be expanded at runtime)
var btn2 = {
    title: "my button!",
    icon: "icon-sxc-list",
    action: "layout"
};

// or the totally compact edition
var btn3 = "layout";

Some functioning code

You may wonder how to actually use this. Here's an JSON example:

<p class="sc-element">
    mouse over this to see inline-json version
    <ul class="sc-menu" data-toolbar='[{
            "command": { 
                "action": "new",
                "contentType": "Category"
            },
            "title": "create Category"
        }, {
            "command": { 
                "action": "new",
                "contentType": "Author"
            },
            "title": "create Author"
    }]'></ul>
</p>

Here's a more sophisticated (but also more reusable) example:

<p class="sc-element">
    mouse over this to see the js toolbar generated by the buttons-list
    <toolbars2Buttons></toolbars2Buttons>
</p>
<script>
    var toolbars2Buttons =  [{
            command: { 
                action: "new",
                contentType: "Category"
            },
            title: "create Category"
        }, {
            command: { 
                action: "new",
                contentType: "Author"
            },
            title: "create Author"
    }];
    
    // note that we cannot create the toolbars before the page-onready. Because of this
    // our code which creates the toolbar must be delayed, like in a $(our-code);
    $(function(){
        if(typeof $2sxc != "undefined")   // continue if $2sxc exists; it may be missing in non-edit modes
            $("toolbars2Buttons").each(function(index, element){
                var controller = $2sxc(element);
                if(!controller.isEditMode())    // check if this specific module currently allows editing
                    return;
                    
                var toolbar = controller.manage.getToolbar(toolbars2Buttons);
                $(element).replaceWith(toolbar);
            });
    });
</script>

How it works

Buttons are used in toolbars all the time, and before they are rendered, the must be fully configured/expanded, as shown in the larger example. Internally the button is built with whatever is given, and anything not defined yet is automatically filled with the defaults. The defaults are taken from the commands definitions.

Here's how the get defaults works:

  1. if all that is knows about a button is the name like var btn = "new", then it gets all the configuration from the defaults
  2. if some properties are known, like var btn = { command: {action: "new"}, icon: "myicon" }, then only the missing properties are taken from the defaults.

Note that retrieving defaults requires the button to know which command it's for, so the name of the command is essential.

The Button Properties

  1. object command the internal command which will be called, should contain both the name and the parameters like { action: "new", contentType: "BlogPost"} see also commands
  2. string icon a css class giving the button the icon. It can be one of the icons 2sxc provides, or it can be your own - just be sure to include a CSS & font which resolves the icon
  3. string title a text which is shown on mouse-over. Note that 2sxc will try to run it through the translator, so you can also use placeholders like Toolbar.Metadata
  4. string classes comma separated list of class-names like makeRed,glowHover
  5. function dynamicClasses(settings) can be used to dynamically build classes depending on the situation
  6. bool/function showCondition (API still experimental) - used to dynamically choose if this button should be shown or not
  7. bool disabled (API still experimental) would disable the click on a button
  8. bool partOfPage (API still experimental, new in 2sxc 9.5) determines if resulting changes should effect the Evoq/Dnn Page Publishing - note that it only effects the page-lifecyle, if the resulting dialogs and APIs respect this setting

Some more Notes

Because the button is often passed around as plain text/html, it can't rely on hidden variables to keep track of anything. This is why the onclick is so verbose, like onclick="$2sxc(4030).manage.run({"action": "edit", "entityId": 42 }). This is to ensure it always survives the text-round-trip.

You should find some code examples in this demo App

History

  1. Introduced in 2sxc 08.06
Edit this page