Integrate the module with KTML's interface

In this topic of the tutorial you will create a new button in one of the KTML's toolbars that will make use of the server-side module created in the previous topic and insert the current date and time in the editor. The server returned date will be inserted at the cursor's selection point.

The steps you have to take to create the button and add functionality are:

1. Create the needed folder and file structure of a standard module

2. Create the standard JavaScript functions of every module

3. Use a built-in KTML API function to create a custom button

4. Customize the function used to make the server request and insert the returned string in the page.

5. Load the module into the KTML page.

Create the files and folders

Inside the <site_root>includes\ktm\modules\ folder, make a new folder for the new module with the name current_date. This folder name is internally used as a variable, so you cannot use spaces or other illegal characters for a variable name. KTML will search for three JavaScript (*.js) files inside this folder, namely:

1. scripts_mozilla.js - stores parts of the JavaScript code that is specific for Mozilla browsers.

2. scripts_ie.js - stores parts of the JavaScript code that is specific for Internet Explorer.

3. scripts.js - stores JavaScript code that can be executed on both platforms mentioned above without problems.

These files are used to provide a cross-browser compatibility solution, allowing you to add code that is specific for a particular browser in its own file. Since this module will not have any cross-browser problems, you will only have to create the scripts.js file.

Note: You should try not to put code that is common to IE and Mozilla into scripts_mozilla.js or scripts_ie.js.

Create the standard JavaScript functions

In the scripts.js file you have to define two standard functions. You will not add code for any of them yet, but you must declare them. The functions are:

1. current_date_runonce - the function name must use the module name as a prefix. This function is executed only once per page, regardless of the number of KTML editors in use. The code to declare this function is:
   
   function current_date_runonce() { }
    

2. current_date_runeach - this function is executed by each instance of KTML on page. The code is:
   
   function current_date_runeach()
    

Use the KTML API to add the button

As the current_date_runonce function will be called for each instance of a KTML editor within the page, put here the code needed to create our new button.  There are two methods of the ktml.toolbar object you can use for this purpose: insertButtonAfter and insertButtonBefore.

Both functions take the same parameters:

• The first parameter is an instance of the new button to insert

• The second is the id of the button to insert after/before. The second parameter is optional.
  Note: see “Creating a client side module” for information about the new ToolbarButton constructor.

The code for the function is as follows: (replace the blank definition in scripts.js with the complete function below:

function current_date_runeach(k) {

var btn = new ToolbarButton({ 'group': 'insert',
'command_type':$KT_JS_STRING,
'button_type':'img',
'button_icon': KtmlRelativeImagePath + 'currentDate.gif',
'name':'current_date',
'command_string':'this.ktml.insertCurrentDate()'
});
k.toolbar.insertButtonAfter(btn, '');
}

The button has the name current_date, and to retrieve the information will call a function named insertCurrentDate. For the button icon, the currentDate.gif file has been selected. You must copy this file from the downloaded package into includes/ktm/core/img. The KtmlRelativeImagePath function returns the correct path to this folder.

The button will look like this:

This function has to be made available to KTML. This is done via prototyping, and the code has to be placed in the current_date__runonce function, since it needs to be defined only once:

function current_date_runonce() {

ktml.prototype.insertCurrentDate = ktml_insertCurrentDate;

}

Create the custom function that gets the date

Now create the insertCurrentDate function itself. It will do two things.:

1. It will make a server request to a method named getCurrentDate of a module named date - the one created here.

2. It will  insert the server response string in the page at current selection (by using the insertHTML method of the KTML object.

The function will be created in the <site_root>includes\ktm\modules\scripts.js file, and its code is like the following:

function ktml_insertCurrentDate() {

var _this = this;
this.makeRequest("date", "getCurrentDate", "",

function(result){

_this.insertHTML(result, is.mozilla?"after" : "");

}) ;

}

Load the modules in the page

The last thing to do is to declare the module and instruct the page containing the KTML control to load it. To do so, follow the next steps;

1. Open the <site_root>\includes\ktm\core\modules.js file with a text editor.

2. If you haven't created any modules yet, the file contains an empty array. Add a new entry to it, with the same name as the module you've created. The new code inside the file should resemble:
   
   // Copyright 2001-2005 Interakt Online. All rights reserved.
   //if you wish to use new modules, please add them to the variable below
   KtmlUserModuleList = {
   "current_date" : ["main"]
   };
    

3. Save the file and close it.

4. Open the file containing the KTML control. Before the <link> tag in the head section, add the following line:
   
   <script src="includes/ktm/core/modules.js" type="text/javascript"></script>
    

5. Now the block of code should resemble:
   
   <script src="includes/resources/ktml.js" type="text/javascript"></script>
   <script src="includes/ktm/core/modules.js" type="text/javascript"></script>
   <link href="includes/ktm/core/styles/ktml.css" rel="stylesheet" type="text/css">
    

6. Save the page and close it.

Save the file and place it on the server. Then open a page containing the KTML control and start using the new module.