module_development

Since Webber is built on Codeigniter this tutorial already assumes that you're familiar with it or with a similar PHP framework and with the MVC (model/view/controller) structure.

Webber also uses the HMVC modular extensions component so, if you're familiar with that one this tutorial should be very easy to follow.

To create a Webber module is quite simple. New modules should be created in a folder placed inside the folder 'various'. The folder of your new module should have the same name as your module.

Another thing that you must do before starting to code this new module is to create a new php file inside your newly created module folder and name it exactly as the folder/module name. Let's take an example. If I want to build a blog module, I will have to create a folder called 'blog' inside 'various/modules' and a php file 'blog.php' inside 'various/modules/blog'. Right now we're done with the structure and we can start coding on our new module.

For your new module to be recognized by webber you will have to place 4 PHP functions inside 'blog.php' (I added the 'blog_' prefix for this example. Each function must have the module name plus an underscore as a prefix):

• blog_activate ();
  • holds the code to be executed when activating the module (sql insert, roles and resources inserting, language inserting etc.)
  • must return 'TRUE' for the module to be activated. If your module requires additional informations from the user before being activated you can return a html form (or whatever content you wish), verify the post values, validate them and only when you're satisfied with the inputs you can return 'TRUE'.
• blog_deactivate ();
  • holds the code to be executed when deactivating the module (mysql cleaner, lang cleaner etc.)
  • must return 'TRUE' for the module to be deactivated. If your module requires additional informations from the user before being deactivated you can return a html form (or whatever content you wish), verify the post values, validate them and only when you're satisfied with the inputs you can return 'TRUE'.
• blog_description ();
  • returns the blog description (a simple return or echo is enough. the description will be visible in the 'Modules' administration area)
• blog_load ();
  • this function is executed at every request/page load when the module is active. It usually holds the menu object (inserts the menu items for the module. For a guide on injecting menu items please click here)

function blog_activate ()
{
	return TRUE;
}
 
function blog_deactivate ()
{
	return TRUE;
}
 
function blog_description ()
{
	return 'My blog description';
}
 
function blog_load ()
{
	//do something here at every request
}

At this point you have a basic module which does absolutely nothing but being visible. You can activate/deactivate it as it should be 100% functional.

New pages are added by creating new controllers. New controllers should be placed inside a folder named 'controllers' which resides in the module folder: 'various/blog/controllers'.

The url to your controller should be preceded by 2 uri segments: 'call/blog'. Supposing you're creating a new controller called 'posts' with a method/function called 'show_posts' your url will look like this: http://www.yourdomain.com/index.php/call/blogs/posts/show_posts

In Codeigniter, the controller extends a class 'Controller'. The controllers created inside a module will extend 'Module'. Here's a coding example for the controller mentioned above:

class Posts extends Module {
 
	function posts ()
	{
		parent::Module ();
	}
 
	function show_posts ()
	{
 
	}
 
}

The models, helpers and libraries are loaded normally using the '$this→load' syntax. No other modifications are done to the normal coding style of Codeigniter.

New models should be placed inside the folder 'models': 'various/blog/models'. New helpers should be placed inside the folder 'helpers': 'various/blog/helpers'. New libraries should be placed inside the folder 'libraries': 'various/blog/libraries'. New template files should be placed inside the folder 'templates': 'various/blog/templates'.

From your module, you can access and use all the helpers and libraries available in codeigniter and also Webber's properties.

We're done with building the module skeleton (pretty simple right?!) and I want to continue with a little example which actually builds a page and displays it using webber's templates. We will also create our own little template to display some html message. This is just to help you familiarized with the coding structure and the whole process of building a page inside your module.

We will continue the example above and create the function 'show_posts' inside the 'blog' controller. I want the function show posts to load an html table with all the blog posts available in my database.

class Posts extends Module {
 
	function posts ()
	{
		parent::Module ();
	}
 
	function show_posts ()
	{
		//load the blog model
		$this->load->model ( 'mblog' );
 
		//fetch the posts
		$query_posts = $this->db->query ( 'SELECT * FROM ' . DBPREFIX . 'blog_posts ORDER BY date_added DESC' );
 
		//assign the posts to an array in order to pass it in the template
		$data = array
		(
			'posts'	=> $query_posts->result ()
		);
 
		//prepare the content
		$content = load_module_template ( $data, ROOTPATH . '/various/blog/templates/posts.tpl' );
 
		//prepare the array to be sent to the main template
		$page = array
		(
			'content' => $content
		);
 
		//extend the $page array and asign the global variables based on this page (title, js, css etc.)
		$page = assign_global_variables ( $page, 'blog_posts' );
 
		//load the main template
		load_template ( $page, 'template' );
	}
 
}

In the first part of our 'show_posts' method we're performing a query to extract the posts from the database. Normally, you would create a function inside a model and use that one instead but, in order to keep the code as simple as possible, we're doing this with a simple query right inside our controller.

$query_posts = $this->db->query ( 'SELECT * FROM ' . DBPREFIX . 'blog_posts ORDER BY date_added DESC' );

Next, we assign the posts to a template which does nothing else but to load the posts table:

//assign the posts to an array in order to pass it in the template
		$data = array
		(
			'posts'	=> $query_posts->result ()
		);
 
		//prepare the content
		$content = load_module_template ( $data, ROOTPATH . '/various/blog/templates/posts.tpl' );

We should create a new file called 'posts.tpl' which is a smarty template file and place it inside 'various/blog/templates'. Here's how the template code might look like:

<ul>
	{foreach from=$posts item=post}
		<li>{$post->title}</li>
	{foreachelse}
		<li>No posts available</li>
	{/foreach}
</ul>

Just a simple foreach to loop through the posts and display them. Notice the function load_module_template that we use to load the template modules.

As you can see we're using templates to load every piece of html that builds the content of our pages. To simplify this even further I could assign the html to '$content' inside my controller and avoid loading 'posts.tpl' but it's important to get familiar with the template system that we're using.

Next, we're assigning the global variables for the newly created page.

$page = assign_global_variables ( $page, 'blog_posts' );

Global variables are little details to build the page based on conditions. For example, page titles are assigned by this function in order to keep them unique. Most of the global variables are assigned based on a unique identifier of the page, in our case 'blog_posts'.

The title of your page should have the key 'blog_posts'. If you add a new language string with this key, it will appear on your page's title.

Here's a list with the tags assigned to a page:

• page_title This one sets the title of the page '<title>{$page_title}</title>
• notifications Used to display various messages to the end user
• dashboard This is the yellow bar right under the menu. Not so very used right now but we have high plans for it :P
• styles This one holds the css styling (also loads a template file which knows what file to load where based on some conditions related to the page_title parameter)
• javascript Sames as above but for javascript
• footer Responsible for what is in the footer
• site_top_right_menu This is the top right menu of the application
• site_menu The main menu which also serves as a breadcrumb
• online_users Not used yet but you can imagine what it will do.
• slogan The site slogan, present if you wish to use it somewhere
• home This is the 'home' link, the first segment of the main menu

Many of them use functions so be prepared to go 2-3 levels deep inside the code.

That's more than it. Here's a list with some topics that might help you get started or customize the module even further:

• How to add my own css/javascript inside my module template
• How to add new items to the menu?

You can download a small blog module example from here: blog.zip (the code is very basic, uses no protection or validation at all, it barely functions).

We have also created a video presenting a tutorial with how to create the blog module from start to finish.