FIXME: Look over new file...

note: for 0.4 (cvs) please read: [!/040]. If you have old modules, have a look at ModulePorting? for a quick overview what has changed.

note: as of version 0.4 the Maintenance module now has a utility to help you generate the skeleton files needed for creating a new module.

note: DirectoryStructure? changed in cvs now (24. May 2004, version 0.3.8)!

THIS TUTORIAL IS FOR 0.3 BRANCH ONLY! FOR 0.4.0 LOOK AT [!/040] INSTEAD

Introduction

OK, you want to create your own module of Seagull? That's fine!

note: This tutorial may help you, but it's still not 100% complete yet. You can use it for getting information on how modules work, for better understanding of Seagull... Please have also a look at the faq module (this is pretty simple...) and see how this one is done.

You can choose a module that's similar to your needs and modify it, or begin with a new one. In the first case, just copy the old module files and directories and rename it properly...

In this tutorial, i want to create a module for managing bookmarks or favourite URLs, it will be based on the faq module. It should:

  • output a orderd list of URLs to other pages (library of bookmarks), with logo, text, counter, bad link button etc.
  • order this links in categories (nestedSet??)
  • redirect to the URL, counting how often one link was clicked
  • everyone can mark a link as bad (e.g. outdated)
  • registered users (with the proper right) can add or modify links

This tutorial needs some basic knowledge of PHP, PEAR, and Seagull. For better understanding, these links are also useful:

Files and Directories to create

To get an overview of workflow in Seagull please see the BasicWorkflow? diagram. note: this is new in SGL 0.3.8

  • modules/bookmark/: the directory for modules classes, langfiles...
  • modules/bookmark/classes/: this directory is for the classes
  • modules/bookmark/lang/: this for the language files
  • www/themes/default/bookmark/: and this for the templates
  • www/bookmarkMgr.php: the basic php file that is called by the browser
  • modules/bookmark/conf.ini: for some configuration
  • var/cache/entities/Bookmark.php: the extended DB_DataObject entity for this module note: this file will be autogenerated by Seagull

SQL

In this example i add a new table to the database:

note: this is the first version of my database table. will surely be optimized. I'll explain it later ;)

CREATE TABLE `bookmark` (
  `bookmark_id` int(11) NOT NULL default '0',
  `date_created` datetime default NULL,
  `last_updated` datetime default NULL,
  `url` varchar(255) default NULL,
  `name` varchar(255) default NULL,
  `text` text,
  `count` tinyint(4) NOT NULL default '0',
  `item_order` int(11) default NULL,
  PRIMARY KEY  (`bookmark_id`)
) TYPE=MyISAM;

To create the DataObject? entity

  • log in as admin
  • go to the ~Maintainance Mgr
  • click on ~'Rebuild DataObjects ~Now'
  • click on ~'Rebuild Sequences Now'

This will create the file var/cache/entities/Bookmark.php and insert a new record into the 'sequence' table

Code examples

to be continued ;)

