DS is the directory separator of your system: either '/' or '\'. This is automatically set by the framework so the developer doesn't have to worry about developing different versions for different server OSs. The 'DS' constant should always be used when referring to files on the local server.

DS is the directory separator of your system: either '/' or '\'. This is automatically set by the framework so the developer doesn't have to worry about developing different versions for different server OSs. The 'DS' constant should always be used when referring to files on the local server.

−

After loading the base controller, we check if a specific controller is needed. In this component, the base controller is the only controller, but we will leave this here for future use.

+

After loading the base controller, we check if a specific controller is needed. In this component, the base controller is the only controller, but we will leave this conditional check "in place" for future use.

JRequest:getVar() finds a variable in the URL or the POST data. So if our URL is index.php?option=com_hello&controller=controller_name, then we can retrieve our controller name in our component using: echo JRequest::getVar('controller');

JRequest:getVar() finds a variable in the URL or the POST data. So if our URL is index.php?option=com_hello&controller=controller_name, then we can retrieve our controller name in our component using: echo JRequest::getVar('controller');

Revision as of 04:02, 15 December 2009

This Namespace has been archived - Please Do Not Edit or Create Pages in this namespace. Pages contain information for a Joomla! version which is no longer supported. It exists only as a historical reference, will not be improved and its content may be incomplete.

Introduction

A software framework is the base of an application that can be used by a developer. The framework in Joomla! 1.5 unleashes a great deal of power for them. The Joomla! code has been completely overhauled and cleaned up. This tutorial will guide you through the process of developing a component using the framework.

The scope of this project will be to develop a simple Hello World! component. In future tutorials, this simple framework will be built upon to show the full power and versatility of the MVC design pattern in Joomla!

Requirements

You need Joomla! 1.5 or greater for this tutorial.

Introduction to Model-View-Controller

While the idea behind a component may seem extremely simple, code can quickly become very complex as additional features are added or the interface is customized.

Model-View-Controller (herein referred to as MVC) is a software design pattern that can be used to organize code in such a way that the business logic and data presentation are separate. The premise behind this approach is that if the business logic is grouped into one section, then the interface and user interaction that surrounds the data can be revised and customized without having to reprogram the business logic. MVC was originally developed to map the traditional input, processing, output roles into a logical GUI architecture.

These three main roles are the basis for the Joomla MVC. They are described here in brief, but for a more thorough explanation, please refer to the links provided at the end of this tutorial.

Model

The model is the part of the component that encapsulates the application's data. It will often provide routines to manage and manipulate this data in a meaningful way in addition to routines that retrieve the data from the model. In our case, the model will contain methods to add, remove and update information about the greetings in the database. It will also contain methods to retrieve the list of greetings from the database. In general, the underlying data access technique should be encapsulated in the model. In this way, if an application is to be moved from a system that utilizes a flat file to store its information to a system that uses a database, the model is the only element that needs to be changed, not the view or the controller.

View

The view is the part of the component that is used to render the data from the model in a manner that is suitable for interaction. For a web-based application, the view would generally be an HTML page that is returned to the data. The view pulls data from the model (which is passed to it from the controller) and feeds the data into a template which is populated and presented to the user. The view does not cause the data to be modified in any way, it only displays data retrieved from the model.

Controller

The controller is responsible for responding to user actions. In the case of a web application, a user action is (generally) a page request. The controller will determine what request is being made by the user and respond appropriately by triggering the model to manipulate the data appropriately and passing the model into the view. The controller does not display the data in the model, it only triggers methods in the model which modify the data, and then pass the model into the view which displays the data.

MVC connection

The simplified picture on the right depicts the basic components being used within Joomla. Besides the Model, the View and the Controller, an Entry Point has been added that is depicted as a small circle. Attached to the viewer (view) a Template has been added. With these five components you should be able to understand this tutorial about making a basic Joomla! MVC component.

Part 1 of the tutorial only focuses on the Controller and the View (with the use of the Template); these are marked with the blue colour in the picture. Part 2 adds and Part 3 extends the model functionality for the data manipulation abstraction; marked with the green colour in the picture.

Keep in mind that this simplified picture only applies for the site section (i.e the front-end). An identical picture is applicable for the admin section (i.e. the back-end). The administrative section is taken care of in Parts 4 through 6 of this component development tutorial. Both the site and the admin section are maintained and configured in an XML based installation file (typically termed a manifest file).

Joomla! MVC Implementation

In Joomla!, the MVC pattern is implemented using three classes: JModel, JView and JController. For more detailed information about these classes, please refer to the API reference documentation (WIP).

For learning purposes and debugging, adding a run-time debugger to your Joomla! site might be a good extension especially during development of your (tutorial) component. A good example is the community project J!Dump that has the advantage of being a pop-up which leaves the view output unchanged. The J!Dump system allows you to view not only your development properties but also the methods.

Creating a Component

For our basic component, we only require five files:

site/hello.php - this is the entry point to our component

site/controller.php - this file contains our base controller

site/views/hello/view.html.php - this file retrieves the necessary data and pushes it into the template

site/views/hello/tmpl/default.php - this is the template for our output

hello.xml - this is an XML (manifest) file that tells Joomla! how to install our component.

Remember that the filename for the entry point must have the same name of the component. For example, if you call your component "Very Intricate Name Component", at install time (see below in the hello.xml section) Joomla! will create the folder com_veryintricatenamecomponent and the entry point php file must be named veryintricatenamecomponent.php otherwise it will not work. Be aware that use of some special characters, notibly the underscore '_', may have special meaning in Joomla and should be avoided in component names or files.

