Absolute Basics of How a Component Functions

From Joomla! Documentation

Revision as of 21:25, 29 May 2014 by Danielt686 (Talk | contribs)

This Article Needs Your Help

This article is tagged because it NEEDS REVIEW. You can help the Joomla! Documentation Wiki by contributing to it.
More pages that need help similar to this one are here. NOTE-If you feel the need is satistified, please remove this notice.

This document describes the absolute basics of how a component functions in the most basic ways. It is written for beginner developers to read to help them understand how a basic Joomla! component works.

Entering the Platform

You enter the Joomla! Platform by making calls to index.php. Joomla! is designed mainly to deliver the results of component files. When you call a page link, like index.php?option=com_<name>, the Joomla! Platform tries to find and load the file components/com_<name>/<name>.php from whichever folder you have installed Joomla! into. So, if your component is 'com_read' you should have a 'com_read' folder and a file named 'read.php' inside of it. I will call this file the 'base file'. It is in this file that you make the decision whether to use an old flat model (returning the HTML code for the requested page) or to use a Model-View-Controller (MVC) pattern.

This MVC model, walks over two legs: a file and a class. The Joomla! Platform will usually look for a given file and, if found, tries to register a specific class within this file. If either one is missing the call will fail.

Your controller.php File

You start all the fireworks by including a reference to a controller file in your base file. The controller file can be named anything you want, but by convention it is called 'controller.php'. In your base file (<name>.php), the following code is typical:

require_once(JPATH_COMPONENT . '/controller.php');

Your controller.php file can be created anywhere you want because you are referencing it by path. If you have written the code exactly as shown above, it should be created in the same location where your base file is located because JPATH_COMPONENT holds the path where the executing component base file is.

So create controller.php and make a reference to the controller library inside by importing it with:


Now that you have controller.php included and the base JControllerLegacy class imported, you have to define a class that extends the JControllerLegacy base class. This is the class leg mentioned earlier. It is here where your action will happen. You can name this class as you like but, by convention, it is named after your component so you write:

class <Name>Controller extends JControllerLegacy

In this stage you have your first two files, the base file and the controller file. The base file loads the controller and the controller defines a class. So far so good and easy. The next step is to create an object of this class and to put it to work. So add the following lines to your base file:

// Get an instance of the controller prefixed by <name>
$controller = JControllerLegacy::getInstance('<Name>');
// Perform the Request task
// Redirect if set by the controller

From this point on things start happening by themselves. Up to now you were able to name files/classes (except for the base one) and store them where you want because you were including the files by path/name and calling your classes by name within your code. (Well, only one file and only one class actually, but you could do it!) From now on the Joomla! Platform will begin loading your files and calling your classes automatically, so you must be careful where you put your files, what you name them, and what classes you define. A single letter mismatch will make Joomla! fail.

Getting the Data

Where does the Joomla! Platform get the data to play? Well, the answer is easy: from the request, be it a GET request or a POST request. But you have NOT written anything else in the request except option=com_<name>. Where does the 'task' in the execute call come from? Do you really have a meaningful 'task' variable?

Yes, and therein lies a 'problem': Whether you pass a request or not, Joomla! will use its defaults to complete a request, making some errors difficult to spot.

The controller->execute() call will make the Joomla! Platform try to do a request that, in this case, will be the default task 'display', because you have not specified otherwise.

class <Name>Controller extends JControllerLegacy
  function display()
    echo 'displaying';

If your request contained a 'task=jump' parameter the controller would have tried to call a method (function) named 'jump' in your controller class:

class <Name>Controller extends JControllerLegacy
  function jump()
    echo 'jumping';

The View

Up to now you have delved into the controller part of the model. This is a new point of decision. You can stop here or go a step further and enter the view part.

The different tasks given to the controller are methods in the controller.php file. All the needed variables are available from the Platform, so you will be able to retrieve them easily.

There is nothing that forces you to use the 'task' variable to drive the call because you can pass the value of any variable as the parameter to the execute method call. But in order to stick to the non-written rules, 'task' is usually used and as it is treated specially by the system, it is a good idea to stick with it.

To trigger the views, you have to call the __construct() method of JControllerLegacy. Do this by inserting, in your method, a call to parent::__construct() as in the last line. At a minimum, your controller file should contain the following:

class <name>Controller extends JControllerLegacy

What's a view? A view is a subset of data. It's the same concept as views in SQL parlance. You deliver different parts of your data with different views. So you could have a detailed data view and a resumed data view, the later presenting a subset of the whole data presented in the former.

As you can have multiple views, Joomla! uses the 'views' folder in your component's base directory to keep things tidy. This folder is only a placeholder for your views. This means that you need to create a views folder with a hierarchy that looks like this:

<name> base folder
  'views' folder
     view1 folder
     view2 folder

