Creating a module: Hello World (Complete guide)

[Sheep]

This is a new thread created from Creating a module: Hello World - Kayako Community Forums by greengiant

As his guide isn't enougth i though starting a new one (the first part of this guide have been taken from the guide by greengiant).
I'm creating a new thread because i'll update this one as soon as i find new tips and that should be quite often (i'm making a module atm).

This guide covers:
Creating a new module,
Creating the module installation process (database table creation),
Creating a new tab in the staff (and admin) pannel,
Creating a widget in the client side


A Helloworld module is a sample where the purpose is to display hello.

If you want to know more take a look at the download module.

== Updates==
26/06/07 - added: admin tab & client widget
26/06/07 - corrected some stuffs
26/06/07 - sample screenshot
25/06/07 - initial guide

== Screenshot ==





== Hello World Module ==

-- Creating the module setup --

1. Create a Folder called helloworld in you modules directory.

2. Create a setup.php file in the new helloworld folder.

3. Creating the basic setup file. - In this setup file we are going to register the module during install and create a simple mysql table called helloworld, which contains two fields.

PHP Code:

        <?php
            //Hello World Module
 
            if (!defined("INSWIFT")) {
                trigger_error("Unable to process $PHP_SELF", E_USER_ERROR);
            }
 
            /**
            * Called when the module is to be installed
            * function name is _MODULENAME_install
            */
            function _helloworld_install($action, $page = '') {
                global $_SWIFT, $__LANG;
 
                if ($action == "getpages") {
                    return "1";
                } else if ($action == "buildpage") {
                    $_SWIFT["query"]["create"]["helloworld"]="CREATE TABLE ".TABLE_PREFIX."helloworld (
                    helloworld_id INT UNSIGNED NOT NULL AUTO_INCREMENT,
                    helloworld_text VARCHAR(255) NOT NULL DEFAULT '',
                    PRIMARY KEY (helloworld_id)
                    );";
 
                    //Tell Esupport about the module.
                    $_SWIFT["query"]["insert"]["settings"][0]=
                        "INSERT INTO `".TABLE_PREFIX."settings`(`section`, `vkey`, `data`) VALUES('registeredmodules', '".MODULE_HELLOWORLD."', '1')";
                }
            }
 
            /**
            * Uninstall Routine
            * function name is _MODULENAME_uninstall
            */
            function _helloworld_uninstall() {
                global $_SWIFT;
 
                $_SWIFT["query"]["drop"]["helloworld"]="DROP TABLE `".TABLE_PREFIX."helloworld;";
 
                //Tell Esupport We are removing the module.
                $_SWIFT["query"]["delete"]["settings"][0]=
                    "DELETE FROM `".TABLE_PREFIX."settings` WHERE `section` = 'registeredmodules' AND `vkey` = '".MODULE_HELLOWORLD."';";
            }
        ?>

5. Edit your Site Config.php file and find the lines:
define("MODULE_PURCHASE", "purchase");
define("MODULE_SERVERS", "servers");

6. Add the following line after the above code. The first argument is the name of the constant that is used in the setup.php file that we just created to register the module with esupport. The second argument is the name of the module folder.

PHP Code:

    define("MODULE_HELLOWORLD","helloworld"); 


7. Edit your Site Config.php file and find the lines:

PHP Code:

    $_MODULES[MODULE_PURCHASE] = dirname(__FILE__)."/../modules/purchase/purchase.php";
    $_MODULES[MODULE_SERVERS] = dirname(__FILE__)."/../modules/servers/purchase.php"; 


8. Add the following line. This is the path to the main file for your module, that we will create in the next step.

PHP Code:

    $_MODULES[MODULE_HELLOWORLD] = dirname(__FILE__)."/../modules/helloworld/helloworld.php"; 


