Starting a Component

Labels: Files and Folders

The beginnings of wisdom in Joomla Component development is the understanding of the Model-View-Controller paradigm. In the Joomla context, the Controller executes tasks. The Model is responsible for getting and setting data. The View is responsible for displaying output. We also have one final layer and that is the Layout, which is the actual HTML that is output to the browser.

File Structure

Most components follow a very formal file structure:

/components
  /com_notes
    /controllers
    /help
    /install
    /media
    /models
    /tables
    /views
    controller.php
    notes.php

The /controllers/ folder holds additional controller files related to specific tasks (such as saving an item, checking in, checking out, deleting, etc).

The /help/ folder can hold any HTML help files that might be useful to the user of the component.

The /install/ folder will hold the files used to install the extension (database schema and any PHP files run at install or uninstall time). In a later chapter we will show you how to create a single install package that allows you to install your component with all its supporting modules and plugins.

The /media/ folder holds any supporting images, CSS stylesheets or Javascript files that might be required by the component.

The /models/ folder holds the model classes or other files related to the data is of interest to the component.

The /tables/ folder holds the table classes for any database tables used by the component. Note that the tables only need to be defined once in either the site or administrator component.

The /views/ folder holds all the views that will display information to the user or visitor.

The controller.php file is the master controller for the component, usually having the main display method supporting all the views.

The notes.php file is basically a dispatcher file that creates the controller and executes the task in the request. This is the file that Joomla looks for and includes to actually run the component.

The initial folder and file creation can be semi-automated. Using an administrator component as an example, the following commands could be issued:

cd administrator/components
mkdir com_notes
cd com_notes
mkdir -p controllers help/en-GB media/css media/images media/js models tables views
echo "<html><body></body></html>" > index.html
touch controller.php
touch notes.php

As a matter of habit, whenever you create a new folder you should create an index.html file to prevent visitors snooping around your web site folders.

Component Preparation

The Database Schema

Most components will be concerned about storing some sort of custom data, whether that be for a forum post, personal notes, products for sale, and so on. It’s worth spending a little bit of time planning out the database schema for the component on paper or using graphical design aids (such as Visual Paradigm). In this example our brief is to create a manager for simple notes. We will be starting with one table to store the notes. The SQL for the table looks like this:

CREATE TABLE `jos_notes` (
  `note_id` int(11) NOT NULL auto_increment,
  `category_id` int(11) NOT NULL default '0' COMMENT 'Foreign key to #__categories.id',
  `title` varchar(255) NOT NULL,
  `alias` varchar(255) NOT NULL,
  `body` mediumtext NOT NULL,
  `privacy` int(1) NOT NULL default '0' COMMENT '0 = none, 1 = private',
  `published` int(1) NOT NULL default '0' COMMENT 'Core field',
  `ordering` int(11) NOT NULL default '0' COMMENT 'Core field',
  `access` int(11) NOT NULL default '0' COMMENT 'Core field',
  `params` mediumtext NOT NULL,
  `sort_date` datetime NOT NULL,
  `checked_out` int(11) NOT NULL COMMENT 'Core field',
  `checked_out_time` datetime NOT NULL COMMENT 'Core field',
  `created_user_id` int(11) NOT NULL,
  `created_date` datetime NOT NULL,
  `modified_user_id` int(11) NOT NULL,
  `modified_date` datetime NOT NULL,
  PRIMARY KEY  (`note_id`),
  KEY `idx_alias` (`alias`),
  KEY `idx_published_access` (`published`,`access`),
  KEY `idx_created_date` (`created_date`),
  KEY `idx_modified_date` (`modified_date`),
  KEY `idx_sort_date_published` (`sort_date`,`published`)
) ENGINE=MyISAM DEFAULT CHARSET=utf8;

Let’s look at the fields in detail:

note_id - This is the primary key of the table which also serves as the unique “id” for the note.
category_id - This a foreign key to the jos_categories table. The notes need to support categories so we will keep a record of the id of the category in this table. We use an integer field for efficient indexing.
title - This is just a text field to hold the title.
alias - This is a URL-safe version of the title to be used in SEF URL’s when required.
body - This is the body text of the note.
privacy - This is a switch that will allow others to see my notes, or allow me to keep them private.
published - This is a standard Joomla field to indicate the published state (where -2 means the row is in the trash).
ordering - This is a standard Joomla field to support ordering of the notes.
access - This is a standard Joomla field to support access control.
params - This is a standard Joomla field to support custom parameters and options.
sort_date - This is a field that allows you to set the date to sort by (as opposed to relying on the created or modified dates).
checked_out - This is a standard Joomla field that indicates whether the row is checked out (it maps to the jos_users table id field).
checked_out_date - This is the datetime when the row was checked out by another user.
created_user_id - This is the user id for the user that created the note.
created_date - This is the date that the note was created.
modified_user_id - This is the user id for the user that last modified the note.
modified_date - This is the date that the note was last modified.

The fields marked in bold have special significance when using other classes in the Joomla Framework (such as JTable).

In addition to the fields, we also specify a number of indexes:

idx_alias - This is an index on the alias column to allow for efficient lookups in SEF URL’s
idx_published_access - This is an index on the published and access fields
idx_created_date
idx_modified_date
idx_sort_date_published

Adding the Component Details to the Administrator Menu

Before we start into the details of component design, it’s worth mentioning how to set them up for testing. Most components will allow you to access them via the URL:

/site/index.php?option=com_notes

This is satisfactory for initial testing but in order to save component configuration, or add the component to menus you will need to add a row to the jos_components table, like this:

INSERT INTO jos_components SET
name = ‘Notes Manager’,
link = ‘option=com_notes’, -- // Only use if a frontend component is also provided
admin_menu_link = ‘option=com_notes’,
admin_menu_alt = ‘Notes Manager’,
option = ‘com_notes’,
is_core = 0,
enabled = 1;

Run this SQL in your management MySQL utility (browser based phpMyAdmin or a desktop utility like MySQL Query Browser). Refreshing the backend will now reveal the new component in the Components menu.

We will look at more advanced, automated ways of manually installing an extension in another chapter.

File Structure

Component Preparation

The Database Schema

Adding the Component Details to the Administrator Menu

Ready for More?