Develop new module - Part 2 - Create module

From TomatoCMS Documentation

Jump to: navigation, search

In this series of guides, I will show you how to create a simple module. Let's say that it's contact module. This module manages contacts in your address book.

Contents

Step 1: Create module folder

Create contact folder inside app/modules folder. 

TomatoCMS_Root_Folder
|__app
    |__modules
        |__contact

Step 2: Add module information

As I said in previous guide, each module has XML file which introduces module information. In our module directory:

  • Create config folder
  • Create about.xml located in config folder 
TomatoCMS_Root_Folder
|___app
    |___modules
        |___contact
	    |___config
		|___about.xml

Put following content to this file: 

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE module SYSTEM "http://schemas.tomatocms.com/dtd/module_about.dtd">
<module>
    <name>contact</name>
    <description langKey="about_contact_description"><![CDATA[Manage contacts]]></description>
    <author>TomatoCMS Core Team</author>
    <email>core@tomatocms.com</email>
    <version>2.0.4</version>
    <license>free</license>
</module>

This XML file follows schema provided by http://schemas.tomatocms.com/dtd/module_about.dtd, therefore it doesn't need to remember the tag keyword if you edit it in IDE that supports DTD format. This file consists of some basic information as:

  • name: Name of module.
  • description: Description of module.
  • author: Author of module
  • email: Author email
  • version: Module version
  • license: Module license

Add database queries

This file also defines SQL queries for your module. For simply illustration, I assume that our contact module has only one database table named contact which can be created by following query: 

CREATE TABLE `t_contact` (
  `contact_id` int(10) UNSIGNED NOT NULL AUTO_INCREMENT,
  `first_name` varchar(50) NOT NULL,
  `last_name` varchar(50) NOT NULL,
  `address` varchar(200) DEFAULT NULL,
  `email` varchar(50) NOT NULL,
  PRIMARY KEY  (`contact_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

Let's add SQL queries including database creation queries, data initializing queries, etc to our about.xml file: 

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE module SYSTEM "http://schemas.tomatocms.com/dtd/module_about.dtd">
<module>
...
    <install>
        <db adapter="mysql|pdo_mysql">
	    <query><![CDATA[DROP TABLE IF EXISTS `###contact`]]></query>
            <query><![CDATA[CREATE TABLE `###contact` (
                   `contact_id` int(10) unsigned NOT NULL auto_increment,
                   `first_name` varchar(50) NOT NULL,
                   `last_name` varchar(50) NOT NULL,
                   `address` varchar(200) default NULL,
                   `email` varchar(50) NOT NULL,
                   PRIMARY KEY  (`contact_id`)
                   ) ENGINE=InnoDB DEFAULT CHARSET=utf8;]]>
            </query>
	</db>
	<db adapter="pgsql">
	    <query><![CDATA[DROP TABLE IF EXISTS `###contact`]]></query>
            <query><![CDATA[CREATE TABLE `###contact` (
                   `contact_id` int(10) unsigned NOT NULL auto_increment,
                   `first_name` varchar(50) NOT NULL,
                   `last_name` varchar(50) NOT NULL,
                   `address` varchar(200) default NULL,
                   `email` varchar(50) NOT NULL,
                   PRIMARY KEY  (`contact_id`)
                   ) ENGINE=InnoDB DEFAULT CHARSET=utf8;]]>
            </query>
	</db>
	<db adapter="sqlsrv">
	    <query><![CDATA[DROP TABLE IF EXISTS `###contact`]]></query>
            <query><![CDATA[CREATE TABLE `###contact` (
                   `contact_id` int(10) unsigned NOT NULL auto_increment,
                   `first_name` varchar(50) NOT NULL,
                   `last_name` varchar(50) NOT NULL,
                   `address` varchar(200) default NULL,
                   `email` varchar(50) NOT NULL,
                   PRIMARY KEY  (`contact_id`)
                   ) ENGINE=InnoDB DEFAULT CHARSET=utf8;]]>
            </query>	
	</db>
    </install>
 
    <uninstall>
       <db adapter="mysql|pdo_mysql">
          <query><![CDATA[DROP TABLE IF EXISTS `###contact`]]></query>
       </db>
       <db adapter="pgsql">
          <query><![CDATA[DROP TABLE IF EXISTS `###contact`]]></query>
       </db>
       <db adapter="sqlsrv">
          <query><![CDATA[DROP TABLE IF EXISTS `###contact`]]></query>
       </db>
    </uninstall>  
</module>

All queries in install (uninstall) tag will be executed when you install (uninstall) modules Also, in the SQL queries, you can use ### character which will be replaced with your database prefix (in this case, the database prefix is t_).

Step 3: Install module

Now, go to Extend > Module menu in back-end. Here you can see list of all available modules in our system.

File: Addmodule_display_at_manage_module_section.png

You can click Install to install module and vice versa, you can click Uninstall to uninstall a module. As I said in step 2, after clicking Install (or Uninstall), all SQL queries defined in install (uninstall) tag from about.xml file also were already executed.

IMPORTANT NOTE: If you click Uninstall, all data belonging to the module will be removed. Don't forget to backup your data before uninstalling module.

Step 4: Show module at dashboard

Now we can see module at administrator dashboard:

File:Addmodule_first_show_module_at_dashboard.png

The question is how to add additional module actions to this module section.

Assume that we need to show two basic actions for this module.

  • The first one lists all contacts which can be accessed via URI /admin/contact/list/
  • The second one allows user to create new contact which can be accessed via URI /admin/contact/add/

The answer is you just need to update about.xml as following: 

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE module SYSTEM "http://schemas.tomatocms.com/dtd/module_about.dtd">
<module>
    ...
    <admin>
        <task link="/admin/contact/list/" langKey="dashboard_list_contacts" />
	<task link="/admin/contact/add/" langKey="dashboard_add_contact" />
    </admin>
</module>

admin tag can contain one or many tasks, each task defines link in back-end via link property. The langKey property is the language key from module language file. Its value will be used as label of link.

Create language file

Assume that our website are using the default English package.

  • Create languages directory
  • Create lang.en_US.ini file 
TomatoCMS_Root_Folder
|___app
    |___modules
	|___contact
	    |___languages
		|___lang.en_US.ini

Next, defines the value for above key:

// app/modules/contact/languages/lang.en_US.ini 

[about]
dashboard_list_contacts = "List contacts"
dashboard_add_contact = "Add new contact"

Refresh our dashboard and you will see the links to module actions as we expected:

File:Addmodule_show_contact_section_link.png

Retrieved from "http://docs.tomatocms.com/index.php/Develop_new_module_-_Part_2_-_Create_module"
Personal tools