Creating a module

PyroCMS is built to be modular, so creating modules is a pretty simple process. There are two kinds of modules: "core" and "third_party". A core module is something the system can't function without, or is considered pretty important. A third-party module is something that is optional that can be deleted or added with no effect to the site. Any module you create should ideally go into third_party/modules/.

Each module can contain the following directories: config, controllers, helpers, libraries, models, views, js, css, img. If a module will have a frontend (something that displays to the user) then it should contain at least one controller, and that controller should be the same name as the module.

E.g: third_party/modules/news/controllers/news.php

The rest of it is pretty much normal CodeIgniter development except for a few things.

details.xml

Each module contains a details.xml file which contains its name, description, version, wether they are available to the backend and/or frontend, etc.  This file is only used when installing and uninstalling the module.  On install the file is parsed and imported into the database.

Here is the basic structure for the details.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<module version="0.8-beta" slug="forums">
    <name>
        <en>Forums</en>
    </name>
    <description>
        <en>Forums for your site</en>
    </description>
    <skip_xss>1</skip_xss>
    <is_frontend>1</is_frontend>
    <is_backend>1</is_backend>
    <is_backend_menu>0</is_backend_menu>
    <controllers>
        <controller name="admin">
            <method>index</method>
        </controller>
    </controllers>
 
 <install>
  <![CDATA[
  DROP TABLE IF EXISTS `forum_categories`;

  -- command split --

  CREATE TABLE `forum_categories` (
    `id` int(11) NOT NULL AUTO_INCREMENT,
    `title` varchar(100) NOT NULL DEFAULT '',
    `permission` mediumint(2) NOT NULL DEFAULT '0',
    PRIMARY KEY (`id`)
  ) ENGINE=MyISAM DEFAULT CHARSET=utf8 COMMENT='Splits forums into categories';

  -- command split --

  DROP TABLE IF EXISTS `forum_posts`;

  -- command split --

  CREATE TABLE `forum_posts` (
    `id` int(11) NOT NULL AUTO_INCREMENT,
    `forum_id` int(11) NOT NULL DEFAULT '0',
    `author_id` int(11) NOT NULL DEFAULT '0',
    `parent_id` int(11) NOT NULL DEFAULT '0',
    `title` varchar(100) NOT NULL DEFAULT '',
    `content` text NOT NULL,
    `type` tinyint(1) NOT NULL DEFAULT '0',
    `is_locked` tinyint(1) NOT NULL DEFAULT '0',
    `is_hidden` tinyint(1) NOT NULL DEFAULT '0',
    `created_on` int(11) NOT NULL DEFAULT '0',
    `updated_on` int(11) NOT NULL DEFAULT '0',
    `view_count` int(11) NOT NULL DEFAULT '0',
    `sticky` tinyint(1) NOT NULL,
    PRIMARY KEY (`id`)
  ) ENGINE=MyISAM  DEFAULT CHARSET=utf8;

  -- command split --

  DROP TABLE IF EXISTS `forum_subscriptions`;

  -- command split --

  CREATE TABLE `forum_subscriptions` (
    `id` int(11) NOT NULL AUTO_INCREMENT,
    `topic_id` int(11) NOT NULL DEFAULT '0',
    `user_id` int(11) NOT NULL DEFAULT '0',
    PRIMARY KEY (`id`)
  ) ENGINE=MyISAM DEFAULT CHARSET=utf8;

  -- command split --

  DROP TABLE IF EXISTS `forums`;

  -- command split --

  CREATE TABLE `forums` (
    `id` int(11) NOT NULL AUTO_INCREMENT,
    `title` varchar(100) NOT NULL DEFAULT '',
    `description` varchar(255) NOT NULL DEFAULT '',
    `category_id` int(11) NOT NULL DEFAULT '0',
    `permission` int(2) NOT NULL DEFAULT '0',
    PRIMARY KEY (`id`)
  ) ENGINE=MyISAM AUTO_INCREMENT=2 DEFAULT CHARSET=utf8 COMMENT='Forums are the containers for threads and topics.';
  ]]>
 </install>

 <uninstall>
  <![CDATA[
  DROP TABLE IF EXISTS `forum_categories`;

  -- command split --

  DROP TABLE IF EXISTS `forum_posts`;

  -- command split --

  DROP TABLE IF EXISTS `forum_subscriptions`;

  -- command split --

  DROP TABLE IF EXISTS `forums`;
  ]]>
 </uninstall>

</module>

You can see that it contains SQL that is ran on Install and Uninstall of the module.  This SQL MUST be CDATA and commands MUST be split by "-- command split --" (as seen above).

Public Controllers

In normal CodeIgniter there is only one controller class. In PyroCMS there are four. Controller, MY_Controller, Admin_Controller and Public_Controller. To use one of these you can extend them like so:

<?php

class Modulename extends Public_Controller {

    function __construct() {
        parent::Public_Controller();
    }

    function index()
    {
        $this->data->some_var = "Hello World!";
        $this->template->build('view_name', $this->data);
    }
 
}


This page will be available to anyone wether logged in or not and will use the frontend design. That means it will use the current active theme and show any login data and navigation, etc and can be viewed via "http://example.com/modulename".

Admin Controllers

Admin controllers have a few different properties to them. It will automatically check that a user has permission to be there, and redirect them to a login page if not. This means they either need to have a user role of "admin" or be allowed specific permissions on the controller or module.

application/modules/modulename/controllers/admin.php

<?php

class Admin extends Admin_Controller {

    function __construct() {
        parent::Admin_Controller();
    }

    function index()
    {
        $this->data->some_var = "Hello Admin!";
        $this->template->build('admin/view_name', $this->data);
    }
 
}


This page can be accessed via "http://example.com/admin/modulename".

Clearing the cache

When you put together your module structure and made your details.xml file, you might notice there is still no sign of your module in the admin panel. The navigation is cached to save CPU cycles as parsing 10+ XML files on each page load is silly. To get your backend module to appear (if you have told it to do so with is_backend_menu in details.xml) you need to clear the application/cache/modules_m/ cache folder like so:

sudo rm -rf application/cache/modules_m

Now your module should appear and you can start developing your module using normal CodeIgniter methods, your own libraries and those included with PyroCMS.

Installing the Module

The module can be installed in 2 different ways.

First Method

1. Copy the module into the third_party/modules folder.
2. Log into the admin and click on "Modules".  Doing this will re-scan the modules directory, find your module and install it automatically (running your install SQL if it exists).
3. That's it!

Second Method (for distribution)

This method is very useful for distributing your module as a downloadable package.

1. Zip up your module directory.
2. Go into the admin and click on "Modules".
3. Click on "Upload"
4. Select your module zip file.
5. Click Upload.  It will upload the zip file, unzip it to the third_part/modules directory and run the install SQL if it exists.
6. Thats It!

Uninstalling the Module

To uninstall simply go into the admin, click on "Modules" then click "Uninstall" next to the module you wil to uninstall.  This wil run any uninstall SQL that exists in details.xml file for that module.

Disabling the Module

To disable simply go into the admin, click on "Modules" then click "Disable" next to the module you want to disable.  This will disable both on the front end (it will 404 when you try to visit it) and in the admin.