Customize the KTML toolbars

In this tutorial you will learn how to customize the KTML toolbars and buttons by changing code in the page, or using the JavaScript API. The three main subjects covered in this topic are:

1. Re-order the buttons for a KTML control instance.

2. Create a new toolbar.

3. Create a custom button and add it to one of the existing toolbar.

Re-order a toolbar's buttons

To change the order in which buttons are displayed within a toolbar for one of the KTML instances you must change the code that sets the control properties in the particular page. For example you want to place the spellcheck and toggle between code and design view buttons first in the toolbar.

By default, the toolbar looks as follows:


 

To make the desired buttons appear first, follow the next steps:

1. Open the page that contains the KTML control applied.

2. Locate the area that defines the toolbars and their buttons. It should look similar to the following:
   
   "buttons": [
            [1, "standard", ["cut", "copy", "paste", "undo", "redo", "find_replace", "toggle_visible", "spellcheck", "toggle_editmode", "toggle_fullscreen", "help"]],
            [1, "formatting", ["bold", "italic", "underline", "align_left", "align_center", "align_right", "align_justify", "numbered_list", "bulleted_list", "outdent", "indent", "clean_menu", "foreground_color", "background_color", "superscript", "subscript"]],
            [2, "styles", ["heading_list", "style_list", "fonttype_list", "fontsize_list"]],
            [2, "insert", ["insert_link", "insert_anchor", "insert_table", "insert_image", "insert_file", "insert_template", "horizontal_rule", "insert_character"]],
            [3, "form", ["insert_form", "insert_textfield", "insert_hiddenfield", "insert_textarea", "insert_checkbox", "insert_radiobutton", "insert_listmenu", "insert_filefield", "insert_button", "insert_label", "insert_fieldset"]]
        ]
    

3. The buttons to change are in the standard toolbar on the first row. You have to move the button definitions first, and the line that results should be:
   "buttons": [
           [1, "standard", ["spellcheck", "toggle_editmode", "cut", "copy", "paste", "undo", "redo", "find_replace", "toggle_visible",   "toggle_fullscreen", "help"]],
    

4. Save the page and reload it in the browser. It will display the buttons in the desired order now:
   
   
    

The order of the buttons has changed.

Create a new toolbar

When you create a module to add functionality to KTML you must also create a way to access it. You can do that by adding a button into an existing toolbar, or into a new one. To create a new toolbar for a KTML control you must change the code in the page where the KTML control is configured:

1. Locate the code section that sets the toolbars and buttons for the editor. It should resemble the following:
   
   "buttons": [
           [1, "standard", ["cut", "copy", "paste", "undo", "redo", "find_replace", "toggle_visible", "spellcheck", "toggle_editmode", "toggle_fullscreen", "help"]],
           [1, "formatting", ["bold", "italic", "underline", "align_left", "align_center", "align_right", "align_justify", "numbered_list", "bulleted_list", "outdent", "indent", "clean_menu", "foreground_color", "background_color", "superscript", "subscript"]],
           [2, "styles", ["heading_list", "style_list", "fonttype_list", "fontsize_list"]],
           [2, "insert", ["insert_link", "insert_anchor", "insert_table", "insert_image", "insert_file", "insert_template", "horizontal_rule", "insert_character"]],
           [3, "form", ["insert_form", "insert_textfield", "insert_hiddenfield", "insert_textarea", "insert_checkbox", "insert_radiobutton", "insert_listmenu", "insert_filefield", "insert_button", "insert_label", "insert_fieldset"]]
       ]
    

2. Add a new toolbar entry before the last closing ] sign. The format is: [row_number, "toolbar_name", [comma_separated_button_list]]. For example, to add a new toolbar on the third row with some of the default buttons, you would add the line:
   
   [3,"extrabar",["cut", "copy", "paste", "undo", "redo"]]
    

3. Save the page and load it in a browser. The toolbar you have defined will show up last:
   
   
    

Add buttons to a toolbar using API calls

When you create a module or extend an existing one you want to add a way for it to be accessed by the user. And the easiest way is to add a button into one of the existing or a new toolbar. The API method to use is: ktml_name.addCustomButton(button_instance_name, 'button_to_insert_after', group_index). The parameters are:

• button_instance_name - the name of a variable that holds an instance of the button class

• button_to_insert_after - the name of an existing button on the toolbar after which you want to add your custom button.

• group_index - number which represents the toolbar ID

To better understand, consider the following example: you have create a custom function - myCustomFunction which will be accessed through a button that will be placed after the Paste button, in the first toolbar. The steps you must take are:

1. Create your custom function in the module.

2. Create a new button instance, which will use an image and calls the custom function:
   
   var myCustomButton = new ToolbarButton({
          'name': 'custom_button',
          'button_type': 'img',
          'button_icon': KtmlRelativeImagePath + 'glyph.gif',
          'command_type': $KT_JS_STRING,
          'command_string':'myCustomFunction(this.ktml)'
      });
    

3. Call the API method that inserts the button in the correct position:
   
   ktml_textarea1.addCustomButton(myCustomButton, 'paste', 0);
    

4. Save the module, and if everything else is correct, the button will show up in the toolbar. If the button you've specified does not exist in the toolbar, the custom button will be placed at the end. Also, if the toolbar ID is missing, the last one will be used.