www/bookmarkMgr.php
<?php
''    initialise
    require_once '../init.php';
    require_once SGL_CORE_DIR . '/Controller.php';
    require_once SGL_MOD_DIR . '/bookmark/classes/BookmarkMgr.php';
    error_log('```````#    NEW PAGE RUN - BOOKMARK MGR    ```````#');
    $process = & new SGL_Controller();
    $process->page = & new BookmarkMgr();
    $process->go(new SGL_HTTP_Request(];
?>
/modules/bookmark/conf.ini

See UsingConfigFiles? for better understanding.

/modules/bookmark/classes/BookmarkMgr.php

See CreatingYourOwnModulesSource?

Templates

All templates are in the directory /www/themes/default/bookmark/

Translating your output

All translation of the output should be done in templates. Don't use the SGL_Output::translate() function in your classes. This is for translating errors etc.

You may use the following functions in the templates:

  {translate(pageTitle)} ''for pagetitle
  {translate(#foobar#)} ''for translating the string 'foobar'  

note: this is just for GUI output yet, no content translation is possible at the moment.

See also TranslatingModules?

Example: bookmarkList.html

This one is for outputing the list. Look at the {foreach:results,key,valueObj}''-loop...

<flexy:include src="banner.html" />
    <form name="users" method="post" flexy:ignore id="users">
        <input type="hidden" name="action" value="delete" />
        <h1 class="pageTitle">{translate(pageTitle)}</h1>
       <span flexy:if="msgGet()">{msgGet()}</span> 
        <table border="0" cellspacing="1" cellpadding="5" width="90%">
        {if:results}
             {foreach:results,key,valueObj} 
            <tr>
                <td><a href="bookmarkMgr.php?action=redirect&bookmarkId={valueObj.bookmark_id}" target="_blank">{valueObj.name}</a></td>
                <td align="right">{formatDate(valueObj.last_updated)}</td>
            </tr>
            <tr>
                <td colspan="2">{valueObj.text:h}</td>
            </tr>
            <tr>
                <td>{translate(#Clicked#)} {valueObj.count} {translate(#times#)}</td>
                <td colspan="1" align="right">
                    <a href="#{valueObj.bookmark_id}" align="right">{translate(#Bad URL?#)}</a> | 
                    <a href="#">{translate(#back to top#)}</a></td>
            </tr>
            <tr>
                <td colspan="2"> </td>
            </tr>
            {end:}
            {else:}
            <tr>
                <td>{translate(#No Links found#)}.</td>
            </tr>
            {end:}
        </table>
    </form>
<flexy:include src="footer.html" />

Add the module to the ModuleMgr?

Next add the new module into the module manager. So:

  • login as admin
  • hit the 'manage' button on the top left
  • hit 'Add a module' button
  • fill the form with:
    • Name: directory name of the module. If you have created a bookmark module, as in the wiki tutorial, you must write 'bookmark' here. The 'name' string will be used to identify the module uniquely so
      • use lowercase only
      • no spaces allowed
      • try and stick with single words and avoid bumpyCaps
    • Title: descriptive name of the module, this can be multiple words, etc.
    • Configurable: if the module can be configured inside the 'Module Manager' activate this checkbox
    • Description: this text will be used in the 'Module Manager' to describe this module
    • Admin URI: the name of the startfile of your module, ie, bookmarkMgr.php
    • Icon: filename (without path) of the icon used in 'Module Manager'
  • At the end hit 'Add' button. This will bring you back to the 'Module Manager' screen. Your new module has been added at the end of the list of modules.

Assign the relevant Permissions

So we move into the 'Users & Security' module.

Presuming you have already setup roles (groups of permissions) in the system, now you're ready to add permissions corresponding to each of the new action methods you've created in your manager class:

  • in the 'Users & Security' module select the 'manage permissions' button
  • add a permission for each action method you have created, ie:
    • permission name is made of class name and method name e.g.
      • our class is 'BookmarkMgr?' and method is called 'edit', perm must be called bookmarkmgr_edit
    • please user lowercase for all permission names
  • after you've created all the required perms, select the 'manage roles' button
  • select the role you wish to add the perms to, and in the Permissions column, hit the relevant 'change' button
  • the right box represents all the perms assigned to the role, the left, all other perms
  • use the widget to select your new perms in the left box, move them to the right box, and hit 'submit'
  • any new user created in that role will inherit the new permissions you've created
  • the public role, which is not user specific, will show the correct behaviour with any new perms added to it once you close the browser and open a new one (since perms are stored in a cookie which lasts the lifetime of the browser)
  • note: currently perm assignments are not retroactive
  • ALTERNATIVELY, you can select an individual user from the 'manage users' section, and in the Permissions tab hit 'change', then activate the new perms one at a time. This manager allows you to filter the perms by module.