| Table of contents |
|---|
|
This example module will run through all of the basics covered in the Module Guide section. The basics behind the module will be simple but are designed to give you a better understanding on how to create a working module.
Folder Setup
 | Creating a module guide reference page: ?Directory and File Layout |
To start first create a folder called helloword in the __modules folder, in that folder we will create the following folders:
- __modules/helloworld/admin/
- __modules/helloworld/api/
- __modules/helloworld/client/
- __modules/helloworld/config/
- __modules/helloworld/library/
- __modules/helloworld/locale/
- __modules/helloworld/staff/
config.xml Setup
| Creating a module guide reference page: Configuration (config.php) Files |
With this folder setup we will then add the config.xml file to the config folder. The layout of the config.xml file will be like follows:
Database Setup File
To start create a file in the __modules/helloworld/config/ folder called class.SWIFT_SetupDatabase_helloworld.php
Class declaration
| Creating a module guide reference page: ?Handling Module Install, Upgrade and Uninstall |
Install function
| Creating a module guide reference page: Handling Module Install, Upgrade and Uninstall |
Upgrade function
| Creating a module guide reference page: Handling Module Install, Upgrade and Uninstall |
Uninstall function
| Creating a module guide reference page: Handling Module Install, Upgrade and Uninstall |
LoadTables function
| Creating a module guide reference page: ?Database Setup |
This function creates a single table called helloworld which contains 3 columns:
| Column Name |
Description |
|---|---|
| helloworldid | The unique ID for each entry into the database |
| phrase1 | A simple phrase (example: hello) |
| phrase2 | The second phrase (example: world) |
Complete file
With these functions in place the module is ready to be installed and used, it will not have any functionality yet but it can be installed into the Kayako environment.
Locale
| Creating a module guide reference page: ?Module Localization |
Creating the files
To start a locale file needs to be created. This file is created in the following location:
__modules/helloworld/locale/en-us/helloworld.php
When the file is created it should be set up to contain all of the language references that the module will use. To begin with there will only be one entry but as the module develops more and more entries will be added. The code in the locale file will look like the following:
With the locale file set up then it is ready to be used within the module.
Settings Page
Now we will create a basic settings page that will be used to determine which phrases are displayed.
settings.xml
The first step is to create the settings XML that will contain our different settings.
Creating the files
| Creating a module guide reference page: Module Settings |
First step is to create the file. The file name is settings.xml and it belongs in the config folder.
Its location should look like this:
__modules/helloworld/config/settings.xml
Once the file is created we need to add this code to it:
That will give us two settings, which will determine if we should display the first part of the phrase and if we should display the second part of the phrase.
Loading the settings file
| Creating a module guide reference page: Module Settings |
Once the file has been created, we need to load it during the install of our module in order to access these settings. To do so we need to open this file:
__modules/helloworld/config/class.SWIFT_SetupDatabase_helloworld.php
At the bottom of the class we will want to add this function:
This function will load out new settings into Kayako so that we can use them.
Now we need to add a call to this function in both the Install and Upgrade functions inside this file. The functions will then look like this:
Settings manager
| Creating a module guide reference page: Module Settings |
Once the settings have been loaded into Kayako these settings are ready to be used and modified. To modify them we need to add a settings manager page.
Modifying the config file
The first step is to modify the configuration file to add a link to the settings page that will be created.
To add a link to the settings page you must first add a tabs element to the config file. Inside the tabs element a tab element will be added. This tab element will add the menu item to the admin control panel. Inside the tab element is where the tabitem elements are added, which are the sub menu items. It is the tabitem that will link to the settings manager page.
Updating the config file in this manner will make it look like the following:
Setting up the files
Once the config file has been updated with a link to the settings manager it is now time to create the settings manager. To do this we need to create a new file in the admin folder called class.Controller_SettingsManager.php which makes the file location for the file this:
__modules\helloworld\admin\class.Controller_SettingsManager.php
Inside the file the first step is to set up the constants, constructor and desctructor. These functions will look like this:
In addition to these functions we require another function that will be responsible for displaying and processing the actual settings manager page. This function looks like this:
With that function in place the settings manager page is almost ready to be used. The last step is to create the language files for the settings page.
Settings Locale file
| Creating a module guide reference page: Module Settings |
After the settings manager file is created a settings locale file needs to be created in order to properly display all of our settings.
The first step is to set up the locale file for the settings. To do this wee need to create the following file in the following location:
__modules\helloworld\locale\en-us\settings.php
This is the new file that contains all of the text for the settings. Each setting name that was set up in the settings.xml will look here automatically for the corresponding text value. So for our example the file will look like this:
With the locale file in place the settings manager page is ready to be used.
Simple admin page
| Creating a module guide reference page: Admin Control Panel Functionality |
Here a simple page will be created that will simply show a string based on the setting created above.
Creating the files
To start the new page files need to be created. There are two files that need to be created the controller file and the view file.
They will be created in the admin folder of the module, the final paths of the two files will look like this:
_modules/helloworld/admin/class.Controller_HelloWorld.php
_modules/helloworld/admin/class.View_HelloWorld.php
Controller
The controller file is used to determine how to render a page and handle and input to the page. This controller will be simple and consist of a constructor, destructor, a render function and two constants.
Constructor
The constructor is responsible for loading the language file and calling the base constructor.
Desctructor
The desctructor is responsible for calling the base destructor.
Render
The render function is responsible for displaying "Hello World" on the screen. It does this by calling four built in functions that are used to render all the other components on the screen.
The Header function sets up the begging of the HTML and the header and menus of the control panel.
The start function renders the left hand panel and the beginning of the containing HTML for the custom page.
The next call is to a custom rendering function declared inside the view file. This function will be described below.
The end function renders the closing tags from the start function.
The footer function finishes the page by rendering the footing information and the closing tags to the pages HTML.
Constants
The constants are used to tell Kayako which tabs to be focused on in the menu system, just like the settings manager constants.
The controller file will look like the following:
With that code in place the controller file is ready to be used.
View
The view file is where the actual rendering of our page is done. Like the controller this page is simple and consists of a constructor, desctructor and rendering function.
Constructor
The constructor is responsible for loading the settings information and calling the base constructor.
Destructor
The desctructor is responsible for calling the base destructor.
Render
The render function is responsible for checking out setting to see if we are supposed to render "Hello World". If so it displays it on the page, if not it displays a different phrase.
The view file will look like the following:
With that the view file is now ready to be used and the simple hello world page is done. All that is left is to link it to a menu item.
Creating the menu item
After the files are created the next step is to add the menu item so that the new page can be accessed. To do this we mush open up the config file, which is located at:
_modules/helloworld/config/config.xml
Under the admin tab a new tab item needs to be added that will link us to the new Hello World page.
Adding this new menu item will link us to the new page, depending on how the Show Phrase setting is set will change what this page shows us.
This was a simple example of how to create a page inside of Kayako that follows the structure and demonstrates some of the basic concepts. For more complicated examples keep on reading this guide.
Simple submit page
This example page will show the basic process for submitting data back to the page for processing. It will use files that have all ready been created by adding functionality to them.
Updating code files
The first step is to update the controller and view file that was created in the previous page example. To do this we need to open these two files:
_modules/helloworld/admin/class.Controller_HelloWorld.php
_modules/helloworld/admin/class.View_HelloWorld.php
Controller
In the controller file two functions need to be added to the bottom of the class. One function for displaying the submit page and one for processing the submit request.
SubmitExample
This function is responsible for rendering the submit controls, much like the other render function this one checks to see if the class is loaded.
Then it proceeds to render the header information.
After the header is loaded it calls a custom rendering function from the view file.
Then it renders the footer information.
ProcessSubmit
This function is responsible processing any submit requests.
It first checks to see if the class is loaded.
Then it checks to see if an expected parameter has been posted to the page, if it has it sets a variable with the submitted value.
Then it calls the previous function to render the submit page.
That is all of the updates required for the controller file.
View
The view file has a single function that needs to be added to the end of the class.
This function is used to display the submit page and any information posted back to the page.
To start it checks to see if the view class is loaded.
It then calls the start function which sets up the post back information to be passed to the ProcessSubmit function set up in the controller file.
Then a button is added to the tool bar that is used to post the data back to the page when clicked.
After the button is added a new tab is made which will contain all of the information to be displayed.
Next a text box is added to the tab, this is the information that is sent back to the page for processing.
Then the code determines if the submit button was clicked and if it was it displays the data that was submitted, if nothing was submitted then it displays a message saying that nothing was submitted.
Last it calls the end function which closes all the open tags from the start function.
With this change the new submit functionality is completed all that is needed is to add another menu item so that this page is accessible.
Language file updates
A few changes to the language file are required so that all of the information is properly displayed.
To start the language file must be opened, it is located at:
_modules/helloworld/locale/en-us/helloworld.php
This file needs to be updated to look like the following:
Config file updates
Updates to the configuration file are required in order to add another menu item so that this page is accessible. To do this we mush open up the config file, which is located at:
_modules/helloworld/config/config.xml
Under the admin tab a new tab item needs to be added that will link us to the new submit page.
With this change to the config file the submit example is now accessible from the menu in the admin control panel.
This example shows the basics for submitting information back to a page for processing.