How Joomla pieces work together - Joomla!

Documentation

http://docs.joomla.org/index.php?title=How_Joomla_pieces_work_toget...

From Joomla! Documentation
Some weeks ago I was asked to confirm if a custom PHP web development with a high budget was the right path to follow. After having a look at the goals of the project I thought that the custom path was overkill and told him that I believed that any open source CMS customization could deliver the same for lot less money. Having made a selection a year or so before I recommended Joomla! as the right tool for the job expecting that my paper will end at this point. But I finally got involved. The only weak point of Joomla! at the time I made my selection (version 1.x) was that is was slow because of the huge joomla.php library file but I thought when making my recommendation that the new hardware we have now would compensate. But to my surprise the Joomla! 1.5.2 framework had just been released and a first look at it was promising. The problem was that there is very little, if any information at all about how the pieces that Joomla! connect with each other. After developing a component, a module and a plugin to achieve the goals of the project, I had to look at lots of disparate small documents, source code and tantra to learn how these pieces work together to make the new Joomla! 1.5. It's a fabulous environment to develop web solutions in an easy and powerful way. My congratulations to the development group that has been able to envision such a magnificent tool. This document is my attempt to express to the community what I have learned while developing the project and also learn from the feedback and help from others. Because I am quite sure that there are lots of things that need revision I humbly request the help of the Joomla! gurus out there to take the time to read this somehow long dissertation and feed me with their knowledge. And, not less important, I request your tolerance if my English is not Oxford-like because I am not a native English speaking person. Luckily, this is a wiki, and others have come by to help with some editing. Ok. Let's start... You enter the Joomla! framework 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! framework tries to find and load the file components/com_<name>/<name>.php from whatever the 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' and it is in this file where 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! framework 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 fails. You start all the fireworks by including 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.DS.'controller.php');

1 of 6

7/9/2011 11:49 PM

2 of 6 7/9/2011 11:49 PM . in this case. but you could do it!) From now on the Joomla! framework will begin loading your files and calling your classes automatically. it is named after your component so you write: class <name>Controller extends JController { } In this stage you have your first two files. Now that you have controller. So far so good and easy. Where does the 'task' in the execute call come from? Do you really have a meaningful 'task' variable? Yes. Up to now you were able to name files. Joomla! will use its defaults to complete a request. Where does the Joomla! framework get the data to play?. Well.php and make a reference to the controller library inside by importing it with: jimport('joomla.php?title=How_Joomla_pieces_work_toget. because you have not specified otherwise. So add these lines to your base file: // Create the controller $controller = new <name>Controller().. by convention. you have to define a class that extends the JController base class.component.org/index. or whatever the name you gave your controller cl // Perform the Request task $controller->execute(JRequest::getCmd('task')). Your controller. The base file loads the controller and the controller defines a class. and therein lies a 'problem': Whether you pass a request or not. except for the base one.Joomla! Documentation http://docs. (Well. the base file and the controller file. The next step is to create an object of this class and to put it to work. so you must be careful where you put your files. only one file and only one class actually. But you have NOT written anything else in the request except option=com_<name>.joomla..controller'). making some errors difficult to spot. because a single letter mismatch will make Joomla! fail.php included and the base JController class imported. The controller->execute() call will make the Joomla! framework try to do a request that. being it windows or linux.php file can be created anywhere you want because we are including it by path but if you have written exactly the former line 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 and DS represents the path separator translated to whatever is convenient for your OS. So create controller. be it a GET request or a POST request. From this point on things start happening by themselves. will be the default task 'display'. the answer is easy: from the request. You can name this class as you like but. and put them where you wanted. what you name them and what classes you define.application. and name classes like you wanted because you were including the files by path/name and calling your classes yourself.How Joomla pieces work together . This is the class leg you wrote before about and it is here where your action will happen.

