Prerequisite
 |
| Dennis Iversen |
| 14-Feb-2011 09:23:54 |
Module Files
First we want to create some module files. (Note: This is a shell command and it will most likely only work on Linux. If the command does not work for you then you must create files manually):
./coscli.sh skeleton --create-mod blog_simple
This will produce something like the following:
Command [ok] mkdir /home/dennis/www/osnet/modules/blog_simple
Command [ok] mkdir /home/dennis/www/osnet/modules/blog_simple/mysql
Command [ok] mkdir /home/dennis/www/osnet/modules/blog_simple/mysql/up
Command [ok] mkdir /home/dennis/www/osnet/modules/blog_simple/mysql/down
Command [ok] mkdir /home/dennis/www/osnet/modules/blog_simple/lang
Command [ok] mkdir /home/dennis/www/osnet/modules/blog_simple/lang/en_GB
Creating files:
Command [ok] touch /home/dennis/www/osnet/modules/blog_simple/menu.inc
/home/dennis/www/osnet/modules/blog_simple/index.php
/home/dennis/www/osnet/modules/blog_simple/README.txt
/home/dennis/www/osnet/modules/blog_simple/install.inc
/home/dennis/www/osnet/modules/blog_simple/blog_simple.ini
/home/dennis/www/osnet/modules/blog_simple/blog_simple.ini-dist
/home/dennis/www/osnet/modules/blog_simple/model.blog_simple.inc
/home/dennis/www/osnet/modules/blog_simple/view.blog_simple.inc
/home/dennis/www/osnet/modules/blog_simple/lang/en_GB/system.inc
/home/dennis/www/osnet/modules/blog_simple/lang/en_GB/language.inc
As you can see this command just produces a lot of files. You don't need all these files. As a minimum you need an install file (install.inc), a model file (model.blog_simple.inc) and a controller file (e.g. index.php as in the above). Usually a website uses database so you will also need SQL files if you want to use a database. For our blog example we will use SQL. Let us create some SQL as the next task:
SQL Files
We start of with creating some SQL for storing the blog posts. Open a file like:
./modules/blog_simple/mysql/up/1.01.sql
In this file we will place your SQL which will be executed when we install version 1.01 of our module. The mysql/up and mysql/down is used when we want to install, uninstall, and upgrade modules. Open the above file in a text editor and place the following SQL:
DROP TABLE IF EXISTS `blog_simple`;
CREATE TABLE `blog_simple` (
`id` int(10) NOT NULL AUTO_INCREMENT,
`title` varchar(128) NOT NULL,
`content` text,
`updated` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,
`user_id` int(10) unsigned DEFAULT NULL,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=UTF8;
As you should notice there is a line space between each statement. You should remember this because each statement is executed after one and another. So always remember a newline between each statements!
The table contains a field for title, a field for the blog entry and a timestamp field for update information, and a user_id field for seeing which user has made the blog entry. We also make a sql file for removing the table on uninstall. Open this file:
./modules/blog_simple/mysql/down/1.01.sql
In this file we place the following sql:
DROP TABLE IF EXISTS `blog_simple`;
Install File
Now we have some SQL, and we like to install this SQL (and the module). In order for doing so, we open our install file and sets the current version for the module. Open:
./modules/blog_simple/install.inc
And place the following php code in it:
<?php
// This sets the version of the module.
// Note that the version follows sql.
//
// If we wanted to update our SQL at a later point
// we will add a fill to the 'up' dir where we place a
// e.g. 1.02.sql file and update $_INSTALL['VERSION] as well.
$_INSTALL['VERSION'] = 1.02;
// This creates a main menu item in the database
$_INSTALL['MAIN_MENU_ITEM'] = array (
'title' => 'blog_simple_title',
'url' => '/blog_simple/index',
'module_name' => 'blog_simple',
'parent' => 0,
'weight' => 2,
);
// This sets the public clone URL
$_INSTALL['PUBLIC_CLONE_URL'] = "git://github.com/diversen/blog_simple.git";
$_INSTALL['PRIVATE_CLONE_URL'] = 'git@github.com:diversen/blog_simple.git';
Install Module
Now we have a module which we can install. To install a module which is already located in the module folder we issue the command:
./coscli.sh module --mod-in blog_simple
This will install the module. You can now add something to a controller file. Create hello.php in your blog_simple folder and add the first "Hello World" statement like in the following piece of code:
<?php
echo "hello world";
open a browser and visit:
http://yoursite/blog_simple/hello
and you should see the hello world statement!
Lets just try and uninstall again right away.
./coscli.sh module --mod-down blog_simple
If you now try and visit the module again, then you will get a 404 error. Module does not exists in web space anymore. Install the module again if you want to see how it develops along the way.
Module Menu
In the above the main menu item was installed (which is placed in database). You will notice that our menu is prefixed with a NT (needs translation). This is because we have not translated our menu item (will do that as a final thing) - if you don't need translation you can just echo statements without using the translation class.
The next menu structure belongs only to the blog_simple module which means that it will only be loaded when our module gets loaded. The module menu is also just a file. Open the file called blog_simple/menu.inc. And add the following PHP code to it:
<?php
/**
* This is where we define our menus.
*/
// First menu item is where we plan to list all entries.
// As you can see the module menu just specifies links
// to controller files. index refers to index.php in our
// module folder
$_MODULE_MENU[] = array(
'title' => lang::translate('blog_simple_menu_list'),
'url' => '/blog_simple/index',
);
// we read who is allowed to use admin interface
// which we get from an ini setting. We will see this ini
// file in the next section of the tutorial.
$blog_simple_allow = get_module_ini('blog_simple_allow');
// we add a menu entry for adding entries. Again it is just
// a link with URL and title, but notice that we set an auth
// element of the array in addition.
// This just means that it is only users logged in as admin
// users who will see this link. Anybody else does not need to
// see this link.
$_MODULE_MENU[] = array(
'title' => lang::translate('blog_simple_menu_add'),
'url' => '/blog_simple/add',
// note that we have set an auth element!
'auth' => $blog_simple_allow
);
When you reload our hello page, you will see that two menus entries are displayed. As you can see no translation exists, but both menu entries are links pointing to files specified in the menu file (index.php which exists and add.php which does not exists).
Adding ini settings
Before we go on and produce the module, we will add a couple of ini settings - these are good if you want to be able to edit some configuration from a central point - which the user can not affect: Open blog_simple.ini, and add the following lines of code:
blog_simple_per_page = 5
blog_simple_filters[] = markdownExt
blog_simple_abstract_length = 250
blog_simple_allow = admin
The first element is for paging. We want to make it possible to change how many items should be on a page. We also add some way of filtering the content displayed we add. We use the markdownExt filter which should be included in the default distribution.
We set a length of the abstract which will be displayed on the list of all entries. And we also add a setting for who can edit blog entries. Placing these settings in the ini file means that we easily can change these settings without touching the main code.
You should also add these exactly settings to blog_simple.ini-dist file, which will then be used as default settings if users decide to use the module - on install from a git repo the blog.ini-dist file will be copied to to blog.ini.
Dependencies
As you can see in the above ini settings we will be using the filter_markdownExt. If you don't have this module (it should be in the default osnet profile, but if you are using another profile you will need to install this filter.