this being done the module will display on the setup page (if you've not deleted it)
emailMyName- Low-cost email address - 1GB email storage - Block spam - Web & POP3 email access - Get your name as your email address
click on the "modify" link, then go to the last step and there you'll be able to install/uninstall the module

Now our module can be registered but can't do anything.
Lets do our basic helloworld.

-- Adding events handler --

9. Create "modules/helloworld/helloworld.php" including

PHP Code:

<?php
if (!defined("INSWIFT")) {
    trigger_error("Unable to process $PHP_SELF", E_USER_ERROR);
}
/**
* Helloworld Module
*/
class helloworld {
    /**
    * Constructor to register any events, sections
    */
    function helloworld() {
        global $_SWIFT, $events;
        $events->registerEventModuleSWIFT(MODULE_HELLOWORLD, $this);
        // Staff CP
        $events->registerEvent(EVENT_STAFF, MODULE_HELLOWORLD, "hello1");
        $events->registerEvent(EVENT_STAFF, MODULE_HELLOWORLD, "hello2");
 
        $eventaction = $events->eventdata["eventaction"];
    }
    /**
    * Destructor, called to unregister any events etc
    */
    function _helloworld() {
    }
    /*
    * Call back function
    */
    function _eventcallback($eventtype, $eventaction)
    {
        global $_SWIFT, $interface, $template, $departments, $staffauth, $module, $grid, $xml, $staff, $settings, $dbCore, $events, $session, $loginshare, $cookie, $errormessage, $infomessage, $permissions, $mimelist;
        if ($eventtype == EVENT_STAFF && ($eventaction == "hello1")) {
            require_once ("./modules/helloworld/hello1.php");
            return true;
        } else if ($eventtype == EVENT_STAFF && ($eventaction == "hello2")) {
            require_once ("./modules/helloworld/hello2.php");
            return true;
        }
 
        return false;
    }
}
?>

Now our module knows how to handle some events, you'll have to add events there.

10. Create "modules/helloworld/hello1.php" including

PHP Code:

<?php
$template->loadLanguageSection("helloworld");     
    $interface->staffHeader("helloworld&gt; hello1", 0);
    $interface->staffNavBar('<a href="index.php?_m=helloworld&_a=hello1" title="hello1">hello1</a>', "", 0);
    //printInfoBox($infomessage);
    //printErrorBox($errormessage);
    echo "Helloworld1!";
    $template->assign("backurl", "index.php?_m=helloworld&_a=hello1");
    $interface->staffFooter();
?>

Now our module handles hello1 action (?_m=helloworld&_a=hello1);
Repeat 10. to create hello2 (and modify all the hello1 to hello2 of course!)


-- Creating the tabs --
11. Open "locale/en-us/en-us.php"
12. Find

PHP Code:

$_SWIFT["staffmenu"] = array ( 


13. Add at the end of this array

PHP Code:

        10 => array ('Rights', 90, MODULE_HELLOWORLD, 3, 'hw_entab'), 


This is our new main tab

14. Look a bit further and find the

PHP Code:

$_SWIFT["stafflinks"] = array ( 


15. Add at the end of this array

PHP Code:

        10 => array (
                0 => array ('Hello1', "index.php?_m=helloworld&_a=hello1", false, true),
                1 => array ('Hello21', "index.php?_m=helloworld&_a=hello2", true, true),
                2 => array ('Hello2', "index.php?_m=helloworld&_a=hello2", true, false), 
                ), 


This is our submenu

Our menu has the id 10 so we have to change our parent in the hello1 & hello2 script

16. In modules/helloworld/hello1.php Search for

PHP Code:

    $interface->staffHeader("helloworld> hello1", 0);
    $interface->staffNavBar('<a href="index.php?_m=helloworld&_a=hello1" title="hello1">hello1</a>', "", 0); 


Notice the ", 0);"
change the 0 to 10 (our menu id)
This id is the tab selected (can be different from helloworld) so if you want to change it, you can.

Now the submenu cache needs to be rebuilt:
Go to emailMyName- Low-cost email address - 1GB email storage - Block spam - Web & POP3 email access - Get your name as your email address
Unlog from the staff pannel
Log in again
(If the new tab doesn't appear try to clean your browser cache)

To play with the admin pannel tabs that's the same thing.
Restart from 11. but play in the zone:

PHP Code:

if (SWIFT_AREA == SWIFT_ADMIN) 


To play with the basic settings in the admin tab you should take a look at "modules/core/admin_settings.php" as you'll have to insert reccords in the database.

-- Creating a widget --
17. Open includes/Widgets/widgets.php
You'll find here all the widgets and their permissions checks
Lets add our basic widget
18. Search

PHP Code:

/**
* ###############################################
* !! DO NOT EDIT ANYTHING BELOW THIS POINT !!
* ###############################################
*/ 


19. add before

PHP Code:

// ======= HELLOWORLD =======
if ($module->isRegistered(MODULE_HELLOWORLD))
{
$_widgets[$index]["icon"] = $_SWIFT["themepath"]."helloworld.gif";
$_widgets[$index]["title"] = "Helloworld";
$_widgets[$index]["description"] = "Hello world!";
$_widgets[$index]["link"] = "index.php?_m=helloworld&_a=view";
$index++;
} 


20. Customize
Dont forget to put a new helloworld.gif in the theme folder (you can also use "downloads".gif etc..., just change the $_widgets[$index]["icon"])

21. You shouldn't harcode the title and descritions.
Lets change it using the language feature
You'll have to create the phases in the language administration

PHP Code:

    $_widgets[$index]["title"] = $_SWIFT["language"]["helloworld"];
    $_widgets[$index]["description"] = $_SWIFT["language"]["desc_helloworld"]; 


but now we need to register the event we've set in the link ( "index.php?_m=helloworld&_a=view" )
22. Open modules/helloworld/helloworld.php
23. in

PHP Code:

     function helloworld() { 


23. add after the staff CP events

PHP Code:

// Support Center
$events->registerEvent(EVENT_CLIENT, MODULE_HELLOWORLD, "view"); 


24. in

PHP Code:

    function _eventcallback($eventtype, $eventaction) 


25. add at the end of the ifcase our else if

PHP Code:

else if ($eventtype == EVENT_CLIENT && ($eventaction == "view")) {
            require_once ("./modules/helloworld/view.php");
            return true;
        } 


26. now create "modules/hellworold/view.php" including

PHP Code:

<?php
if (!defined("INSWIFT")) {
    trigger_error("Unable to process $PHP_SELF", E_USER_ERROR);
}
    echo $template->displayTemplate("header");
    echo "Hello world";
    $template->assign("backurl", "index.php");
    echo $template->displayTemplate("footer");
?>

For more advanced infos on templates take a look at the other modules.

---- END ----

[Siora]

Great work as always Antoine.

[richm]

Excellent Antoine! Can't wait to try it out. Just what I need to tie our FTP server into the client support site.

Rich

[Bconsulting]

Yes awesome great work.....

[Bconsulting]

Will you be providing anything in regards to the Admin side and the client side?

[Sheep]

Hmm....
i don't think i'll have to use the admin side in my module (or maybe should i handle staff permissions ? but i don't think that's needed in the specifications that i wrote, but if i had to do it "nicely" i should. so i'll see if i have time for this)
also for the client side, my module will be a plug-in (changing code comportment) and not a module (widget) so i don't think i'll have time to search how to handle widgets. Someone will have to. If anyone find anything post there and i'll update the guide.

so at the moment, the answer to your question is "no".


Edit: added a screenshot

[Sheep]

Update: added admin tab and client widget (yeah got bored)
here you are lbGURU, take a look at 16. and 17.+

Edit: added screenshot of the client widget

[supportskins]

This is great stuff! Thanks for sharing

[richm]

This would be an excellent article for the suportsuite wiki perhaps?

http://www.div0.com/supportsuite/index.php/Main_Page

Rich

[Sheep]

Seems like this wiki page is under easy spam. I guess the forum will be ok.
Btw: i didn't know there was a wiki. Who is doing this? Where should i have found the link?

[craigbrass]

I think http://www.div0.com/supportsuite/index.php/User_manual was a user started one Varun posted about in the news section a long while ago but not sure if this is what he is referring to.

[Jamie Edwards]

I do not think this support Wiki is being maintained. We (I) are currently working on an official Wiki, however.

[Bconsulting]

Originally Posted by Sheep

Update: added admin tab and client widget (yeah got bored)
here you are lbGURU, take a look at 16. and 17.+

Edit: added screenshot of the client widget

Thanks very much, my initial thinking around the admin side was for settings and how to add menu items to the left side....anyhow I am appreciative with what you have provided.

[Sheep]

It's also in the en-us.php

PHP Code:

if (SWIFT_AREA == SWIFT_ADMIN)
{
 /**
 * Admin Area Navigation Bar
 */
 $_SWIFT["adminbar"] = array ( 


And it's the first array

[greengiant]

glad someone found time to update my tutorial i started and never found time to complete. good work