Previous topic

TextBox

Next topic

ToolsList

DOCUMENTATION
Last updated 15-Jul-2016

Toolbar

Introduction

With the Toolbar widget you can display a Toolbar. You may use it both as a standalone screen element, and as part of the Grid widget (see Grid).

Test Toolbar in browser

See JS API for all methods and properties

Main properties

You can place on a toolbar:

  • toolbar buttons;
  • toolbar buttons separator.

You define toolbar elements as child elements. Depending on the way your widgets are declared, child elements are defined as follows:

  • a nested array (in case of declaration with help of the loader);
  • using the addChild method (in case of programmatic declaration);
  • a hierarchy of widgets corresponding to the hierarchy of DOMNodes (declarative syntax).

More detailed information on widget declaration see in Widget Declaration.

Toolbar buttons

Using the ToolbarButton widget you can display a toolbar button.

Such a button may contain:

  • label

    You may define it using either the label property, or the title property. You must not use the both properties together.

  • icon

    It may be defined using two ways:

    • by specifying a CSS class for the iconClass property

      RUN DEMO

      require(["aps/Toolbar", "aps/ToolbarButton", "aps/PageContainer", "aps/ready!"],
        function(Toolbar, ToolbarButton, PageContainer){
          "use strict";
      
          var page = new PageContainer({}, "example");
      
          var toolbar = new Toolbar({});
      
          toolbar.addChild(new ToolbarButton({
            label:      "Add New Server",
            iconClass:  "sb-add-new-server"
          }));
      
          page.addChild(toolbar);
      
          page.startup();
      });
      
    • by specifying the path to an icon file for the iconName property

      You can also add a click handler for a button by defining the onclick property:

      RUN DEMO

      require(["aps/Toolbar", "aps/ToolbarButton", "aps/PageContainer", "aps/ready!"],
        function(Toolbar, ToolbarButton, PageContainer){
          "use strict";
      
          var page = new PageContainer({}, "example");
          var toolbar = new Toolbar();
      
          toolbar.addChild(new ToolbarButton({
            label:      "Add New Server",
            iconClass:  "sb-add-new-server",
            onClick: function(){
              alert("triam!");
            }
          }));
      
          page.addChild(toolbar);
      
          page.startup();
      });
      

After creating a button, irrespective of the way it was declared, you can specify a click handler at any time you like by using the on method with a value of the first argument set to “click”. You can get a button object with help of a registry (dijit/registry) object. For more information on the registry module see Standard properties of widgets.

RUN DEMO

require([
  "aps/Toolbar",
  "aps/ToolbarButton",
  "dijit/registry",
  "aps/PageContainer",
  "aps/ready!"
], function(Toolbar, ToolbarButton, registry, PageContainer){
  "use strict";

  var page = new PageContainer({}, "example");

  var toolbar = new Toolbar();

  toolbar.addChild(new ToolbarButton({
    id:         "AddNewServer",
    label:      "Add New Server",
    iconClass:  "sb-add-new-server"
  }));

  page.addChild(toolbar);

  page.startup();

  registry.byId("AddNewServer").on("click", function(e) {
    alert("click!");
  });
});

When using declarative syntax, you may define a click handler by specifying a child element with the dojo/on type inside a button:

RUN DEMO

<div dojoType="aps/PageContainer">
	<div dojoType="aps/ToolbarButton">
  	<script type="dojo/on" data-dojo-event="click">
    	alert("hurrah!");
    </script>
    New Server
  </div>
</div>

By default, after clicking a button it changes its color to grey, text on the button also changes and the button itself becomes disabled until the cancel method is called for the button.

The following properties are available for changing such behavior:

Property Default value Description
autoBusy true Whether the button be disabled after clicking
busyLabel “Please wait” Text that will be displayed on the button while it is disabled
timeout 0 If specified, the button will enable itself after this time expires

The SDK supports an ability to define toolbar buttons with help of the Button module. The Toolbar module will on its own replace them with ToolbarButton widgets, but this is a bad style and you should avoid such usage of the Button widget.

Translation

In the dictionary, you can add translation of default text values contained in a widget by using one of the following options:

  • Translation by a common key independent of widget context. For example, the key might be ‘Please wait’.
  • Translation valid for the specified context where the widget is located. The context name must be presented in the key name in accordance with the schema ‘CommonKey_Context’. For example, if the context is *VPSedit, the key would by ‘Please wait_VPSedit’.
Key Context Default value
Please wait apsToolbarButton Please wait

Toolbar buttons separator

Using the ToolbarSeparator you can display a button separator on a toolbar.

Examples

  • declaration using the loader

    RUN DEMO

    require(["aps/load", "aps/ready!"],
       function(load){
         "use strict";
    
         load(["aps/PageContainer", [
               ["aps/Toolbar",
                     [[ "aps/ToolbarButton", {
                            label:      "Export configuration",
                            iconClass:  "sb-export",
                            onClick:    function(){ alert("Hello!"); } } ],
                      [ "aps/ToolbarButton", {
                            label:      "Add New Server",
                            iconClass:  "sb-add-new-server",
                            onClick:    function(){ alert("Hello!"); }
                     }]
         ]]]]);
     });
    
  • programmatic definition

    RUN DEMO

    require([
      "aps/Toolbar",
      "aps/ToolbarButton",
      "aps/ToolbarSeparator",
      "aps/PageContainer",
      "aps/ready!"
    ], function(Toolbar, ToolbarButton, ToolbarSeparator, PageContainer){
        "use strict";
    
        var page = new PageContainer({}, "testToolbar");
    
        var toolbar = new Toolbar();
    
        toolbar.addChild(new ToolbarButton({
          id:      "buttonAddNewCustomer",
          label:      "Add New Server",
          iconClass:  "sb-add-new-server",
          onClick: function(){
            alert("triam!");
          }
        }));
    
        toolbar.addChild(new ToolbarButton({
          id:      "buttonExportCustomers",
          label:      "Export configuration",
          iconClass:  "sb-export",
          onClick: function(){
            alert("triam!");
          }
        }));
    
        toolbar.addChild(new ToolbarSeparator({}));
        page.addChild(toolbar);
    
        page.startup();
    });
    
  • declarative definition

    require(["dojo/parser", "aps/ready!"],
      function(parser){
        "use strict";
        parser.parse();
    });
    

    RUN DEMO

    <div dojoType="aps/PageContainer">
      <div dojoType="aps/Toolbar">
        <div
          dojoType="aps/ToolbarButton"
          label="Add New Server"
          data-dojo-props="iconClass: 'sb-add-new-server'"
        ></div>
        <div
          dojoType="aps/ToolbarButton"
          label="Export configuration"
          data-dojo-props="iconClass: 'sb-export'">
            <script
              type="dojo/on"
              data-dojo-event="click"
            >
              alert("hurrah!");
            </script>
        </div>
      </div>
    </div>
    

More detailed information on widget declaration see in Widget Declaration.