The site directory here is for the parts of the component which are installed in the front end site.

Creating the Entry Point

Joomla! is always accessed through a single point of entry: index.php for the Site Application or administrator/index.php for the Administrator Application. The application will then load the required component, based on the value of 'option' in the URL or in the POST data. For our component, the URL would be:

index.php?option=com_hello&view=hello

This will load our main file, which can be seen as the single point of entry for our component: components/com_hello/hello.php.

JPATH_COMPONENT is the absolute path to the current component, in our case components/com_hello. If you specifically need either the Site component or the Administrator component, you can use JPATH_COMPONENT_SITE or JPATH_COMPONENT_ADMINISTRATOR.

DS is the directory separator of your system: either '/' or '\'. This is automatically set by the framework so the developer doesn't have to worry about developing different versions for different server OSs. The 'DS' constant should always be used when referring to files on the local server.

After loading the base controller, we check if a specific controller is needed. In this component, the base controller is the only controller, but we will leave this conditional check "in place" for future use.

JRequest:getVar() finds a variable in the URL or the POST data. So if our URL is index.php?option=com_hello&controller=controller_name, then we can retrieve our controller name in our component using: echo JRequest::getVar('controller');

Now we have our base controller 'HelloController' in com_hello/controller.php, and, if needed, additional controllers like 'HelloControllerController1' in com_hello/controllers/controller1.php. Using this standard naming scheme will make things easy later on: '{Componentname}{Controller}{Controllername}'

After the controller is created, we instruct the controller to execute the task, as defined in the URL: index.php?option=com_hello&task=sometask. If no task is set, the default task 'display' will be assumed. When display is used, the 'view' variable will decide what will be displayed. Other common tasks are save, edit, new...

The controller might decide to redirect the page, usually after a task like 'save' has been completed. This last statement takes care of the actual redirection.

The main entry point (hello.php) essentially passes control to the controller, which handles performing the task that was specified in the request.

Note that we don't use a closing php tag in this file: ?>. The reason for this is that we will not have any unwanted whitespace in the output code. This is default practice since Joomla! 1.5, and will be used for all php-only files.

Creating the Controller

Our component only has one task - greet the world. Therefore, the controller will be very simple. No data manipulation is required. All that needs to be done is the appropriate view loaded. We will have only one method in our controller: display(). Most of the required functionality is built into the JController class, so all that we need to do is invoke the JController::display() method.

The JController constructor will always register a display() task and unless otherwise specified (using the registerDefaultTask() method), it will set it as the default task.

This barebones display() method isn't really even necessary since all it does is invoke the parent constructor. However, it is a good visual clue to indicate what is happening in the controller.

The JController::display() method will determine the name of the view and layout from the request and load that view and set the layout. When you create a menu item for your component, the menu manager will allow the administrator to select the view that they would like the menu link to display and to specify the layout. A view usually refers to a view of a certain set of data (i.e. a list of cars, a list of events, a single car, a single event). A layout is a way that that view is organized.

In our component, we will have a single view called hello, and a single layout (default).

Creating the View

The task of the view is very simple: It retrieves the data to be displayed and pushes it into the template. Data is pushed into the template using the JView::assignRef method.

Creating the Template

Joomla! templates/layouts are regular PHP files that are used to layout the data from the view in a particular manner. The variables assigned by the JView::assignRef method can be accessed from the template using $this->{propertyname} (see the template code below for an example).

Our template is very simple: we only want to display the greeting that was passed in from the view - this file is site/views/hello/tmpl/default.php:

Wrapping It All Up - Creating the hello.xml File

It is possible to install a component manually by copying the files using an FTP client and modifying the database tables. It is more efficient to create a package file that will allow the Joomla! Installer to do this for you. This package file contains a variety of information:

optionally, an SQL file which contains database queries that should be executed upon install/uninstall

The format of the XML file at hello.xml is as follows:

<?xmlversion="1.0"encoding="utf-8"?><installtype="component"version="1.5.0"><name>Hello</name><!-- The following elements are optional and free of formatting constraints --><creationDate>2007-02-22</creationDate><author>John Doe</author><authorEmail>john.doe@example.org</authorEmail><authorUrl>http://www.example.org</authorUrl><copyright>Copyright Info</copyright><license>License Info</license><!-- The version string is recorded in the components table --><version>1.01</version><!-- The description is optional and defaults to the name --><description>Description of the component ...</description><!-- Site Main File Copy Section --><!-- Note the folder attribute: This attribute describes the folder to copy FROM in the package to install therefore files copied in this section are copied from /site/ in the package --><filesfolder="site"><filename>controller.php</filename><filename>hello.php</filename><filename>index.html</filename><filename>views/index.html</filename><filename>views/hello/index.html</filename><filename>views/hello/view.html.php</filename><filename>views/hello/tmpl/default.php</filename><filename>views/hello/tmpl/index.html</filename></files><administration><!-- Administration Menu Section --><menu>Hello World!</menu><!-- Administration Main File Copy Section --><filesfolder="admin"><filename>hello.php</filename><filename>index.html</filename></files></administration></install>

If you look closely you will notice that there are some files that will be copied that we have not discussed. These are the index.html files. An index.html file is placed in each directory to prevent prying users from getting a directory listing. If there is no index.html file, some web servers will list the directory contents. This is often undesirable. These files have the simple line:

<html><body bgcolor="#FFFFFF"></body></html>

It will simply display a blank page.

The other file is the hello.php file in the admin section. This is the entry point for the admin section of our component. Since we don't have an admin section of our component, it will have the same content as the index.html files at this point in time.