'task' is usually used (and as it is treated specially by the system.How Joomla pieces work together . components usually had a switch statement that. You deliver different parts of your data with different views. class <name>Controller extends JController { function display() { echo 'displaying'. you have to call the display() method of JController.joomla. It's the same concept as views in SQL parlance.php?title=How_Joomla_pieces_work_toget. With Joomla! 1.component.1. the switch is gone and your different tasks are methods in the controller. called a function with several arguments to deliver the HTML result.5.Joomla! Documentation http://docs. At a minimum. it is a good idea to stick with it). in your method. 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.application. Arguments are lost but all the needed variables are available from the framework so you will be able to retrieve them easily. } } Up to now you have delved with the controller part of the model. } } What's a view? A view is a subset of data. You can stop here or go a step further and enter the view part.php file. the later presenting a subset of the whole data presented in the former.controller'). To trigger the views. simplify your base file over Joomla! 1. } } So that 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 JController { function jump() { echo 'jumping'. depending on the given task (or whatever passed variable). your controller file should contain the following: (?Is this necessary? The display function should be pulled from the JController class that it is extending.org/index. a call to parent::display() as in the last line. So you could have a detailed data view and a resumed data view. class <name>Controller extends JController { function display() { parent::display().5. But in order to stick to the non-written rules. This is a new point of decision.. at least.x . right?) jimport('joomla. Do this by inserting. Stopping here will. As you can have multiple views Joomla! uses the 'views' folder in your component's base directory to keep 3 of 6 7/9/2011 11:49 PM .. Up to version 1.

now you need the view class. etc. You have the view file. The specific format you are using is what you have written in the middle part of the name of the file in your view folder (The file we talked about a few lines before 'view.org/index.. you will need some code inside the view.php that should exist in your view folder.joomla...Joomla! Documentation http://docs. It's that easy. you need to include it now because there is no such a thing as a default view. rss.php file.rss.php?title=How_Joomla_pieces_work_toget.php <component_name>. With this URL Joomla! is importing a file located at <site root dir>/components/<name>/views/<myview>/view. if you did not include it. Anyway. If this files or the path does not exist. If you use a different format like 'rss' your file should be named after it like view. So your class name will be a capitalized <name>View<myview>.php.php'). In this case. so I'll try to explain. The Joomla! framework includes a file named view. but you can use your own. things tidy. Inside the views folder other folders hold the files that build each view. This means that you need to create a views folder with a hierarchy that looks like this: <name> base folder controller. This way.php?option=com_<name>&view=<myview>[&task=<mytask>] The task part may or may not exist. There exist several well known formats such as html (the default one if none is specified). Joomla! will fail. The 'html' format makes the Joomla! framework wrap the response in whatever template your site is using so that you get a fully built HTML page. Get it? As mentioned before. the word 'View'.com/index. When you built your request. If no format is specified in the request with the 'format=<myformat>' parameter a default value of 'html' is used. I know.html.php. You have to extend the JView class with your own class following the strict rules mentioned before. you get back your page fully loaded with modules or whatever you had configured. you included a variable named 'view' that tells the MVC model what view you want. with very little effort from you. Or.com/index.html. A bit messy.?option=com_read&view=detail) your view class must be: 4 of 6 7/9/2011 11:49 PM .php 'views' folder view1 folder view2 folder .<format>. Just construct your URL like http://example. Every request for a view requires that you also specify the format you are serving the view.. you deliver different views of your data. 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. and the view name.html. By simply swapping the value of the view. to achieve your goal. you can have formats other than html and Joomla! will not wrap the template on them. Remember that if you omit it you are defaulting to task=display.ajax.php?option=com_<name>&view=<myview>&format=ajax to make the Joomla! Framework look for and load the file view. If your component is named travels and your view is named detail (URL . So your URL is something like: http://example.How Joomla pieces work together . This folder is only a placeholder for your views. your class name must be built by concatenating the component name.php located at <site root dir>/components /<name>/views/<myview>/ from where you can echo anything you want...

Where does the display function come from? Again. class TravelsViewDetail extends JView { function display($tpl=null) { echo 'blah. } } Within this class you only have to feed the data you want to display for your component under this specific case. or be more subtle and use a layout (more on this later).' and pass the layout template name as a parameter.org/index. A layout is a way to present the data for the view. if you do not specify a layout you go with the 'default' layout. Having reached this point you can dissect a bit more and have another layer of detail: the final layout for the data you deliver..x).php. So your class should be: 5 of 6 7/9/2011 11:49 PM .How Joomla pieces work together . You can do this directly by delivering the [x]HTML code directly. To use layouts you need to create a new folder under the related view folder named 'tmpl' and create a file named <mylayout>. nothing more nothing less.php?title=How_Joomla_pieces_work_toget. You 'inject' the view data in the layout template and use the template code to visually format it for presenting to the user. In this way the files that you must process can be very small and adjusted to the situation you are treating. I don't know. Can you have other functions besides display? I don't know. As before. 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. Hope that someone else can help here. But you can go a bit further.joomla.Joomla! Documentation http://docs. blah'.. If you are using the default layout this file will be named 'default. This is something that the gurus must answer.php'. To use a layout your view class must call 'parent::display(). speeding up the global response time of the system by not loading lots of code that will not ever be used with this kind of requests (as in Joomla! 1. 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. Up to this point you have a distributed framework that dissects your request in such a way that allow you to create small and very specific files to react only to specific types of requests. or through calls to echo inside php tags.

$moredata). // Inject the data $this->assignRef('variablename'.. 6 of 6 7/9/2011 11:49 PM ..php?title=How_Joomla_pieces_work_toget. parent::display($tpl).joomla.Joomla! Documentation http://docs.php' in the 'tmpl' folder of the given view. You can go without this part or apply fully the model but I think I will keep this tale for another session..How Joomla pieces work together . 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 [x]HTML *FINAL* code. $this->assignRef('variablename3'.org/How_Joomla_pieces_work_together" Categories: Tips and tricks | Tips and tricks 1. small.. Here you have the last point of decision.org/index. $data2). class <Name>View<Viewname> extends JView { function display($tpl=null) { // Prepare the data $data1 = .joomla.5 | Tutorials | Component Development This page was last modified on 9 February 2011. Content is available under Joomla! EDL. $data1)... For sure I have already abused of my audience. Retrieved from "http://docs.. $this->assignRef('variablename2'. at 21:17. // Call the layout template $tpl = 'myTemplate'. If you have been observant you will have noticed that you have not 'used' the 'model' part of MVC model.. $data2 = . } } This way Joomla! will look for a file named 'myTemplate. $moredata[] = array. As you surely will have determined by this moment by yourself you can have different layouts files in your tmpl folder thus driving easily your output with simple. very specific files.... or more directly parent::display('myTemplate').

Sign up to vote on this title
UsefulNot useful

Master Your Semester with Scribd & The New York Times

Special offer: Get 4 months of Scribd and The New York Times for just $1.87 per week!

Master Your Semester with a Special Offer from Scribd & The New York Times