Inside the views folder, other folders hold the files that build each view. The Joomla! Platform includes a file named view.html.php that should exist in your view folder. A bit messy, I know, so I'll try to explain.

When you built your request, you included a variable named 'view' that tells the MVC model what view you want. Or, if you did not include it, you need to include it now because there is no such a thing as a default view. So your URL is something like:<name>&view=<myview>[&task=<mytask>]

The task part may or may not exist. Remember that if you omit it, you are defaulting to task=display. With this URL Joomla! is importing a file located at <site root dir>/components/<name>/views/<myview>/view.html.php. If this file or the path does not exist, Joomla! will fail. By simply swapping the value of the view, you deliver different views of your data.

Every request for a view requires that you also specify the format in which you are serving the view. There exist several well known formats such as html (the default one if none is specified), rss, etc. or you can use your own. If no format is specified in the request with the 'format=<myformat>' parameter a default value of 'html' is used.

The 'html' format makes the Joomla! Platform wrap the response in whatever template your site is using so that you get a fully built HTML page. This way, with very little effort from you, you get back your page fully loaded with modules or whatever you had configured.

The specific format you are using needs to be included in the middle part of the name of the file in your view folder (The file we talked about a few lines before 'view.html.php'). If you use a different format like 'rss' your file should be named after it like view.rss.php. Get it?

As mentioned before, you can have formats other than html and Joomla! will not wrap the template on them. You could have a 'pdf' format to deliver your data in pdf format or even an 'ajax' format to deliver ajax responses to the front-end easily. Just construct your URL like<name>&view=<myview>&format=ajax

to make the Joomla! Platform look for and load the file view.ajax.php located at <site root dir>/components/<name>/views/<myview>/ from which you can echo anything you want. It's that easy.

Anyway, to achieve your goal, you will need some code inside the view.<format>.php file. You have the view file, now you need the view class. You have to extend the JView class with your own class following the strict rules mentioned before. In this case, your class name must be built by concatenating the component name, the word 'View', and the view name. So your class name will be a capitalized <name>View<myview>. If your component is named 'travels' and your view is named 'detail' (URL ...?option=com_travels&view=detail) your view class must be:

class TravelsViewDetail extends JViewLegacy
  function display($tpl=null)
    echo 'blah, blah';

Within this class, you only have to feed the data you want to display for your component under this specific case. You can do this directly by delivering the HTML code directly, or through calls to echo inside php tags, or be more subtle and use a layout (more on this later).

Can you have other functions besides display? I don't know. This is something that the gurus must answer. Where does the display function come from? Again, I don't know. Hope that someone else can help here.

Now you can go a bit further. Up to this point, you have a distributed Platform that dissects your request in such a way that allows you to create small and very specific files to react only to specific types of requests. In this way, the files that you must process can be very small and adjusted to the situation you are treating. This will speed up the global response time of the system by not loading a bunch of code that will never be used with these kinds of requests.

Having reached this point, you can dissect a bit more and have another layer of detail: the final layout for the data you deliver.

A layout is a way to present the data for the view. The same data can be delivered under different visual aspects so that the same preparation code (inside the display function of your view class) can present the same data in different ways simply using different files. You 'inject' the view data into the layout template and use the template code to visually format it for presenting to the user.

As before, if you do not specify a layout, the 'default' layout will be used. To use layouts you need to create a new folder under the related view folder named 'tmpl' and create a file named <mylayout>.php, nothing more, nothing less. If you are using the default layout this file will be named 'default.php'.

The desired layout can be specified in the request by means of a 'layout=<mylayout>' variable or can be injected in the call if you manage to get the layout you want to use from other sources.

To use a layout, your view class must call 'parent::display();' and pass the layout template name as a parameter. So your class should be:

class <Name>View<Viewname> extends JViewLegacy
  function display($tpl=null)
    // Prepare the data
    $data1 = ....
    $data2 = ....
    $moredata[] = array....
    // Inject the data
    $this->variablename = $data1;
    $this->variablename2 = $data2;
    $this->variablename3 = $moredata;
    // Call the layout template. If no tpl value is set Joomla! will look for a default.php file
    $tpl = 'myTemplate';

This way, Joomla! will look for a file named 'myTemplate.php' in the 'tmpl' folder of the given view. Inside this template file you get a '$this' object that has access to the variables you have injected by means of '$this->variablename' that you can use in your constructions to deliver your HTML *FINAL* code.

As you will have determined by now, you can have different layout files in your tmpl folder, which can easily drive your output with simple, small, very specific files.

If you have been observant, you will have noticed that you have not 'used' the 'model' part of MVC model. Here you have the last point of decision. You can go without this part or fully apply the model, but I think I will keep this tale for another session, for I am sure that I have already abused my audience.