Joomla! Documentation - User contributions [en]

API16:JParameter/ construct

2011-04-04T14:53:07Z

Datashuttle: /* Syntax */

===Description===
Constructor


<nowiki>[</nowiki>[[Description:JParameter/__construct|Edit Descripton]]<nowiki>]</nowiki>


{{Description:JParameter/__construct}}

===Syntax===
<source lang="php">__construct($data= '', $path= '')</source>

{| class="wikitable"
|-
!Parameter Name
!Default Value
!Description
|-
| $data
| ''
| The raw params text
|-
| $path
| ''
| Path to the xml setup file
|}

===Defined in===
libraries/joomla/html/parameter.php
===Importing===
<source lang="php">jimport( 'joomla.html.parameter' );</source>

===Source Body===
<source lang="php">
public function __construct($data = '', $path = '')
{
parent::__construct('_default');

// Set base path.
$this->_elementPath[] = dirname(__FILE__).DS.'parameter'.DS.'element';

if ($data = trim($data)) {
if (strpos($data, '{') === 0) {
$this->loadJSON($data);
} else {
$this->loadINI($data);
}
}

if ($path) {
$this->loadSetupFile($path);
}

$this->_raw = $data;
}
</source>


<nowiki>[</nowiki>[[SeeAlso:JParameter/__construct|Edit See Also]]<nowiki>]</nowiki>

{{SeeAlso:JParameter/__construct}}

===Examples===
<CodeExamplesForm />
<dpl>
noresultsheader=\n
category=__construct
category=JParameter
category=CodeExample
category=MethodExample
include=*
format= ,,,
</dpl>

Absolute Basics of How a Component Functions

2011-02-09T21:17:48Z

Datashuttle:

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:

<source lang="php">
require_once(JPATH_COMPONENT.DS.'controller.php');
</source>

Your controller.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, being it windows or linux.

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

<source lang="php">
jimport('joomla.application.component.controller');
</source>

Now that you have controller.php included and the base JController class imported, you have to define a class that extends the JController base class. This is the class leg you wrote before about and 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:

<source lang="php">
class <name>Controller extends JController
{
}
</source>

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 these lines to your base file:

<source lang="php">
// Create the controller
$controller = new <name>Controller(); or whatever the name you gave your controller class

// Perform the Request task
$controller->execute(JRequest::getCmd('task'));
</source>

From this point on things start happening by themselves. Up to now you were able to name files, except for the base one, and put them where you wanted, and name classes like you wanted because you were including the files by path/name and calling your classes yourself. (Well, only one file and only one class actually, but you could do it!) From now on the Joomla! framework 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, because a single letter mismatch will make Joomla! fail.

Where does the Joomla! framework 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! framework try to do a request that, in this case, will be the default task 'display', because you have not specified otherwise.

<source lang="php">
class <name>Controller extends JController
{
function display()
{
echo 'displaying';
}
}
</source>

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:

<source lang="php">
class <name>Controller extends JController
{
function jump()
{
echo 'jumping';
}
}
</source>

Up to now you have delved with 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. Stopping here will, at least, simplify your base file over Joomla! 1.1.x . Up to version 1.5, components usually had a switch statement that, depending on the given task (or whatever passed variable), called a function with several arguments to deliver the HTML result.

With Joomla! 1.5, the switch is gone and your different tasks are methods in the controller.php file. Arguments are lost but all the needed variables are available from the framework 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 display() method of JController. Do this by inserting, in your method, a call to parent::display() as in the last line. At a minimum, your controller file should contain the following: (?Is this necessary? The display function should be pulled from the JController class that it is extending, right?)

<source lang="php">
jimport('joomla.application.component.controller');

class <name>Controller extends JController
{
function display()
{
parent::display();
}
}
</source>

'''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
controller.php
<component_name>.php
'views' folder
view1 folder
view2 folder
...

Inside the views folder other folders hold the files that build each view. The Joomla! framework 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:

http://example.com/index.php?option=com_<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 files 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 you are serving the view. There exist several well known formats such as html (the default one if none is specified), rss, etc. but 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! framework 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 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.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

http://example.com/index.php?option=com_<name>&view=<myview>&format=ajax

to make the Joomla! Framework look for and load the file view.ajax.php located at <site root dir>/components/<name>/views/<myview>/ from where 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_read&view=detail) your view class must be:

<source lang="php">
class TravelsViewDetail extends JView
{
function display($tpl=null)
{
echo 'blah, blah';
}
}
</source>

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 [x]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.

But you can go a bit further. 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. In this way the files that you must process can be very small and adjusted to the situation you are treating, 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.x).

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 in 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 you go with the 'default' layout. 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:

<source lang="php">
class <Name>View<Viewname> extends JView
{
function display($tpl=null)
{
// Prepare the data
$data1 = ....
$data2 = ....
$moredata[] = array....

// Inject the data
$this->assignRef('variablename', $data1);
$this->assignRef('variablename2', $data2);
$this->assignRef('variablename3', $moredata);

// Call the layout template
$tpl = 'myTemplate';
parent::display($tpl);

or more directly

parent::display('myTemplate');
}
}
</source>

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 [x]HTML *FINAL* code.

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, 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 apply fully the model but I think I will keep this tale for another session. For sure I have already abused of my audience.

[[Category:Tips and tricks]]
[[Category:Tips and tricks 1.5]]

[[Category:Tutorials]][[Category:Component Development]]

Absolute Basics of How a Component Functions

2011-02-09T21:12:27Z

Datashuttle:

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:

<source lang="php">
require_once(JPATH_COMPONENT.DS.'controller.php');
</source>

Your controller.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, being it windows or linux.

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

<source lang="php">
jimport('joomla.application.component.controller');
</source>

Now that you have controller.php included and the base JController class imported, you have to define a class that extends the JController base class. This is the class leg you wrote before about and 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:

<source lang="php">
class <name>Controller extends JController
{
}
</source>

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 these lines to your base file:

<source lang="php">
// Create the controller
$controller = new <name>Controller(); or whatever the name you gave your controller class

// Perform the Request task
$controller->execute(JRequest::getCmd('task'));
</source>

From this point on things start happening by themselves. Up to now you were able to name files, except for the base one, and put them where you wanted, and name classes like you wanted because you were including the files by path/name and calling your classes yourself. (Well, only one file and only one class actually, but you could do it!) From now on the Joomla! framework 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, because a single letter mismatch will make Joomla! fail.

Where does the Joomla! framework 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! framework try to do a request that, in this case, will be the default task 'display', because you have not specified otherwise.

<source lang="php">
class <name>Controller extends JController
{
function display()
{
echo 'displaying';
}
}
</source>

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:

<source lang="php">
class <name>Controller extends JController
{
function jump()
{
echo 'jumping';
}
}
</source>

Up to now you have delved with 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. Stopping here will, at least, simplify your base file over Joomla! 1.1.x . Up to version 1.5, components usually had a switch statement that, depending on the given task (or whatever passed variable), called a function with several arguments to deliver the HTML result.

With Joomla! 1.5, the switch is gone and your different tasks are methods in the controller.php file. Arguments are lost but all the needed variables are available from the framework 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 display() method of JController. Do this by inserting, in your method, a call to parent::display() as in the last line. At a minimum, your controller file should contain the following: (?Is this necessary? The display function should be pulled from the JController class that it is extending, right?)

<source lang="php">
jimport('joomla.application.component.controller');

class <name>Controller extends JController
{
function display()
{
parent::display();
}
}
</source>

'''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
controller.php
<component_name>.php
'views' folder
view1 folder
view2 folder
...

Inside the views folder other folders hold the files that build each view. The Joomla! framework 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:

http://example.com/index.php?option=com_<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 files 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 you are serving the view. There exist several well known formats such as html (the default one if none is specified), rss, etc. but 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! framework 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 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.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

http://example.com/index.php?option=com_<name>&view=<myview>&format=ajax

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

Anyway, to achieve your goal you 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, that you should follow. 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_read&view=detail) your view class must be:

<source lang="php">
class TravelsViewDetail extends JView
{
function display($tpl=null)
{
echo 'blah, blah';
}
}
</source>

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 [x]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.

But you can go a bit further. 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. In this way the files that you must process can be very small and adjusted to the situation you are treating, 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.x).

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 in 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 you go with the 'default' layout. 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:

<source lang="php">
class <Name>View<Viewname> extends JView
{
function display($tpl=null)
{
// Prepare the data
$data1 = ....
$data2 = ....
$moredata[] = array....

// Inject the data
$this->assignRef('variablename', $data1);
$this->assignRef('variablename2', $data2);
$this->assignRef('variablename3', $moredata);

// Call the layout template
$tpl = 'myTemplate';
parent::display($tpl);

or more directly

parent::display('myTemplate');
}
}
</source>

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 [x]HTML *FINAL* code.

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, 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 apply fully the model but I think I will keep this tale for another session. For sure I have already abused of my audience.

[[Category:Tips and tricks]]
[[Category:Tips and tricks 1.5]]

[[Category:Tutorials]][[Category:Component Development]]

Absolute Basics of How a Component Functions

2011-02-08T23:40:04Z

Datashuttle:

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:

<source lang="php">
require_once(JPATH_COMPONENT.DS.'controller.php');
</source>

Your controller.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, being it windows or linux.

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

<source lang="php">
jimport('joomla.application.component.controller');
</source>

Now that you have controller.php included and the base JController class imported, you have to define a class that extends the JController base class. This is the class leg you wrote before about and 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:

<source lang="php">
class <name>Controller extends JController
{
}
</source>

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 these lines to your base file:

<source lang="php">
// Create the controller
$controller = new <name>Controller(); or whatever the name you gave your controller class

// Perform the Request task
$controller->execute(JRequest::getCmd('task'));
</source>

From this point on things start happening by themselves. Up to now you were able to name files, except for the base one, and put them where you wanted, and name classes like you wanted because you were including the files by path/name and calling your classes yourself. (Well, only one file and only one class actually, but you could do it!) From now on the Joomla! framework 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, because a single letter mismatch will make Joomla! fail.

Where does the Joomla! framework 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! framework try to do a request that, in this case, will be the default task 'display', because you have not specified otherwise.

<source lang="php">
class <name>Controller extends JController
{
function display()
{
echo 'displaying';
}
}
</source>

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:

<source lang="php">
class <name>Controller extends JController
{
function jump()
{
echo 'jumping';
}
}
</source>

Up to now you have delved with 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. Stopping here will, at least, simplify your base file over Joomla! 1.1.x . Up to version 1.5, components usually had a switch statement that, depending on the given task (or whatever passed variable), called a function with several arguments to deliver the HTML result.

With Joomla! 1.5, the switch is gone and your different tasks are methods in the controller.php file. Arguments are lost but all the needed variables are available from the framework 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 display() method of JController. Do this by inserting, in your method, a call to parent::display() as in the last line. At a minimum, your controller file should contain the following: (?Is this necessary? The display function should be pulled from the JController class that it is extending, right?)

<source lang="php">
jimport('joomla.application.component.controller');

class <name>Controller extends JController
{
function display()
{
parent::display();
}
}
</source>

'''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
controller.php
<component_name>.php
'views' folder
view1 folder
view2 folder
...

Inside the views folder other folders hold the files that build each view. The Joomla! framework 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:

http://example.com/index.php?option=com_<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 files 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 you are serving the view. There exist several well known formats such as html (the default one if none is specified), rss, etc. but 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! framework wrap the response in whatever template your site is using so that you get a fully built HTML page. This way, with very few effort from you side, you get back your page fully loaded with modules or whatever you had configured.

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.html.php'). If you use a different format like 'rss' your file should be named after it like view.rss.php. Get it?

As told 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

http://example.com/index.php?option=com_<name>&view=<myview>&format=ajax

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

Anyway, to achieve your goal you 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, that you should follow. 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_read&view=detail) your view class must be:

<source lang="php">
class TravelsViewDetail extends JView
{
function display($tpl=null)
{
echo 'blah, blah';
}
}
</source>

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 [x]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.

But you can go a bit further. 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. In this way the files that you must process can be very small and adjusted to the situation you are treating, 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.x).

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 in 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 you go with the 'default' layout. 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:

<source lang="php">
class <Name>View<Viewname> extends JView
{
function display($tpl=null)
{
// Prepare the data
$data1 = ....
$data2 = ....
$moredata[] = array....

// Inject the data
$this->assignRef('variablename', $data1);
$this->assignRef('variablename2', $data2);
$this->assignRef('variablename3', $moredata);

// Call the layout template
$tpl = 'myTemplate';
parent::display($tpl);

or more directly

parent::display('myTemplate');
}
}
</source>

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 [x]HTML *FINAL* code.

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, 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 apply fully the model but I think I will keep this tale for another session. For sure I have already abused of my audience.

[[Category:Tips and tricks]]
[[Category:Tips and tricks 1.5]]

[[Category:Tutorials]][[Category:Component Development]]

Absolute Basics of How a Component Functions

2011-02-08T23:37:59Z

Datashuttle:

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:

<source lang="php">
require_once(JPATH_COMPONENT.DS.'controller.php');
</source>

Your controller.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, being it windows or linux.

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

<source lang="php">
jimport('joomla.application.component.controller');
</source>

Now that you have controller.php included and the base JController class imported, you have to define a class that extends the JController base class. This is the class leg you wrote before about and 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:

<source lang="php">
class <name>Controller extends JController
{
}
</source>

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 these lines to your base file:

<source lang="php">
// Create the controller
$controller = new <name>Controller(); or whatever the name you gave your controller class

// Perform the Request task
$controller->execute(JRequest::getCmd('task'));
</source>

From this point on things start happening by themselves. Up to now you were able to name files, except for the base one, and put them where you wanted, and name classes like you wanted because you were including the files by path/name and calling your classes yourself. (Well, only one file and only one class actually, but you could do it!) From now on the Joomla! framework 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, because a single letter mismatch will make Joomla! fail.

Where does the Joomla! framework 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 this is the 'problem': Whether you pass or do not pass a full request, Joomla! will use its defaults to complete a request, making some errors difficult to spot.

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

<source lang="php">
class <name>Controller extends JController
{
function display()
{
echo 'displaying';
}
}
</source>

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:

<source lang="php">
class <name>Controller extends JController
{
function jump()
{
echo 'jumping';
}
}
</source>

Up to now you have delved with 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. Stopping here will, at least, simplify your base file over Joomla! 1.1.x . Up to version 1.5, components usually had a switch statement that, depending on the given task (or whatever passed variable), called a function with several arguments to deliver the HTML result.

With Joomla! 1.5, the switch is gone and your different tasks are methods in the controller.php file. Arguments are lost but all the needed variables are available from the framework 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 display() method of JController. Do this by inserting, in your method, a call to parent::display() as in the last line. At a minimum, your controller file should contain the following: (?Is this necessary? The display function should be pulled from the JController class that it is extending, right?)

<source lang="php">
jimport('joomla.application.component.controller');

class <name>Controller extends JController
{
function display()
{
parent::display();
}
}
</source>

'''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
controller.php
<component_name>.php
'views' folder
view1 folder
view2 folder
...

Inside the views folder other folders hold the files that build each view. The Joomla! framework 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:

http://example.com/index.php?option=com_<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 files 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 you are serving the view. There exist several well known formats such as html (the default one if none is specified), rss, etc. but 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! framework wrap the response in whatever template your site is using so that you get a fully built HTML page. This way, with very few effort from you side, you get back your page fully loaded with modules or whatever you had configured.

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.html.php'). If you use a different format like 'rss' your file should be named after it like view.rss.php. Get it?

As told 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

http://example.com/index.php?option=com_<name>&view=<myview>&format=ajax

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

Anyway, to achieve your goal you 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, that you should follow. 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_read&view=detail) your view class must be:

<source lang="php">
class TravelsViewDetail extends JView
{
function display($tpl=null)
{
echo 'blah, blah';
}
}
</source>

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 [x]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.

But you can go a bit further. 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. In this way the files that you must process can be very small and adjusted to the situation you are treating, 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.x).

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 in 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 you go with the 'default' layout. 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:

<source lang="php">
class <Name>View<Viewname> extends JView
{
function display($tpl=null)
{
// Prepare the data
$data1 = ....
$data2 = ....
$moredata[] = array....

// Inject the data
$this->assignRef('variablename', $data1);
$this->assignRef('variablename2', $data2);
$this->assignRef('variablename3', $moredata);

// Call the layout template
$tpl = 'myTemplate';
parent::display($tpl);

or more directly

parent::display('myTemplate');
}
}
</source>

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 [x]HTML *FINAL* code.

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, 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 apply fully the model but I think I will keep this tale for another session. For sure I have already abused of my audience.

[[Category:Tips and tricks]]
[[Category:Tips and tricks 1.5]]

[[Category:Tutorials]][[Category:Component Development]]

Absolute Basics of How a Component Functions

2011-02-08T23:35:45Z

Datashuttle:

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:

<source lang="php">
require_once(JPATH_COMPONENT.DS.'controller.php');
</source>

Your controller.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, being it windows or linux.

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

<source lang="php">
jimport('joomla.application.component.controller');
</source>

Now that you have controller.php included and the base JController class imported, you have to define a class that extends the JController base class. This is the class leg you wrote before about and 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:

<source lang="php">
class <name>Controller extends JController
{
}
</source>

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 these lines to your base file:

<source lang="php">
// Create the controller
$controller = new <name>Controller(); or whatever the name you gave your controller class

// Perform the Request task
$controller->execute(JRequest::getCmd('task'));
</source>

From this point on things start happening by themselves. Up to now you were able to name files, except for the base one, and put them where you wanted, and name classes like you wanted because you were including the files by path/name and calling your classes yourself. (Well, only one file and only one class actually, but you could do it!) From now on the Joomla! framework 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, because a single letter mismatch will make Joomla! fail.

Where does the Joomla! framework 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 this is the 'problem': Whether you pass or do not pass a full request, Joomla! will use its defaults to complete a request, making some errors difficult to spot.

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

<source lang="php">
class <name>Controller extends JController
{
function display()
{
echo 'displaying';
}
}
</source>

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:

<source lang="php">
class <name>Controller extends JController
{
function jump()
{
echo 'jumping';
}
}
</source>

Up to now you have delved with 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. Stopping here will, at least, simplify your base file over Joomla! 1.1.x . Up to version 1.5, components usually had a switch statement that, depending on the given task (or whatever passed variable), called a function with several arguments to deliver the HTML result.

With Joomla! 1.5, the switch is gone and your different tasks are methods in the controller.php file. Arguments are lost but all the needed variables are available from the framework 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 display() method of JController. Do this by inserting, in your method, a call to parent::display() as in the last line. At a minimum, your controller file should contain the following: (?Is this necessary? The display function should be pulled from the JController class that it is extending, right?)

<source lang="php">
jimport('joomla.application.component.controller');

class <name>Controller extends JController
{
function display()
{
parent::display();
}
}
</source>

'''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
controller.php
<component_name>.php
'views' folder
view1 folder
view2 folder
...

Inside the views folder other folders hold the files that build each view. The Joomla! framework 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 better include it now because there is not such a thing like a default view. So your URL was something like:

http://example.com/index.php?option=com_<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 files 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 you are serving the view. There exist several well known formats such as html (the default one if none is specified), rss, etc. but 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! framework wrap the response in whatever template your site is using so that you get a fully built HTML page. This way, with very few effort from you side, you get back your page fully loaded with modules or whatever you had configured.

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.html.php'). If you use a different format like 'rss' your file should be named after it like view.rss.php. Get it?

As told 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

http://example.com/index.php?option=com_<name>&view=<myview>&format=ajax

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

Anyway, to achieve your goal you 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, that you should follow. 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_read&view=detail) your view class must be:

<source lang="php">
class TravelsViewDetail extends JView
{
function display($tpl=null)
{
echo 'blah, blah';
}
}
</source>

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 [x]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.

But you can go a bit further. 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. In this way the files that you must process can be very small and adjusted to the situation you are treating, 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.x).

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 in 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 you go with the 'default' layout. 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:

<source lang="php">
class <Name>View<Viewname> extends JView
{
function display($tpl=null)
{
// Prepare the data
$data1 = ....
$data2 = ....
$moredata[] = array....

// Inject the data
$this->assignRef('variablename', $data1);
$this->assignRef('variablename2', $data2);
$this->assignRef('variablename3', $moredata);

// Call the layout template
$tpl = 'myTemplate';
parent::display($tpl);

or more directly

parent::display('myTemplate');
}
}
</source>

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 [x]HTML *FINAL* code.

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, 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 apply fully the model but I think I will keep this tale for another session. For sure I have already abused of my audience.

[[Category:Tips and tricks]]
[[Category:Tips and tricks 1.5]]

[[Category:Tutorials]][[Category:Component Development]]

Absolute Basics of How a Component Functions

2011-02-08T23:34:13Z

Datashuttle:

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:

<source lang="php">
require_once(JPATH_COMPONENT.DS.'controller.php');
</source>

Your controller.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, being it windows or linux.

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

<source lang="php">
jimport('joomla.application.component.controller');
</source>

Now that you have controller.php included and the base JController class imported, you have to define a class that extends the JController base class. This is the class leg you wrote before about and 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:

<source lang="php">
class <name>Controller extends JController
{
}
</source>

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 these lines to your base file:

<source lang="php">
// Create the controller
$controller = new <name>Controller(); or whatever the name you gave your controller class

// Perform the Request task
$controller->execute(JRequest::getCmd('task'));
</source>

From this point on things start happening by themselves. Up to now you were able to name files, except for the base one, and put them where you wanted, and name classes like you wanted because you were including the files by path/name and calling your classes yourself. (Well, only one file and only one class actually, but you could do it!) From now on the Joomla! framework 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, because a single letter mismatch will make Joomla! fail.

Where does the Joomla! framework 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 this is the 'problem': Whether you pass or do not pass a full request, Joomla! will use its defaults to complete a request, making some errors difficult to spot.

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

<source lang="php">
class <name>Controller extends JController
{
function display()
{
echo 'displaying';
}
}
</source>

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:

<source lang="php">
class <name>Controller extends JController
{
function jump()
{
echo 'jumping';
}
}
</source>

Up to now you have delved with 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. Stopping here will, at least, simplify your base file over Joomla! 1.1.x . Up to version 1.5, components usually had a switch statement that, depending on the given task (or whatever passed variable), called a function with several arguments to deliver the HTML result.

With Joomla! 1.5, the switch is gone and your different tasks are methods in the controller.php file. Arguments are lost but all the needed variables are available from the framework 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 display() method of JController. Do this by inserting, in your method, a call to parent::display() as in the last line. At a minimum, your controller file should contain the following: (?Is this necessary? The display function should be pulled from the JController class that it is extending, right?)

<source lang="php">
jimport('joomla.application.component.controller');

class <name>Controller extends JController
{
function display()
{
parent::display();
}
}
</source>

'''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
controller.php
<component_name>.php
'views' folder
view1 folder
view2 folder
...

Inside the views folder other folders hold the files that build each view. The Joomla! framework includes a file named view.html.php that should exist in your view directory. 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 better include it now because there is not such a thing like a default view. So your URL was something like:

http://example.com/index.php?option=com_<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 files 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 you are serving the view. There exist several well known formats such as html (the default one if none is specified), rss, etc. but 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! framework wrap the response in whatever template your site is using so that you get a fully built HTML page. This way, with very few effort from you side, you get back your page fully loaded with modules or whatever you had configured.

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.html.php'). If you use a different format like 'rss' your file should be named after it like view.rss.php. Get it?

As told 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

http://example.com/index.php?option=com_<name>&view=<myview>&format=ajax

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

Anyway, to achieve your goal you 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, that you should follow. 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_read&view=detail) your view class must be:

<source lang="php">
class TravelsViewDetail extends JView
{
function display($tpl=null)
{
echo 'blah, blah';
}
}
</source>

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 [x]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.

But you can go a bit further. 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. In this way the files that you must process can be very small and adjusted to the situation you are treating, 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.x).

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 in 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 you go with the 'default' layout. 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:

<source lang="php">
class <Name>View<Viewname> extends JView
{
function display($tpl=null)
{
// Prepare the data
$data1 = ....
$data2 = ....
$moredata[] = array....

// Inject the data
$this->assignRef('variablename', $data1);
$this->assignRef('variablename2', $data2);
$this->assignRef('variablename3', $moredata);

// Call the layout template
$tpl = 'myTemplate';
parent::display($tpl);

or more directly

parent::display('myTemplate');
}
}
</source>

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 [x]HTML *FINAL* code.

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, 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 apply fully the model but I think I will keep this tale for another session. For sure I have already abused of my audience.

[[Category:Tips and tricks]]
[[Category:Tips and tricks 1.5]]

[[Category:Tutorials]][[Category:Component Development]]

Absolute Basics of How a Component Functions

2011-02-08T23:32:59Z

Datashuttle:

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:

<source lang="php">
require_once(JPATH_COMPONENT.DS.'controller.php');
</source>

Your controller.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, being it windows or linux.

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

<source lang="php">
jimport('joomla.application.component.controller');
</source>

Now that you have controller.php included and the base JController class imported, you have to define a class that extends the JController base class. This is the class leg you wrote before about and 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:

<source lang="php">
class <name>Controller extends JController
{
}
</source>

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 these lines to your base file:

<source lang="php">
// Create the controller
$controller = new <name>Controller(); or whatever the name you gave your controller class

// Perform the Request task
$controller->execute(JRequest::getCmd('task'));
</source>

From this point on things start happening by themselves. Up to now you were able to name files, except for the base one, and put them where you wanted, and name classes like you wanted because you were including the files by path/name and calling your classes yourself. (Well, only one file and only one class actually, but you could do it!) From now on the Joomla! framework 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, because a single letter mismatch will make Joomla! fail.

Where does the Joomla! framework 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 this is the 'problem': Whether you pass or do not pass a full request, Joomla! will use its defaults to complete a request, making some errors difficult to spot.

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

<source lang="php">
class <name>Controller extends JController
{
function display()
{
echo 'displaying';
}
}
</source>

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:

<source lang="php">
class <name>Controller extends JController
{
function jump()
{
echo 'jumping';
}
}
</source>

Up to now you have delved with 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. Stopping here will, at least, simplify your base file over Joomla! 1.1.x . Up to version 1.5, components usually had a switch statement that, depending on the given task (or whatever passed variable), called a function with several arguments to deliver the HTML result.

With Joomla! 1.5, the switch is gone and your different tasks are methods in the controller.php file. Arguments are lost but all the needed variables are available from the framework 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 display() method of JController. Do this by inserting, in your method, a call to parent::display() as in the last line. At a minimum, your controller file should contain the following: (?Is this necessary? The display function should be pulled from the JController class that it is extending, right?)

<source lang="php">
jimport('joomla.application.component.controller');

class <name>Controller extends JController
{
function display()
{
parent::display();
}
}
</source>

'''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
controller.php
<component_name>.php
'views' folder
view1 folder
view2 folder
...

Inside the views folder other folders hold the files that build each view. The Joomla! framework includes a file named view.html.php that should exist in your view directory. 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 better include it now because there is not such a thing like a default view. So your URL was something like:

http://example.com/index.php?option=com_<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 files 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 you are serving the view. There exist several well known formats such as html (the default one if none is specified), rss, etc. but 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! framework wrap the response in whatever template your site is using so that you get a fully built HTML page. This way, with very few effort from you side, you get back your page fully loaded with modules or whatever you had configured.

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.html.php'). If you use a different format like 'rss' your file should be named after it like view.rss.php. Get it?

As told 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

http://example.com/index.php?option=com_<name>&view=<myview>&format=ajax

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

Anyway, to achieve your goal you 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, that you should follow. 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_read&view=detail) your view class must be:

<source lang="php">
class TravelsViewDetail extends JView
{
function display($tpl=null)
{
echo 'blah, blah';
}
}
</source>

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 [x]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.

But you can go a bit further. 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. In this way the files that you must process can be very small and adjusted to the situation you are treating, 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.x).

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 in 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 you go with the 'default' layout. 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:

<source lang="php">
class <Name>View<Viewname> extends JView
{
function display($tpl=null)
{
// Prepare the data
$data1 = ....
$data2 = ....
$moredata[] = array....

// Inject the data
$this->assignRef('variablename', $data1);
$this->assignRef('variablename2', $data2);
$this->assignRef('variablename3', $moredata);

// Call the layout template
$tpl = 'myTemplate';
parent::display($tpl);

or more directly

parent::display('myTemplate');
}
}
</source>

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 [x]HTML *FINAL* code.

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, 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 apply fully the model but I think I will keep this tale for another session. For sure I have already abused of my audience.

[[Category:Tips and tricks]]
[[Category:Tips and tricks 1.5]]

[[Category:Tutorials]][[Category:Component Development]]

Absolute Basics of How a Component Functions

2011-02-08T23:30:45Z

Datashuttle:

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:

<source lang="php">
require_once(JPATH_COMPONENT.DS.'controller.php');
</source>

Your controller.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, being it windows or linux.

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

<source lang="php">
jimport('joomla.application.component.controller');
</source>

Now that you have controller.php included and the base JController class imported, you have to define a class that extends the JController base class. This is the class leg you wrote before about and 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:

<source lang="php">
class <name>Controller extends JController
{
}
</source>

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 these lines to your base file:

<source lang="php">
// Create the controller
$controller = new <name>Controller(); or whatever the name you gave your controller class

// Perform the Request task
$controller->execute(JRequest::getCmd('task'));
</source>

From this point on things start happening by themselves. Up to now you were able to name files, except for the base one, and put them where you wanted, and name classes like you wanted because you were including the files by path/name and calling your classes yourself. (Well, only one file and only one class actually, but you could do it!) From now on the Joomla! framework 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, because a single letter mismatch will make Joomla! fail.

Where does the Joomla! framework 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 this is the 'problem': Whether you pass or do not pass a full request, Joomla! will use its defaults to complete a request, making some errors difficult to spot.

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

<source lang="php">
class <name>Controller extends JController
{
function display()
{
echo 'displaying';
}
}
</source>

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:

<source lang="php">
class <name>Controller extends JController
{
function jump()
{
echo 'jumping';
}
}
</source>

Up to now you have delved with 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. Stopping here will, at least, simplify your base file over Joomla! 1.1.x . Up to version 1.5, components usually had a switch statement that, depending on the given task (or whatever passed variable), called a function with several arguments to deliver the HTML result.

With Joomla! 1.5, the switch is gone and your different tasks are methods in the controller.php file. Arguments are lost but all the needed variables are available from the framework 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 display() method of JController. Do this by inserting, in your method, a call to parent::display() as in the last line. At a minimum, your controller file should contain the following: (?Is this necessary? The display function should be pulled from the JController class that it is extending, right?)

<source lang="php">
jimport('joomla.application.component.controller');

class <name>Controller extends JController
{
function display()
{
parent::display();
}
}
</source>

'''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
controller.php
<component_name>.php
'views' folder
view1
view2
...

Inside the views folder other folders hold the files that build each view. The Joomla! framework includes a file named view.html.php that should exist in your view directory. 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 better include it now because there is not such a thing like a default view. So your URL was something like:

http://example.com/index.php?option=com_<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 files 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 you are serving the view. There exist several well known formats such as html (the default one if none is specified), rss, etc. but 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! framework wrap the response in whatever template your site is using so that you get a fully built HTML page. This way, with very few effort from you side, you get back your page fully loaded with modules or whatever you had configured.

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.html.php'). If you use a different format like 'rss' your file should be named after it like view.rss.php. Get it?

As told 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

http://example.com/index.php?option=com_<name>&view=<myview>&format=ajax

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

Anyway, to achieve your goal you 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, that you should follow. 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_read&view=detail) your view class must be:

<source lang="php">
class TravelsViewDetail extends JView
{
function display($tpl=null)
{
echo 'blah, blah';
}
}
</source>

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 [x]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.

But you can go a bit further. 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. In this way the files that you must process can be very small and adjusted to the situation you are treating, 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.x).

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 in 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 you go with the 'default' layout. 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:

<source lang="php">
class <Name>View<Viewname> extends JView
{
function display($tpl=null)
{
// Prepare the data
$data1 = ....
$data2 = ....
$moredata[] = array....

// Inject the data
$this->assignRef('variablename', $data1);
$this->assignRef('variablename2', $data2);
$this->assignRef('variablename3', $moredata);

// Call the layout template
$tpl = 'myTemplate';
parent::display($tpl);

or more directly

parent::display('myTemplate');
}
}
</source>

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 [x]HTML *FINAL* code.

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, 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 apply fully the model but I think I will keep this tale for another session. For sure I have already abused of my audience.

[[Category:Tips and tricks]]
[[Category:Tips and tricks 1.5]]

[[Category:Tutorials]][[Category:Component Development]]

Absolute Basics of How a Component Functions

2011-02-08T22:09:06Z

Datashuttle:

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:

<source lang="php">
require_once(JPATH_COMPONENT.DS.'controller.php');
</source>

Your controller.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, being it windows or linux.

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

<source lang="php">
jimport('joomla.application.component.controller');
</source>

Now that you have controller.php included and the base JController class imported, you have to define a class that extends the JController base class. This is the class leg you wrote before about and 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:

<source lang="php">
class <name>Controller extends JController
{
}
</source>

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 these lines to your base file:

<source lang="php">
// Create the controller
$controller = new <name>Controller(); or whatever the name you gave your controller class

// Perform the Request task
$controller->execute(JRequest::getCmd('task'));
</source>

From this point on things start happening by themselves. Up to now you were able to name files, except for the base one, and put them where you wanted, and name classes like you wanted because you were including the files by path/name and calling your classes yourself. (Well, only one file and only one class actually, but you could do it!) From now on the Joomla! framework 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, because a single letter mismatch will make Joomla! fail.

Where does the Joomla! framework 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 this is the 'problem': Whether you pass or do not pass a full request, Joomla! will use its defaults to complete a request, making some errors difficult to spot.

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

<source lang="php">
class <name>Controller extends JController
{
function display()
{
echo 'displaying';
}
}
</source>

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:

<source lang="php">
class <name>Controller extends JController
{
function jump()
{
echo 'jumping';
}
}
</source>

Up to now you have delved with 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. Stopping here will, at least, simplify your base file over Joomla! 1.1.x . Up to version 1.5, components usually had a switch statement that, depending on the given task (or whatever passed variable), called a function with several arguments to deliver the HTML result.

With Joomla! 1.5, the switch is gone and your different tasks are methods in the controller.php file. Arguments are lost but all the needed variables are available from the framework 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 display() method of JController. Do this by inserting, in your method, a call to parent::display() as in the last line. At a minimum, your controller file should contain the following: (?Is this necessary? The display function should be pulled from the JController class that it is extending, right?)

<source lang="php">
jimport('joomla.application.component.controller');

class <name>Controller extends JController
{
function display()
{
parent::display();
}
}
</source>

'''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 of your views. This means that you have to create the views folder and now you could have something like in your disk:

<name> base folder
controller.php
<component_name>.php
'views' folder
view1
view2
...

Inside the views folder other folders hold the files that build each view. The Joomla! framework includes a file named view.html.php that should exist in your view directory. 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 better include it now because there is not such a thing like a default view. So your URL was something like:

http://example.com/index.php?option=com_<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 files 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 you are serving the view. There exist several well known formats such as html (the default one if none is specified), rss, etc. but 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! framework wrap the response in whatever template your site is using so that you get a fully built HTML page. This way, with very few effort from you side, you get back your page fully loaded with modules or whatever you had configured.

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.html.php'). If you use a different format like 'rss' your file should be named after it like view.rss.php. Get it?

As told 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

http://example.com/index.php?option=com_<name>&view=<myview>&format=ajax

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

Anyway, to achieve your goal you 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, that you should follow. 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_read&view=detail) your view class must be:

<source lang="php">
class TravelsViewDetail extends JView
{
function display($tpl=null)
{
echo 'blah, blah';
}
}
</source>

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 [x]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.

But you can go a bit further. 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. In this way the files that you must process can be very small and adjusted to the situation you are treating, 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.x).

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 in 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 you go with the 'default' layout. 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:

<source lang="php">
class <Name>View<Viewname> extends JView
{
function display($tpl=null)
{
// Prepare the data
$data1 = ....
$data2 = ....
$moredata[] = array....

// Inject the data
$this->assignRef('variablename', $data1);
$this->assignRef('variablename2', $data2);
$this->assignRef('variablename3', $moredata);

// Call the layout template
$tpl = 'myTemplate';
parent::display($tpl);

or more directly

parent::display('myTemplate');
}
}
</source>

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 [x]HTML *FINAL* code.

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, 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 apply fully the model but I think I will keep this tale for another session. For sure I have already abused of my audience.

[[Category:Tips and tricks]]
[[Category:Tips and tricks 1.5]]

[[Category:Tutorials]][[Category:Component Development]]

Absolute Basics of How a Component Functions

2011-02-08T22:05:35Z

Datashuttle:

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:

<source lang="php">
require_once(JPATH_COMPONENT.DS.'controller.php');
</source>

Your controller.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, being it windows or linux.

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

<source lang="php">
jimport('joomla.application.component.controller');
</source>

Now that you have controller.php included and the base JController class imported, you have to define a class that extends the JController base class. This is the class leg you wrote before about and 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:

<source lang="php">
class <name>Controller extends JController
{
}
</source>

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 these lines to your base file:

<source lang="php">
// Create the controller
$controller = new <name>Controller(); or whatever the name you gave your controller class

// Perform the Request task
$controller->execute(JRequest::getCmd('task'));
</source>

From this point on things start happening by themselves. Up to now you were able to name files, except for the base one, and put them where you wanted, and name classes like you wanted because you were including the files by path/name and calling your classes yourself. (Well, only one file and only one class actually, but you could do it!) From now on the Joomla! framework 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, because a single letter mismatch will make Joomla! fail.

Where does the Joomla! framework 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 this is the 'problem': Whether you pass or do not pass a full request, Joomla! will use its defaults to complete a request, making some errors difficult to spot.

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

<source lang="php">
class <name>Controller extends JController
{
function display()
{
echo 'displaying';
}
}
</source>

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:

<source lang="php">
class <name>Controller extends JController
{
function jump()
{
echo 'jumping';
}
}
</source>

Up to now you have delved with 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. Stopping here will, at least, simplify your base file over Joomla! 1.1.x . Up to version 1.5, components usually had a switch statement that, depending on the given task (or whatever passed variable), called a function with several arguments to deliver the HTML result.

With Joomla! 1.5, the switch is gone and your different tasks are methods in the controller.php file. Arguments are lost but all the needed variables are available from the framework 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 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 only have to call the display() method of JController. You do this by inserting in your method a call to parent::display() as the last line. At a minimum, your controller file should contain the following: (?Is this necessary? The display function should be pulled from the JController class that it is extending, right?)

<source lang="php">
jimport('joomla.application.component.controller');

class <name>Controller extends JController
{
function display()
{
parent::display();
}
}
</source>

'''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 of your views. This means that you have to create the views folder and now you could have something like in your disk:

<name> base folder
controller.php
<component_name>.php
'views' folder
view1
view2
...

Inside the views folder other folders hold the files that build each view. The Joomla! framework includes a file named view.html.php that should exist in your view directory. 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 better include it now because there is not such a thing like a default view. So your URL was something like:

http://example.com/index.php?option=com_<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 files 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 you are serving the view. There exist several well known formats such as html (the default one if none is specified), rss, etc. but 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! framework wrap the response in whatever template your site is using so that you get a fully built HTML page. This way, with very few effort from you side, you get back your page fully loaded with modules or whatever you had configured.

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.html.php'). If you use a different format like 'rss' your file should be named after it like view.rss.php. Get it?

As told 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

http://example.com/index.php?option=com_<name>&view=<myview>&format=ajax

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

Anyway, to achieve your goal you 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, that you should follow. 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_read&view=detail) your view class must be:

<source lang="php">
class TravelsViewDetail extends JView
{
function display($tpl=null)
{
echo 'blah, blah';
}
}
</source>

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 [x]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.

But you can go a bit further. 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. In this way the files that you must process can be very small and adjusted to the situation you are treating, 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.x).

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 in 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 you go with the 'default' layout. 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:

<source lang="php">
class <Name>View<Viewname> extends JView
{
function display($tpl=null)
{
// Prepare the data
$data1 = ....
$data2 = ....
$moredata[] = array....

// Inject the data
$this->assignRef('variablename', $data1);
$this->assignRef('variablename2', $data2);
$this->assignRef('variablename3', $moredata);

// Call the layout template
$tpl = 'myTemplate';
parent::display($tpl);

or more directly

parent::display('myTemplate');
}
}
</source>

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 [x]HTML *FINAL* code.

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, 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 apply fully the model but I think I will keep this tale for another session. For sure I have already abused of my audience.

[[Category:Tips and tricks]]
[[Category:Tips and tricks 1.5]]

[[Category:Tutorials]][[Category:Component Development]]

Absolute Basics of How a Component Functions

2011-02-08T22:03:29Z

Datashuttle:

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:

<source lang="php">
require_once(JPATH_COMPONENT.DS.'controller.php');
</source>

Your controller.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, being it windows or linux.

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

<source lang="php">
jimport('joomla.application.component.controller');
</source>

Now that you have controller.php included and the base JController class imported, you have to define a class that extends the JController base class. This is the class leg you wrote before about and 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:

<source lang="php">
class <name>Controller extends JController
{
}
</source>

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 these lines to your base file:

<source lang="php">
// Create the controller
$controller = new <name>Controller(); or whatever the name you gave your controller class

// Perform the Request task
$controller->execute(JRequest::getCmd('task'));
</source>

From this point on things start happening by themselves. Up to now you were able to name files, except for the base one, and put them where you wanted, and name classes like you wanted because you were including the files by path/name and calling your classes yourself. (Well, only one file and only one class actually, but you could do it!) From now on the Joomla! framework 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, because a single letter mismatch will make Joomla! fail.

Where does the Joomla! framework 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 this is the 'problem': Whether you pass or do not pass a full request, Joomla! will use its defaults to complete a request, making some errors difficult to spot.

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

<source lang="php">
class <name>Controller extends JController
{
function display()
{
echo 'displaying';
}
}
</source>

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:

<source lang="php">
class <name>Controller extends JController
{
function jump()
{
echo 'jumping';
}
}
</source>

Up to now you have delved with 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. Stopping here will, at least, simplify your base file over Joomla! 1.1.x . Up to version 1.5, components usually had a switch statement that, depending on the given task (or whatever passed variable), called a function with several arguments to deliver the HTML result.

With Joomla! 1.5, the switch is gone and your different tasks are functions in the controller.php file. Arguments are lost but all the needed variables are available from the framework 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 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 only have to call the display() method of JController. You do this by inserting in your method a call to parent::display() as the last line. At a minimum, your controller file should contain the following: (?Is this necessary? The display function should be pulled from the JController class that it is extending, right?)

<source lang="php">
jimport('joomla.application.component.controller');

class <name>Controller extends JController
{
function display()
{
parent::display();
}
}
</source>

'''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 of your views. This means that you have to create the views folder and now you could have something like in your disk:

<name> base folder
controller.php
<component_name>.php
'views' folder
view1
view2
...

Inside the views folder other folders hold the files that build each view. The Joomla! framework includes a file named view.html.php that should exist in your view directory. 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 better include it now because there is not such a thing like a default view. So your URL was something like:

http://example.com/index.php?option=com_<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 files 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 you are serving the view. There exist several well known formats such as html (the default one if none is specified), rss, etc. but 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! framework wrap the response in whatever template your site is using so that you get a fully built HTML page. This way, with very few effort from you side, you get back your page fully loaded with modules or whatever you had configured.

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.html.php'). If you use a different format like 'rss' your file should be named after it like view.rss.php. Get it?

As told 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

http://example.com/index.php?option=com_<name>&view=<myview>&format=ajax

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

Anyway, to achieve your goal you 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, that you should follow. 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_read&view=detail) your view class must be:

<source lang="php">
class TravelsViewDetail extends JView
{
function display($tpl=null)
{
echo 'blah, blah';
}
}
</source>

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 [x]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.

But you can go a bit further. 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. In this way the files that you must process can be very small and adjusted to the situation you are treating, 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.x).

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 in 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 you go with the 'default' layout. 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:

<source lang="php">
class <Name>View<Viewname> extends JView
{
function display($tpl=null)
{
// Prepare the data
$data1 = ....
$data2 = ....
$moredata[] = array....

// Inject the data
$this->assignRef('variablename', $data1);
$this->assignRef('variablename2', $data2);
$this->assignRef('variablename3', $moredata);

// Call the layout template
$tpl = 'myTemplate';
parent::display($tpl);

or more directly

parent::display('myTemplate');
}
}
</source>

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 [x]HTML *FINAL* code.

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, 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 apply fully the model but I think I will keep this tale for another session. For sure I have already abused of my audience.

[[Category:Tips and tricks]]
[[Category:Tips and tricks 1.5]]

[[Category:Tutorials]][[Category:Component Development]]

Absolute Basics of How a Component Functions

2011-02-08T21:51:33Z

Datashuttle:

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:

<source lang="php">
require_once(JPATH_COMPONENT.DS.'controller.php');
</source>

Your controller.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, being it windows or linux.

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

<source lang="php">
jimport('joomla.application.component.controller');
</source>

Now that you have controller.php included and the base JController class imported, you have to define a class that extends the JController base class. This is the class leg you wrote before about and 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:

<source lang="php">
class <name>Controller extends JController
{
}
</source>

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 these lines to your base file:

<source lang="php">
// Create the controller
$controller = new <name>Controller(); or whatever the name you gave your controller class

// Perform the Request task
$controller->execute(JRequest::getCmd('task'));
</source>

From this point on things start happening by themselves. Up to now you were able to name files, except for the base one, and put them where you wanted, and name classes like you wanted because you were including the files by path/name and calling your classes yourself. (Well, only one file and only one class actually, but you could do it!) From now on the Joomla! framework 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, because a single letter mismatch will make Joomla! fail.

Where does the Joomla! framework 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 this is the 'problem': Whether you pass or do not pass a full request, Joomla! will use its defaults to complete a request, making some errors difficult to spot.

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

<source lang="php">
class <name>Controller extends JController
{
function display()
{
echo 'displaying';
}
}
</source>

So that if your request contained a 'task=jump' parameter the controller would have tried to call a function named jump in your controller class:

<source lang="php">
class <name>Controller extends JController
{
function jump()
{
echo 'jumping';
}
}
</source>

Up to now you have delved with 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. Stopping here will, at least, simplify your base file over Joomla! 1.1.x . Up to version 1.5, components usually had a switch statement that, depending on the given task (or whatever passed variable), called a function with several arguments to deliver the HTML result.

With Joomla! 1.5, the switch is gone and your different tasks are functions in the controller.php file. Arguments are lost but all the needed variables are available from the framework 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 function call but 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 only have to call the display() function of JController. You do this by inserting in your function a call to parent::display() as the last line. At a minimum, your controller file should contain the following: (?Is this necessary? The display function should be pulled from the JController class that it is extending, right?)

<source lang="php">
jimport('joomla.application.component.controller');

class <name>Controller extends JController
{
function display()
{
parent::display();
}
}
</source>

'''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 of your views. This means that you have to create the views folder and now you could have something like in your disk:

<name> base folder
controller.php
<component_name>.php
'views' folder
view1
view2
...

Inside the views folder other folders hold the files that build each view. The Joomla! framework includes a file named view.html.php that should exist in your view directory. 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 better include it now because there is not such a thing like a default view. So your URL was something like:

http://example.com/index.php?option=com_<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 files 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 you are serving the view. There exist several well known formats such as html (the default one if none is specified), rss, etc. but 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! framework wrap the response in whatever template your site is using so that you get a fully built HTML page. This way, with very few effort from you side, you get back your page fully loaded with modules or whatever you had configured.

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.html.php'). If you use a different format like 'rss' your file should be named after it like view.rss.php. Get it?

As told 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

http://example.com/index.php?option=com_<name>&view=<myview>&format=ajax

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

Anyway, to achieve your goal you 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, that you should follow. 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_read&view=detail) your view class must be:

<source lang="php">
class TravelsViewDetail extends JView
{
function display($tpl=null)
{
echo 'blah, blah';
}
}
</source>

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 [x]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.

But you can go a bit further. 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. In this way the files that you must process can be very small and adjusted to the situation you are treating, 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.x).

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 in 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 you go with the 'default' layout. 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:

<source lang="php">
class <Name>View<Viewname> extends JView
{
function display($tpl=null)
{
// Prepare the data
$data1 = ....
$data2 = ....
$moredata[] = array....

// Inject the data
$this->assignRef('variablename', $data1);
$this->assignRef('variablename2', $data2);
$this->assignRef('variablename3', $moredata);

// Call the layout template
$tpl = 'myTemplate';
parent::display($tpl);

or more directly

parent::display('myTemplate');
}
}
</source>

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 [x]HTML *FINAL* code.

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, 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 apply fully the model but I think I will keep this tale for another session. For sure I have already abused of my audience.

[[Category:Tips and tricks]]
[[Category:Tips and tricks 1.5]]

[[Category:Tutorials]][[Category:Component Development]]

Absolute Basics of How a Component Functions

2011-02-08T21:49:37Z

Datashuttle:

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:

<source lang="php">
require_once(JPATH_COMPONENT.DS.'controller.php');
</source>

Your controller.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, being it windows or linux.

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

<source lang="php">
jimport('joomla.application.component.controller');
</source>

Now that you have controller.php included and the base JController class imported, you have to define a class that extends the JController base class. This is the class leg you wrote before about and 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:

<source lang="php">
class <name>Controller extends JController
{
}
</source>

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 these lines to your base file:

<source lang="php">
// Create the controller
$controller = new <name>Controller(); or whatever the name you gave your controller class

// Perform the Request task
$controller->execute(JRequest::getCmd('task'));
</source>

From this point on things start happening by themselves. Up to now you were able to name files, except for the base one, and put them where you wanted, and name classes like you wanted because you were including the files by path/name and calling your classes yourself. (Well, only one file and only one class actually, but you could do it!) From now on the Joomla! framework 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, because a single letter mismatch will make Joomla! fail.

Where does the Joomla! framework 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 this is the 'problem': Whether you pass or do not pass a full request, Joomla! will use its defaults to complete a request, making some errors difficult to spot.

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

<source lang="php">
class <name>Controller extends JController
{
function display()
{
echo 'displaying';
}
}
</source>

So that if your request contained a 'task=jump' parameter the controller would have tried to call a function named jump in your controller class:

<source lang="php">
class <name>Controller extends JController
{
function jump()
{
echo 'jumping';
}
}
</source>

Up to now you have delved with 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. Stopping here will, at least, simplify your base file over Joomla! 1.1.x . Up to version 1.5, components usually had a switch statement that, depending on the given task (or whatever passed variable), called a function with several arguments to deliver the HTML result.

With Joomla! 1.5, the switch is gone and your different tasks are functions in the controller.php file. Arguments are lost but all the needed variables are available from the framework 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 function call but 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 only have to call the display() function of JController. You do this by inserting in your function a call to parent::display() as the last line. At a minimum, your controller file should contain the following: (?Is this necessary? The display function should be pulled from the JController class that it is extending, right?)

<source lang="php">
jimport('joomla.application.component.controller');

class <name>Controller extends JController
{
function display()
{
parent::display();
}
}
</source>

'''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 of your views. This means that you have to create the views folder and now you could have something like in your disk:

<name> base folder
controller.php
<component_name>.php
'views' folder
view1
view2
...

Inside the views folder other folders hold the files that build each view. The Joomla! framework includes a file named view.html.php that should exist in your view directory. 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 better include it now because there is not such a thing like a default view. So your URL was something like:

http://example.com/index.php?option=com_<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 files 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 you are serving the view. There exist several well known formats such as html (the default one if none is specified), rss, etc. but 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! framework wrap the response in whatever template your site is using so that you get a fully built HTML page. This way, with very few effort from you side, you get back your page fully loaded with modules or whatever you had configured.

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.html.php'). If you use a different format like 'rss' your file should be named after it like view.rss.php. Get it?

As told 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

http://example.com/index.php?option=com_<name>&view=<myview>&format=ajax

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

Anyway, to achieve your goal you 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, that you should follow. 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_read&view=detail) your view class must be:

<source lang="php">
class TravelsViewDetail extends JView
{
function display($tpl=null)
{
echo 'blah, blah';
}
}
</source>

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 [x]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.

But you can go a bit further. 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. In this way the files that you must process can be very small and adjusted to the situation you are treating, 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.x).

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 in 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 you go with the 'default' layout. 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:

<source lang="php">
class <Name>View<Viewname> extends JView
{
function display($tpl=null)
{
// Prepare the data
$data1 = ....
$data2 = ....
$moredata[] = array....

// Inject the data
$this->assignRef('variablename', $data1);
$this->assignRef('variablename2', $data2);
$this->assignRef('variablename3', $moredata);

// Call the layout template
$tpl = 'myTemplate';
parent::display($tpl);

or more directly

parent::display('myTemplate');
}
}
</source>

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 [x]HTML *FINAL* code.

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, 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 apply fully the model but I think I will keep this tale for another session. For sure I have already abused of my audience.

[[Category:Tips and tricks]]
[[Category:Tips and tricks 1.5]]

[[Category:Tutorials]][[Category:Component Development]]

Absolute Basics of How a Component Functions

2011-02-08T21:47:45Z

Datashuttle:

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:

<source lang="php">
require_once(JPATH_COMPONENT.DS.'controller.php');
</source>

Your controller.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, being it windows or linux.

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

<source lang="php">
jimport('joomla.application.component.controller');
</source>

Now that you have controller.php included and the base JController class imported, you have to define a class that extends the JController base class. This is the class leg you wrote before about and 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:

<source lang="php">
class <name>Controller extends JController
{
}
</source>

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 these lines to your base file:

<source lang="php">
// Create the controller
$controller = new <name>Controller(); or whatever the name you gave your controller class

// Perform the Request task
$controller->execute(JRequest::getCmd('task'));
</source>

From this point on things start happening by themselves. Up to now you were able to name files, except for the base one, and put them where you wanted, and name classes like you wanted because you were including the files by path/name and calling your classes yourself. (Well, only one file and only one class actually, but you could do it!) From now on the Joomla! framework 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, because a single letter mismatch will make Joomla! fail.

Where does the Joomla! framework 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 this is the 'problem': Whether you pass or do not pass a full request, Joomla! will use its defaults to complete a request, making some errors difficult to spot.

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

<source lang="php">
class <name>Controller extends JController
{
function display()
{
echo 'displaying';
}
}
</source>

So that if your request contained a 'task=jump' parameter the controller would have tried to call a function named jump in your controller class:

<source lang="php">
class <name>Controller extends JController
{
function jump()
{
echo 'jumping';
}
}
</source>

Up to now you have delved with 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. Stopping here will, at least, simplify your base file over Joomla! 1.1.x . Up to version 1.5, components usually had a switch statement that, depending on the given task (or whatever passed variable), called a function with several arguments to deliver the HTML result.

With Joomla! 1.5, the switch is gone and your different tasks are functions in the controller.php file. Arguments are lost but all the needed variables are available from the framework 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 function call but 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 only have to call the display() function of JController. You do this by inserting in your function a call to parent::display() as the last line. At a minimum, your controller file should contain the following: (?Is this necessary? The display function should be pulled from the JController class that it is extending, right?)

<source lang="php">
jimport('joomla.application.component.controller');

class <name>Controller extends JController
{
function display()
{
parent::display();
}
}
</source>

'''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 of your views. This means that you have to create the views folder and now you could have something like in your disk:

<name> base folder
controller.php
<component_name>.php
'views' folder
view1
view2
...

Inside the views folder other folders hold the files that build each view. The Joomla! framework includes a file named view.html.php that should exist in your view directory. 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 better include it now because there is not such a thing like a default view. So your URL was something like:

http://example.com/index.php?option=com_<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 files 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 you are serving the view. There exist several well known formats such as html (the default one if none is specified), rss, etc. but 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! framework wrap the response in whatever template your site is using so that you get a fully built HTML page. This way, with very few effort from you side, you get back your page fully loaded with modules or whatever you had configured.

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.html.php'). If you use a different format like 'rss' your file should be named after it like view.rss.php. Get it?

As told 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

http://example.com/index.php?option=com_<name>&view=<myview>&format=ajax

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

Anyway, to achieve your goal you 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, that you should follow. 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_read&view=detail) your view class must be:

<source lang="php">
class TravelsViewDetail extends JView
{
function display($tpl=null)
{
echo 'blah, blah';
}
}
</source>

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 [x]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.

But you can go a bit further. 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. In this way the files that you must process can be very small and adjusted to the situation you are treating, 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.x).

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 in 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 you go with the 'default' layout. 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:

<source lang="php">
class <Name>View<Viewname> extends JView
{
function display($tpl=null)
{
// Prepare the data
$data1 = ....
$data2 = ....
$moredata[] = array....

// Inject the data
$this->assignRef('variablename', $data1);
$this->assignRef('variablename2', $data2);
$this->assignRef('variablename3', $moredata);

// Call the layout template
$tpl = 'myTemplate';
parent::display($tpl);

or more directly

parent::display('myTemplate');
}
}
</source>

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 [x]HTML *FINAL* code.

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, 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 apply fully the model but I think I will keep this tale for another session. For sure I have already abused of my audience.

[[Category:Tips and tricks]]
[[Category:Tips and tricks 1.5]]

[[Category:Tutorials]][[Category:Component Development]]

Absolute Basics of How a Component Functions

2011-02-08T21:44:32Z

Datashuttle:

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:

<source lang="php">
require_once(JPATH_COMPONENT.DS.'controller.php');
</source>

Your controller.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, being it windows or linux.

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

<source lang="php">
jimport('joomla.application.component.controller');
</source>

Now that you have controller.php included and the base JController class imported, you have to define a class that extends the JController base class. This is the class leg you wrote before about and 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:

<source lang="php">
class <name>Controller extends JController
{
}
</source>

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 these lines to your base file:

<source lang="php">
// Create the controller
$controller = new <name>Controller(); or whatever the name you gave your controller class

// Perform the Request task
$controller->execute(JRequest::getCmd('task'));
</source>

From this point on things start happening by themselves. Up to now you were able to name files, except for the base one, and put them where you wanted, and name classes like you wanted because you were including the files by path/name and calling your classes yourself. (Well, only one file and only one class actually, but you could do it!) From now on the Joomla! framework 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, because a single letter mismatch will make Joomla! fail.

Where does the Joomla! framework 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 this is the 'problem': Whether you pass or do not pass a full request, Joomla! will use its defaults to complete one making some errors difficult to spot.

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

<source lang="php">
class <name>Controller extends JController
{
function display()
{
echo 'displaying';
}
}
</source>

So that if your request contained a 'task=jump' parameter the controller would have tried to call a function named jump in your controller class:

<source lang="php">
class <name>Controller extends JController
{
function jump()
{
echo 'jumping';
}
}
</source>

Up to now you have delved with 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. Stopping here will, at least, simplify your base file over Joomla! 1.1.x . Up to version 1.5, components usually had a switch statement that, depending on the given task (or whatever passed variable), called a function with several arguments to deliver the HTML result.

With Joomla! 1.5, the switch is gone and your different tasks are functions in the controller.php file. Arguments are lost but all the needed variables are available from the framework 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 function call but 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 only have to call the display() function of JController. You do this by inserting in your function a call to parent::display() as the last line. At a minimum, your controller file should contain the following: (?Is this necessary? The display function should be pulled from the JController class that it is extending, right?)

<source lang="php">
jimport('joomla.application.component.controller');

class <name>Controller extends JController
{
function display()
{
parent::display();
}
}
</source>

'''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 of your views. This means that you have to create the views folder and now you could have something like in your disk:

<name> base folder
controller.php
<component_name>.php
'views' folder
view1
view2
...

Inside the views folder other folders hold the files that build each view. The Joomla! framework includes a file named view.html.php that should exist in your view directory. 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 better include it now because there is not such a thing like a default view. So your URL was something like:

http://example.com/index.php?option=com_<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 files 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 you are serving the view. There exist several well known formats such as html (the default one if none is specified), rss, etc. but 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! framework wrap the response in whatever template your site is using so that you get a fully built HTML page. This way, with very few effort from you side, you get back your page fully loaded with modules or whatever you had configured.

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.html.php'). If you use a different format like 'rss' your file should be named after it like view.rss.php. Get it?

As told 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

http://example.com/index.php?option=com_<name>&view=<myview>&format=ajax

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

Anyway, to achieve your goal you 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, that you should follow. 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_read&view=detail) your view class must be:

<source lang="php">
class TravelsViewDetail extends JView
{
function display($tpl=null)
{
echo 'blah, blah';
}
}
</source>

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 [x]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.

But you can go a bit further. 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. In this way the files that you must process can be very small and adjusted to the situation you are treating, 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.x).

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 in 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 you go with the 'default' layout. 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:

<source lang="php">
class <Name>View<Viewname> extends JView
{
function display($tpl=null)
{
// Prepare the data
$data1 = ....
$data2 = ....
$moredata[] = array....

// Inject the data
$this->assignRef('variablename', $data1);
$this->assignRef('variablename2', $data2);
$this->assignRef('variablename3', $moredata);

// Call the layout template
$tpl = 'myTemplate';
parent::display($tpl);

or more directly

parent::display('myTemplate');
}
}
</source>

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 [x]HTML *FINAL* code.

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, 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 apply fully the model but I think I will keep this tale for another session. For sure I have already abused of my audience.

[[Category:Tips and tricks]]
[[Category:Tips and tricks 1.5]]

[[Category:Tutorials]][[Category:Component Development]]

Absolute Basics of How a Component Functions

2011-02-08T21:43:46Z

Datashuttle:

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:

<source lang="php">
require_once(JPATH_COMPONENT.DS.'controller.php');
</source>

Your controller.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, being it windows or linux.

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

<source lang="php">
jimport('joomla.application.component.controller');
</source>

Now that you have controller.php included and the base JController class imported, you have to define a class that extends the JController base class. This is the class leg you wrote before about and 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:

<source lang="php">
class <name>Controller extends JController
{
}
</source>

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 these lines to your base file:

<source lang="php">
// Create the controller
$controller = new <name>Controller(); or whatever the name you gave your controller class

// Perform the Request task
$controller->execute(JRequest::getCmd('task'));
</source>

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

Where does the Joomla! framework 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 this is the 'problem': Whether you pass or do not pass a full request, Joomla! will use its defaults to complete one making some errors difficult to spot.

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

<source lang="php">
class <name>Controller extends JController
{
function display()
{
echo 'displaying';
}
}
</source>

So that if your request contained a 'task=jump' parameter the controller would have tried to call a function named jump in your controller class:

<source lang="php">
class <name>Controller extends JController
{
function jump()
{
echo 'jumping';
}
}
</source>

Up to now you have delved with 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. Stopping here will, at least, simplify your base file over Joomla! 1.1.x . Up to version 1.5, components usually had a switch statement that, depending on the given task (or whatever passed variable), called a function with several arguments to deliver the HTML result.

With Joomla! 1.5, the switch is gone and your different tasks are functions in the controller.php file. Arguments are lost but all the needed variables are available from the framework 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 function call but 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 only have to call the display() function of JController. You do this by inserting in your function a call to parent::display() as the last line. At a minimum, your controller file should contain the following: (?Is this necessary? The display function should be pulled from the JController class that it is extending, right?)

<source lang="php">
jimport('joomla.application.component.controller');

class <name>Controller extends JController
{
function display()
{
parent::display();
}
}
</source>

'''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 of your views. This means that you have to create the views folder and now you could have something like in your disk:

<name> base folder
controller.php
<component_name>.php
'views' folder
view1
view2
...

Inside the views folder other folders hold the files that build each view. The Joomla! framework includes a file named view.html.php that should exist in your view directory. 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 better include it now because there is not such a thing like a default view. So your URL was something like:

http://example.com/index.php?option=com_<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 files 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 you are serving the view. There exist several well known formats such as html (the default one if none is specified), rss, etc. but 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! framework wrap the response in whatever template your site is using so that you get a fully built HTML page. This way, with very few effort from you side, you get back your page fully loaded with modules or whatever you had configured.

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.html.php'). If you use a different format like 'rss' your file should be named after it like view.rss.php. Get it?

As told 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

http://example.com/index.php?option=com_<name>&view=<myview>&format=ajax

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

Anyway, to achieve your goal you 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, that you should follow. 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_read&view=detail) your view class must be:

<source lang="php">
class TravelsViewDetail extends JView
{
function display($tpl=null)
{
echo 'blah, blah';
}
}
</source>

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 [x]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.

But you can go a bit further. 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. In this way the files that you must process can be very small and adjusted to the situation you are treating, 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.x).

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 in 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 you go with the 'default' layout. 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:

<source lang="php">
class <Name>View<Viewname> extends JView
{
function display($tpl=null)
{
// Prepare the data
$data1 = ....
$data2 = ....
$moredata[] = array....

// Inject the data
$this->assignRef('variablename', $data1);
$this->assignRef('variablename2', $data2);
$this->assignRef('variablename3', $moredata);

// Call the layout template
$tpl = 'myTemplate';
parent::display($tpl);

or more directly

parent::display('myTemplate');
}
}
</source>

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 [x]HTML *FINAL* code.

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, 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 apply fully the model but I think I will keep this tale for another session. For sure I have already abused of my audience.

[[Category:Tips and tricks]]
[[Category:Tips and tricks 1.5]]

[[Category:Tutorials]][[Category:Component Development]]

Absolute Basics of How a Component Functions

2011-02-08T21:43:14Z

Datashuttle:

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:

<source lang="php">
require_once(JPATH_COMPONENT.DS.'controller.php');
</source>

Your controller.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, being it windows or linux.

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

<source lang="php">
jimport('joomla.application.component.controller');
</source>

Now that you have controller.php included and the base JController class imported, you have to define a class that extends the JController base class. This is the class leg you wrote before about and 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:

<source lang="php">
class <name>Controller extends JController
{
}
</source>

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 these lines to your base file:

<source lang="php">
// Create the controller
$controller = new <name>Controller(); or whatever the name you gave your controller class

// Perform the Request task
$controller->execute(JRequest::getCmd('task'));
</source>

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

Where does the Joomla! framework 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 this is the 'problem': Whether you pass or do not pass a full request, Joomla! will use its defaults to complete one making some errors difficult to spot.

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

<source lang="php">
class <name>Controller extends JController
{
function display()
{
echo 'displaying';
}
}
</source>

So that if your request contained a 'task=jump' parameter the controller would have tried to call a function named jump in your controller class:

<source lang="php">
class <name>Controller extends JController
{
function jump()
{
echo 'jumping';
}
}
</source>

Up to now you have delved with 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. Stopping here will, at least, simplify your base file over Joomla! 1.1.x . Up to version 1.5, components usually had a switch statement that, depending on the given task (or whatever passed variable), called a function with several arguments to deliver the HTML result.

With Joomla! 1.5, the switch is gone and your different tasks are functions in the controller.php file. Arguments are lost but all the needed variables are available from the framework 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 function call but 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 only have to call the display() function of JController. You do this by inserting in your function a call to parent::display() as the last line. At a minimum, your controller file should contain the following: (?Is this necessary? The display function should be pulled from the JController class that it is extending, right?)

<source lang="php">
jimport('joomla.application.component.controller');

class <name>Controller extends JController
{
function display()
{
parent::display();
}
}
</source>

'''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 of your views. This means that you have to create the views folder and now you could have something like in your disk:

<name> base folder
controller.php
<component_name>.php
'views' folder
view1
view2
...

Inside the views folder other folders hold the files that build each view. The Joomla! framework includes a file named view.html.php that should exist in your view directory. 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 better include it now because there is not such a thing like a default view. So your URL was something like:

http://example.com/index.php?option=com_<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 files 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 you are serving the view. There exist several well known formats such as html (the default one if none is specified), rss, etc. but 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! framework wrap the response in whatever template your site is using so that you get a fully built HTML page. This way, with very few effort from you side, you get back your page fully loaded with modules or whatever you had configured.

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.html.php'). If you use a different format like 'rss' your file should be named after it like view.rss.php. Get it?

As told 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

http://example.com/index.php?option=com_<name>&view=<myview>&format=ajax

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

Anyway, to achieve your goal you 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, that you should follow. 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_read&view=detail) your view class must be:

<source lang="php">
class TravelsViewDetail extends JView
{
function display($tpl=null)
{
echo 'blah, blah';
}
}
</source>

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 [x]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.

But you can go a bit further. 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. In this way the files that you must process can be very small and adjusted to the situation you are treating, 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.x).

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 in 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 you go with the 'default' layout. 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:

<source lang="php">
class <Name>View<Viewname> extends JView
{
function display($tpl=null)
{
// Prepare the data
$data1 = ....
$data2 = ....
$moredata[] = array....

// Inject the data
$this->assignRef('variablename', $data1);
$this->assignRef('variablename2', $data2);
$this->assignRef('variablename3', $moredata);

// Call the layout template
$tpl = 'myTemplate';
parent::display($tpl);

or more directly

parent::display('myTemplate');
}
}
</source>

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 [x]HTML *FINAL* code.

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, 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 apply fully the model but I think I will keep this tale for another session. For sure I have already abused of my audience.

[[Category:Tips and tricks]]
[[Category:Tips and tricks 1.5]]

[[Category:Tutorials]][[Category:Component Development]]

Absolute Basics of How a Component Functions

2011-02-08T21:40:31Z

Datashuttle:

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:

<source lang="php">
require_once(JPATH_COMPONENT.DS.'controller.php');
</source>

Your controller.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, being it windows or linux.

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

<source lang="php">
jimport('joomla.application.component.controller');
</source>

Now that you have controller.php included and the base JController class imported, you have to define a class that extends the JController base class. This is the class leg you wrote before about and 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:

<source lang="php">
class <name>Controller extends JController
{
}
</source>

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 these lines to your base file:

<source lang="php">
// Create the controller
$controller = new <name>Controller(); or whatever the name you gave your controller class

// Perform the Request task
$controller->execute(JRequest::getCmd('task'));
</source>

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

Where does the Joomla! framework 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 comes from? Do you really have a meaningful 'task' variable?

Yes, and this is the 'problem': Whether you pass or do not pass a full request, Joomla! will use its defaults to complete one making some errors difficult to spot.

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

<source lang="php">
class <name>Controller extends JController
{
function display()
{
echo 'displaying';
}
}
</source>

So that if your request contained a 'task=jump' parameter the controller would have tried to call a function named jump in your controller class:

<source lang="php">
class <name>Controller extends JController
{
function jump()
{
echo 'jumping';
}
}
</source>

Up to now you have delved with 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. Stopping here will, at least, simplify your base file over Joomla! 1.1.x . Up to version 1.5, components usually had a switch statement that, depending on the given task (or whatever passed variable), called a function with several arguments to deliver the HTML result.

With Joomla! 1.5, the switch is gone and your different tasks are functions in the controller.php file. Arguments are lost but all the needed variables are available from the framework 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 function call but 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 only have to call the display() function of JController. You do this by inserting in your function a call to parent::display() as the last line. At a minimum, your controller file should contain the following: (?Is this necessary? The display function should be pulled from the JController class that it is extending, right?)

<source lang="php">
jimport('joomla.application.component.controller');

class <name>Controller extends JController
{
function display()
{
parent::display();
}
}
</source>

'''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 of your views. This means that you have to create the views folder and now you could have something like in your disk:

<name> base folder
controller.php
<component_name>.php
'views' folder
view1
view2
...

Inside the views folder other folders hold the files that build each view. The Joomla! framework includes a file named view.html.php that should exist in your view directory. 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 better include it now because there is not such a thing like a default view. So your URL was something like:

http://example.com/index.php?option=com_<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 files 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 you are serving the view. There exist several well known formats such as html (the default one if none is specified), rss, etc. but 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! framework wrap the response in whatever template your site is using so that you get a fully built HTML page. This way, with very few effort from you side, you get back your page fully loaded with modules or whatever you had configured.

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.html.php'). If you use a different format like 'rss' your file should be named after it like view.rss.php. Get it?

As told 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

http://example.com/index.php?option=com_<name>&view=<myview>&format=ajax

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

Anyway, to achieve your goal you 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, that you should follow. 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_read&view=detail) your view class must be:

<source lang="php">
class TravelsViewDetail extends JView
{
function display($tpl=null)
{
echo 'blah, blah';
}
}
</source>

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 [x]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.

But you can go a bit further. 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. In this way the files that you must process can be very small and adjusted to the situation you are treating, 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.x).

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 in 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 you go with the 'default' layout. 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:

<source lang="php">
class <Name>View<Viewname> extends JView
{
function display($tpl=null)
{
// Prepare the data
$data1 = ....
$data2 = ....
$moredata[] = array....

// Inject the data
$this->assignRef('variablename', $data1);
$this->assignRef('variablename2', $data2);
$this->assignRef('variablename3', $moredata);

// Call the layout template
$tpl = 'myTemplate';
parent::display($tpl);

or more directly

parent::display('myTemplate');
}
}
</source>

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 [x]HTML *FINAL* code.

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, 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 apply fully the model but I think I will keep this tale for another session. For sure I have already abused of my audience.

[[Category:Tips and tricks]]
[[Category:Tips and tricks 1.5]]

[[Category:Tutorials]][[Category:Component Development]]

Absolute Basics of How a Component Functions

2011-02-08T20:08:30Z

Datashuttle: Changed some of the wording to be consistant with second-person narrative

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:

<source lang="php">
require_once(JPATH_COMPONENT.DS.'controller.php');
</source>

Your controller.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, being it windows or linux.

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

<source lang="php">
jimport('joomla.application.component.controller');
</source>

Now that you have controller.php included and the base JController class imported, you have to define a class that extends the JController base class. This is the class leg you wrote before about and 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:

<source lang="php">
class <name>Controller extends JController
{
}
</source>

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 these lines to your base file:

<source lang="php">
// Create the controller
$controller = new <name>Controller(); or whatever the name you gave your controller class

// Perform the Request task
$controller->execute(JRequest::getCmd('task'));
</source>

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

Where does the Joomla! framework 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 comes from? Do you really have a meaningful 'task' variable?

Yes, and this is the 'problem': Whether you pass or do not pass a full request, Joomla! will use its defaults to complete one making some errors difficult to spot.

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

<source lang="php">
class <name>Controller extends JController
{
function display()
{
echo 'displaying';
}
}
</source>

So that if your request contained a 'task=jump' parameter the controller would have tried to call a function named jump in your controller class:

<source lang="php">
class <name>Controller extends JController
{
function jump()
{
echo 'jumping';
}
}
</source>

Up to now you have delved with 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. Stopping here will, at least, simplify your base file over Joomla! 1.1.x . Up to version 1.5, components usually had a switch statement that, depending on the given task (or whatever passed variable), called a function with several arguments to deliver the HTML result.

With Joomla! 1.5, the switch is gone and your different tasks are functions in the controller.php file. Arguments are lost but all the needed variables are available from the framework 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 function call but 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 only have to call the display() function of JController. You do this by inserting in your function a call to parent::display() as the last line. At a minimum, your controller file should contain the following: (?Is this necessary? The display function should be pulled from the JController class that it is extending, right?)

<source lang="php">
jimport('joomla.application.component.controller');

class <name>Controller extends JController
{
function display()
{
parent::display();
}
}
</source>

'''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 of your views. This means that you have to create the views folder and now you could have something like in your disk:

<name> base folder
controller.php
<component_name>.php
'views' folder
view1
view2
...

Inside the views folder other folders hold the files that build each view. The Joomla! framework includes a file named view.html.php that should exist in your view directory. 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 better include it now because there is not such a thing like a default view. So your URL was something like:

http://example.com/index.php?option=com_<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 files 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 you are serving the view. There exist several well known formats such as html (the default one if none is specified), rss, etc. but 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! framework wrap the response in whatever template your site is using so that you get a fully built HTML page. This way, with very few effort from you side, you get back your page fully loaded with modules or whatever you had configured.

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.html.php'). If you use a different format like 'rss' your file should be named after it like view.rss.php. Get it?

As told 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

http://example.com/index.php?option=com_<name>&view=<myview>&format=ajax

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

Anyway, to achieve your goal you 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, that you should follow. 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_read&view=detail) your view class must be:

<source lang="php">
class TravelsViewDetail extends JView
{
function display($tpl=null)
{
echo 'blah, blah';
}
}
</source>

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 [x]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.

But you can go a bit further. 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. In this way the files that you must process can be very small and adjusted to the situation you are treating, 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.x).

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 in 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 you go with the 'default' layout. 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:

<source lang="php">
class <Name>View<Viewname> extends JView
{
function display($tpl=null)
{
// Prepare the data
$data1 = ....
$data2 = ....
$moredata[] = array....

// Inject the data
$this->assignRef('variablename', $data1);
$this->assignRef('variablename2', $data2);
$this->assignRef('variablename3', $moredata);

// Call the layout template
$tpl = 'myTemplate';
parent::display($tpl);

or more directly

parent::display('myTemplate');
}
}
</source>

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 [x]HTML *FINAL* code.

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, 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 apply fully the model but I think I will keep this tale for another session. For sure I have already abused of my audience.

[[Category:Tips and tricks]]
[[Category:Tips and tricks 1.5]]

[[Category:Tutorials]][[Category:Component Development]]

Absolute Basics of How a Component Functions

2011-02-08T19:44:18Z

Datashuttle: Changed word from this to these

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:

<source lang="php">
require_once(JPATH_COMPONENT.DS.'controller.php');
</source>

Your controller.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, being it windows or linux.

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

<source lang="php">
jimport('joomla.application.component.controller');
</source>

Now that we have controller.php included and the base JController class imported, we have to define a class that extend the JController base class. This is the class leg we wrote before about and it is here where our action will happen. You can name this class as you like but, by convention, it is named after your component so you write:

<source lang="php">
class <name>Controller extends JController
{
}
</source>

In this stage we have our 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. Our next step is to create an object of this class and to put it to work. So we add these lines to our base file:

<source lang="php">
// Create the controller
$controller = new <name>Controller(); or whatever the name you gave your controller class

// Perform the Request task
$controller->execute(JRequest::getCmd('task'));
</source>

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

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

Yes, and this is the 'problem': Whether you pass or do not pass a full request, Joomla! will use its defaults to complete one making some errors difficult to spot.

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

<source lang="php">
class <name>Controller extends JController
{
function display()
{
echo 'displaying';
}
}
</source>

So that if your request contained a 'task=jump' parameter the controller would have tried to call a function named jump in your controller class:

<source lang="php">
class <name>Controller extends JController
{
function jump()
{
echo 'jumping';
}
}
</source>

Up to now we have delved with the controller part of the model. This is a new point of decision. We can stop here or we can go a step further and enter the view part of it. Stopping here will, at least, simplify your base file over Joomla! 1.1.x . Up to version 1.5, components usually had a switch statement that, depending on the given task (or whatever passed variable), called a function with several arguments to deliver the HTML result.

With Joomla! 1.5, the switch is gone and our different tasks are functions in the controller.php file. Arguments are lost but all the needed variables are available from the framework so we will be able to retrieve them easily.

There is nothing that forces us to use the 'task' variable to drive the call because we can pass the value of any variable as the parameter to the execute function call but 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 we only have to call the display() function of JController. We do this by inserting in our function a call to parent::display() as the last line. At the minimum our controller file should contain the following: (?Is this necessary? The display function should be pulled from the JController class that it is extending, right?)

<source lang="php">
jimport('joomla.application.component.controller');

class <name>Controller extends JController
{
function display()
{
parent::display();
}
}
</source>

'''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 of your views. This means that you have to create the views folder and now you could have something like in your disk:

<name> base folder
controller.php
<component_name>.php
'views' folder
view1
view2
...

Inside the views folder other folders hold the files that build each view. The Joomla! framework includes a file named view.html.php that should exist in your view directory. 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 better include it now because there is not such a thing like a default view. So your URL was something like:

http://example.com/index.php?option=com_<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 files 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 you are serving the view. There exist several well known formats such as html (the default one if none is specified), rss, etc. but 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! framework wrap the response in whatever template your site is using so that you get a fully built HTML page. This way, with very few effort from you side, you get back your page fully loaded with modules or whatever you had configured.

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.html.php'). If you use a different format like 'rss' your file should be named after it like view.rss.php. Get it?

As told before, you can have other formats 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

http://example.com/index.php?option=com_<name>&view=<myview>&format=ajax

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

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

<source lang="php">
class TravelsViewDetail extends JView
{
function display($tpl=null)
{
echo 'blah, blah';
}
}
</source>

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 [x]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 respond. Where does the display function come from? Again, I don't know. Hope that someone else can help here.

But we can go a bit further. Up to this point we have a distributed framework that dissects our request in such a way that allow us to create small and very specific files to react only to specific types of requests. In this way the files that we must process can be very small and adjusted to the situation we are treating, 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.x).

Having reached this point we can dissect a bit more and have another layer of detail: the final layout for the data we 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 in 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 you go with the 'default' layout. 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:

<source lang="php">
class <Name>View<Viewname> extends JView
{
function display($tpl=null)
{
// Prepare the data
$data1 = ....
$data2 = ....
$moredata[] = array....

// Inject the data
$this->assignRef('variablename', $data1);
$this->assignRef('variablename2', $data2);
$this->assignRef('variablename3', $moredata);

// Call the layout template
$tpl = 'myTemplate';
parent::display($tpl);

or more directly

parent::display('myTemplate');
}
}
</source>

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 [x]HTML *FINAL* code.

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, small, very specific files.

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

[[Category:Tips and tricks]]
[[Category:Tips and tricks 1.5]]

[[Category:Tutorials]][[Category:Component Development]]

Chunk:Framework (CMS 1.5 and 1.6)

2011-02-04T13:40:09Z

Datashuttle: Removed the word "its" in the second paragraph

__NOTOC__
[[Image:Joomla_Architecture.jpg|thumb|The Joomla Architecture]]

The Joomla Framework is an important part of the Joomla architecture. It's based on modern object-oriented design patterns that make the Joomla core highly maintainable and easily extendable ([[About the Joomla Framework|Learn more about the Joomla Framework]]).

Third party developers benefit from the rich, and easily accessible functionality that the Joomla Framework provides. On this page we'd like to provide you a reference of all classes and respective methods. The links will take you to further information about each class including, where possible, examples of use.

If you would like to help us improve this resource, please read [[API Reference Project]].

J1.5:Component parameters

2011-02-03T22:57:28Z

Datashuttle: /* 2. Menu item specific parameters */ Added missing word to second paragraph.

==Background==
One thing that sets Joomla! Components apart from other types of Extension (i.e. Modules and Plugins) is the ability to store significant quantities of data in the Joomla! MySQL database. Typically, this data will be content for displaying on a page (such as the content of an article, or its title) or data about how that content should be displayed (e.g. a setting specifying whether or not the title should be shown). A Component normally creates at least one table in the database to store this data - for example, data for articles associated with the <code>com_content</code> Component are stored in the <code>jos_content</code> table (where ''jos'' is the table prefix for the site).

However, choosing exactly how to store each item of data requires a little more thought. There are essentially two choices: each data item may be stored in its own field, or a collection of data items may be stored within a single parameters field. (Of course, there is nothing to stop you making use of both methods, for different data items, within the same component). Which approach you use for a given data item is largely a matter of personal choice, although there are some factors to consider:
* Core code included in the Joomla! installation makes it very easy to produce the appropriate form elements for entering data into '''parameters''' in the Back-end. If you choose to save the data in separate fields, you will need to code the appropriate form elements yourself.
* Again, Joomla! core code allows you to set default values for '''parameters''' across the whole component. Individual component items (e.g. individual articles) can then choose to use the default values, or to override them with values specific to that item. See below for details of how to do this.
* It is not possible to extract individual parameter values directly from the database. Instead, the whole parameters field must be extracted and parsed to obtain the different parameter values. This means that it is not very easy, for example, to run MySQL queries that search for a parameter with a particular value. Any data that you want to run queries against should be given its '''own table field'''.
* Similarly, it is not possible to run data validation on parameter fields before saving data.
In general, parameters are conventionally used to store data relating to the ''presentation'' of information. The information itself is generally stored in separate fields.

==Types of Component parameter==

===1. Component-wide default parameters===

These parameters are set once for the whole Component, and are generally used to provide the 'default' parameter settings for the Component on that particular site.

===2. Menu item specific parameters===

A menu link to an individual Component item (e.g. an article) can also have parameters associated with it, which can affect the way the Component item is displayed ''using that link''. The types of parameters available will depend on the way that the Component item is displayed (the 'view' in MVC terms, but don't worry if this doesn't mean anything to you!). However, the precise values of those parameters can be set for each menu link individually. If there is another menu link to that same Component item, then it is important to realise each menu link may have different parameter values, and so the same article may be displayed differently in the two cases.

A menu link can also override the Component-wide default parameters, so that the override values (if set) are used in place of the default values ''for that Component item when accessed via that menu link''. As you would expect, when no override value is set, the default value is used instead, in the normal manner.

===3. 'Article' specific parameters===

Finally, each Component item (e.g. article) can have parameters which apply to that item, regardless of how it is accessed (i.e. via any available menu link, or even without reference to a menu at all!). If the Component designer wants, the article specific parameters can also be set up to use the 'override' behaviour, so that they default to the current values of the corresponding Component-wide parameters, though this is not essential. Again, this is described further below.

==Storing the parameters and their values.==

In general, a set of parameters is stored within the database in a single <code>text</code> field. Different parameters are separated by <code>newline</code> characters ('<code>\n</code>' in MySQL - each parameter will appear on a different line when you look at the data in something like phpMyAdmin). Each parameter consists of the parameter name and value, separated by an equals sign (=). As an example:

<source lang="text">
parameter1=parameter1value
parameter2=
parameter3=parameter3value
parameter4=parameter4value
</source>

Here, parameter1, parameter3, and parameter4 have all been assigned values, whilst parameter2 has no value. Typically, a parameter will be given no value where it is set up to allow override of a default value, but 'no override is required' - i.e. it is desired to use the default value.

===1. Component-wide default parameters===

These are stored in the <code>params</code> field of the jos_components table, in the row corresponding to the particular component to which they apply.

===2. Menu item specific parameters===

These are stored in the <code>params</code> field of the jos_menu table, in the row corresponding to the particular menu item to which they apply.

===3. 'Article' specific parameters===

These are stored in a text field in the table created by the Component. Whilst there is no strict rule for naming the field, it is common to extend the above pattern using the <code>params</code> name. However, com_content stores article parameters in a field called <code>attribs</code>.

==Accessing the parameters - Back-end==

Joomla! includes some shortcuts to enable component creators to easily add parameter forms to the Back-end of their component. These forms allow a site administrator to enter a parameter value by, for example, entering some text in a box, choosing from a drop-down list, or selecting a radio button. To create these forms, each parameter needs to have an associated <code><param /></code> object in an XML file. The type of <code><nowiki><param /></nowiki></code> object determines the form elements that will be shown in the Back-end. A list of the available form elements is given [[Standard_parameter_types|here]]. More information is given below about the XML file names, structure and location required for each set of parameters.

===1. Component-wide default parameters===

These can be created at installation of the Component, by including <code><param /></code> elements in the installation XML file (typically called COMPONENT_NAME.xml, and located in the root folder of the Component package. As far as the parameters are concerned, this XML file has the following structure:
<source lang="xml">
<install>
...
<params>
<param />


<param name="font_size" default="16" />

...
</params>
<url addpath="....">
<param />
</url>
...
</install>
</source>
Each <code><param /></code> element must be given the attributes <code>name</code> and <code>default</code>, which define the parameter name and value respectively. These values are then copied to the jos_components table in the database.

However, on its own this is not very useful, as it doesn't allow users to change the values of the parameters. To do this, parameter form elements need to be defined in a file named <code>config.xml</code> which is located in <code>/PATH_TO_JOOMLA/administrator/components/com_COMPONENT_NAME/</code>. The file should have the following structure:
<source lang="xml">
<root>
<params>
<url addpath="/administrator/components/com_COMPONENT_NAME/elements">
<param name="cid" type="JELEMENT_TYPE_NAME" scope="com_COMPONENT_NAME" default="0" label="LABEL" description="DESCRIPTION" />
</url>
<param type="type" name="name" description="description" />



<param type="text" name="font_size" size="3" label="Font size:" description="Please enter the required font size" />

...
</params>
</root>
</source>
Note that the <code><root></code> element can have any name you wish, but there must be one element at the root of the document (this is a requirement for a well-formed XML document). You can have more than one <code><params></code> element, but only the first one will be considered. It is not currently possible to group certain parameter form elements together.

The <code><url></code> section contains parameters which are added to the URL of the menu item. To enable this functionality, the <code>type</code> attribute of the <code><param></code> elements must specify the name of a class which extends JElement, and is able to generate HTML forms to display and set the parameter. You can use one of the [[Standard parameter types]]. Or, you can create your own subclass of JElement. Put the class definition file in your component's <code>/administrator/components/com_COMPONENT_NAME/</code> directory, and refer to this path in the <code>addpath</code> attribute of the <code><URL></code> element. More information here: http://forum.joomla.org/viewtopic.php?f=476&t=206062.

So that administrators to access these parameters, you will need to add a button to the toolbar in the Back-end of your component. This can be done using the code:
<source lang="php">
JToolBarHelper::preferences( 'com_COMPONENT_NAME' );
// e.g. for the core Content component, you would use JToolBarHelper::preferences( 'com_content' );
</source>
which is typically placed in the PHP file responsible for the Back-end output. (For example, using an MVC structure, you might place this code at the top of <code>/PATH_TO_JOOMLA/administrator/components/com_COMPONENT_NAME/views/VIEW_NAME/tmpl/default.php</code>.

This adds a <code>Parameters</code> button to the toolbar:

[[Image:Toolbar_newsfeed.png]]

Clicking on the toolbar button produces a pop-up window containing the form fields for each parameter defined in <code>config.xml</code>.

Note that there is no need to define <code>default</code> attributes for the <code><param /></code> elements in the <code>config.xml</code> file, since the default values will already have been saved in the installation of the Component.

===2. Menu item specific parameters===

A menu item is associated with a particular view from your Component's Front-end - following the menu link in the Front-end will display that view. Joomla! 1.5 allows you to define parameters for a particular view, so that a copy of those parameters can be associated with each menu item using the view. In addition, you can also choose to override the Component-wide default parameters defined as above, so that the override values will apply to the particular menu item.

The view parameters are defined in an XML file stored in the ''Front-end'' view output template directory. (This is not to be confused with the site Template directory, which is different!). The XML file has the same name as the layout used with the template. For most applications you will be using the default layout. Thus the path to the XML file is something like: <code>/PATH_TO_JOOMLA/components/com_COMPONENT_NAME/views/VIEW_NAME/tmpl/default.xml</code>. The structure of the file is:
<source lang="xml">
<metadata>
...
<state>
...
<params>
<param />
...
</params>
<url>
<param />
...
</url>
<advanced>
<param />
...
</advanced>
</state>
</metadata>
</source>

See [[Standard parameter types]] for a full list of the core parameter types. (You can use these types within a <code><url></code> section without needing to supply an <code>addpath</code> attribute.)

Displaying the forms for these parameters is handled automatically by the core <code>com_menus</code> component, which creates a number of slider panes on the right hand side (at least when viewed using the default Khepri backend site Template) of the menu item edit screen. Any parameters defined within the <code><params></code> or <code><url></code> tags will appear in the <code>Parameters - Basic</code> slider pane. Any parameters defined within the <code><advanced></code> tag will appear in the <code>Parameters - Advanced</code> slider pane.

The following screenshot shows the menu admin page for the Category 'List' layout. You can see that the <code>Parameters - Basic</code> slider pane is open, and contains form elements for five parameters. There are no 'Advanced' parameters for this view, and so the <code>Parameters - Advanced</code> slider pane is not shown:

[[Image:Menu items edit.png]]

For the override of the Component-wide default parameters, <code>com_menus</code> uses the same <code>config.xml</code> file as above, so there is no need to define these parameters again. The override forms are automatically added to a slider pane named <code>Parameters - Component</code>. However, there are a number of changes from the forms used in the Preferences pop-up window (despite being based on the same <code>config.xml</code> file):
* Any <code><param type="radio" /></code> parameter is shown not as a radio button form field, but by a drop-down list.
* All drop-down lists (both those defined as such in <code>config.xml</code>, and those defined as radio buttons) are given an extra option. This extra option displays the text "Use Global" but has an associated value of an empty string. The "Use Global" option is set as the default option for the list. Thus, by default, these parameters will use the Component-wide default values, rather than overriding them. (However, note that any text box fields defined with a default value in <code>config.xml</code> retain that default value, and so will override the component-wide default value if that is different).

===3. 'Article' specific parameters===

These are defined in an XML file which can be stored anywhere you like, but is typically placed within the <code>models</code> folder of the Component Back-end (if you are using an MVC structure) and named according to the model to which they apply, i.e. <code>PATH_TO_JOOMLA/administrator/components/com_COMPONENT_NAME/models/MODEL_NAME.xml</code>. The XML file has the following structure:

<source lang="xml">
<root>
<params>
<param />
...
</params>
<params group="GROUP_NAME">
<param />
...
</params>
...
</root>
</source>

As above, you can give the <code><root></code> element whatever name you wish. You can also have as many <code><params></code> groups as you like, though each group must have a <code>group</code> attribute with a different <code>GROUP_NAME</code>. If there are two or more <code><params></code> groups with the same <code>GROUP_NAME</code>, only the last one in the list will be considered.

To display the forms for these parameters in the Back-end of your Component, you will need to do a little work yourself. Firstly, you need to access the saved parameter data from the database. For this, you will need to identify both the location of the stored parameters data in the database, and the XML file that you are using to define the parameter form fields. Assuming that you have already created a <code>$row</code> variable to hold your component item (i.e. 'article') data, that the parameters data is stored in the <code>params</code> field of the <code>$row</code>, and that the XML file is located in the models folder as specified above, you could use the following code:
<source lang="php">
$paramsdata = $row->params;
$paramsdefs = JPATH_COMPONENT.DS.'models'.DS.'MODEL_NAME.xml';
$params = new JParameter( $paramsdata, $paramsdefs );

$this->assignRef('params', $params);
</source>
This code is typically placed in the View file (e.g. view.html.php) within the corresponding folder.

To display the parameters forms in slider panes (in the same way that they are displayed in the menu item Back-end), you should use the following code in the template file (e.g. <code>PATH_TO_JOOMLA/administrator/com_COMPONENT_NAME/views/VIEW_NAME/tmpl/default.php</code>):
<source lang="php">
jimport('joomla.html.pane');

$pane =& JPane::getInstance( 'sliders' );

echo $pane->startPane( 'content-pane' );

// First slider panel
// Create a slider panel with a title of SLIDER_PANEL_1_TITLE and a title id attribute of SLIDER_PANEL_1_NAME
echo $pane->startPanel( JText::_( 'SLIDER_PANEL_1_TITLE' ), 'SLIDER_PANEL_1_NAME' );
// Display the parameters defined in the <params> group with no 'group' attribute
echo $this->params->render( 'params' );
echo $pane->endPanel();

//Second slider panel
// Create a slider panel with a title of SLIDER_PANEL_2_TITLE and a title id attribute of SLIDER_PANEL_2_NAME
echo $pane->startPanel( JText::_( 'SLIDER_PANEL_2_TITLE' ), 'SLIDER_PANEL_2_NAME' );
// Display the parameters defined in the <params> group with the 'group' attribute of 'GROUP_NAME'
echo $this->params->render( 'params', 'GROUP_NAME' );
echo $pane->endPanel();

// Repeat for each additional slider panel required

echo $pane->endPane();
</source>
In order to save the parameters to the database you have to overload the bind() function which can be found in
<code>PATH_TO_JOOMLA/administrator/com_COMPONENT_NAME/tables/COMPONENT_NAME.php</code>
<source lang="php">
function bind($array, $ignore = '')
{
if (key_exists( 'params', $array ) && is_array( $array['params'] ))
{
$registry = new JRegistry();
$registry->loadArray($array['params']);
$array['params'] = $registry->toString();
}
return parent::bind($array, $ignore);
}
</source>

==Accessing the parameters - frontend==

The Front-end situation is a bit more complex than the Back-end. The 'standard' way to deal with parameters in the Front-end is to set up a cascade of overrides, as described above:
<blockquote>Item-specific ''overrides'' Menu-specific ''overrides'' Component-default</blockquote>
If you '''don't''' want to do this, then a little extra work is required

===With overrides===

The following code will access the Component-wide default parameters, ''already overridden'' with those for the menu item (if applicable):

<source lang="php">
<?php
$params = &JComponentHelper::getParams( 'COMPONENT_NAME' );

// e.g. for the com_weblinks component, you would use:
// $params = &JComponentHelper::getParams( 'com_weblinks' )
?>
</source>

In an MVC structure, this code would be placed in the <code>view.html.php</code> file for the particular view required.

Assuming that the item parameters are stored in the <code>params</code> field, and that the particular item has been loaded into the <code>$row</code> object by the method, you would then add in the item parameters to the <code>$params</code> object using:

<source lang="php">
<?php
$params->merge( new JParameter( &$row->params ) );
?>
</source>

Note that, in both cases (i.e. overrides by menu-specific parameters, and overrides by item-specific parameters), we aren't ''just'' doing overrides - we also add in any new parameters that weren't found in the defaults. In other words, the <code>$params</code> object ends up with all the parameters we need!

To access the value of a specific parameter, we would use:

<source lang="php">
<?php
$params->get( 'PARAMETER_NAME' );

// e.g. to obtain the value of 'parameter1', we use:
// $params->get( 'parameter1' );
?>
</source>

It is important to realise that any <code>merge</code> carried out is persistent, so the following code (where for example you have an array containing the parameters sets for several items, and you want the parameters for each item to individually override the defaults) would not produce the result you might expect:

<source lang="php">
<?php
foreach ($itemparamsgroup as $itemparams)
{
$params = &JComponentHelper::getParams( 'COMPONENT_NAME' );
$params->merge( $itemparams );
echo $params->get( 'PARAMETER_NAME' );
}
?>
</source>

In such cases, you will need to use the non-override method, and then force the overrides manually, as described below.

===Without overrides===

There will be cases where you don't want to use the default override pattern. For example, you may want to ignore the menu-specific parameters, and have only the item-specific parameters overriding the defaults. This is a little more difficult to accomplish, although it can still be done.

You can access the Component-wide default parameter values, ''without the menu overrides'', as follows:

<source lang="php">
<?php
$component = JComponentHelper::getComponent( 'COMPONENT_NAME' );
$params = new JParameter( $component->params );
?>
</source>

If you want to override these with the menu parameters, but ''without'' the 'persistence' effect described above, you can:

<source lang="php">
<?php
$menuitemid = JRequest::getInt( 'Itemid' );
if ($menuitemid)
{
$menu = JSite::getMenu();
$menuparams = $menu->getParams( $menuitemid );
$params->merge( $menuparams );
}
?>
</source>

You can access the item parameters as before, and choose whether to merge them in using the code above, or simply store them in a separate object:

<source lang="php">
<?php
$itemparams = new JParameter( $row->params );
?>
</source>

You can combine this code to achieve the effect that you want. For example, you could override the Component-wide defaults with the item-specific parameters, but ignore those for the menu. Or you could use the menu-specific parameters in some circumstances, and the item-specific ones in others. [Whenever you depart from the standard approach, though, you should be careful that you inform your users how your Component works. Users will expect your component to work the same way as those from the Joomla! core, so you should have a good reason for departing from this approach.]

Accessing the value of a particular parameter is done in the same way as described above.

[[Category:Components]]
[[Category:Parameters]]
[[Category:Tutorials]]
[[Category:Component Management]]
[[Category:Component Development]]

J1.5:Component parameters

2011-02-03T22:55:35Z

Datashuttle: /* 2. Menu item specific parameters */ Corrected misspelling.

==Background==
One thing that sets Joomla! Components apart from other types of Extension (i.e. Modules and Plugins) is the ability to store significant quantities of data in the Joomla! MySQL database. Typically, this data will be content for displaying on a page (such as the content of an article, or its title) or data about how that content should be displayed (e.g. a setting specifying whether or not the title should be shown). A Component normally creates at least one table in the database to store this data - for example, data for articles associated with the <code>com_content</code> Component are stored in the <code>jos_content</code> table (where ''jos'' is the table prefix for the site).

However, choosing exactly how to store each item of data requires a little more thought. There are essentially two choices: each data item may be stored in its own field, or a collection of data items may be stored within a single parameters field. (Of course, there is nothing to stop you making use of both methods, for different data items, within the same component). Which approach you use for a given data item is largely a matter of personal choice, although there are some factors to consider:
* Core code included in the Joomla! installation makes it very easy to produce the appropriate form elements for entering data into '''parameters''' in the Back-end. If you choose to save the data in separate fields, you will need to code the appropriate form elements yourself.
* Again, Joomla! core code allows you to set default values for '''parameters''' across the whole component. Individual component items (e.g. individual articles) can then choose to use the default values, or to override them with values specific to that item. See below for details of how to do this.
* It is not possible to extract individual parameter values directly from the database. Instead, the whole parameters field must be extracted and parsed to obtain the different parameter values. This means that it is not very easy, for example, to run MySQL queries that search for a parameter with a particular value. Any data that you want to run queries against should be given its '''own table field'''.
* Similarly, it is not possible to run data validation on parameter fields before saving data.
In general, parameters are conventionally used to store data relating to the ''presentation'' of information. The information itself is generally stored in separate fields.

==Types of Component parameter==

===1. Component-wide default parameters===

These parameters are set once for the whole Component, and are generally used to provide the 'default' parameter settings for the Component on that particular site.

===2. Menu item specific parameters===

A menu link to an individual Component item (e.g. an article) can also have parameters associated with it, which can affect the way the Component item is displayed ''using that link''. The types of parameters available will depend on the way that the Component item is displayed (the 'view' in MVC terms, but don't worry if this doesn't mean anything to you!). However, the precise values of those parameters can be set for each menu link individually. If there is another menu link to that same Component item, then it is important to realise each menu link may have different parameter values, and so the same article may be displayed differently in the two cases.

A menu link can also override the Component-wide default parameters, so that the override values (if set) are used in place of the default values ''for that Component item when accessed via that menu link''. As you would expect, when no override value is set, the default value is used instead, in the normal manner.

===3. 'Article' specific parameters===

Finally, each Component item (e.g. article) can have parameters which apply to that item, regardless of how it is accessed (i.e. via any available menu link, or even without reference to a menu at all!). If the Component designer wants, the article specific parameters can also be set up to use the 'override' behaviour, so that they default to the current values of the corresponding Component-wide parameters, though this is not essential. Again, this is described further below.

==Storing the parameters and their values.==

In general, a set of parameters is stored within the database in a single <code>text</code> field. Different parameters are separated by <code>newline</code> characters ('<code>\n</code>' in MySQL - each parameter will appear on a different line when you look at the data in something like phpMyAdmin). Each parameter consists of the parameter name and value, separated by an equals sign (=). As an example:

<source lang="text">
parameter1=parameter1value
parameter2=
parameter3=parameter3value
parameter4=parameter4value
</source>

Here, parameter1, parameter3, and parameter4 have all been assigned values, whilst parameter2 has no value. Typically, a parameter will be given no value where it is set up to allow override of a default value, but 'no override is required' - i.e. it is desired to use the default value.

===1. Component-wide default parameters===

These are stored in the <code>params</code> field of the jos_components table, in the row corresponding to the particular component to which they apply.

===2. Menu item specific parameters===

These are stored in the <code>params</code> field of the jos_menu table, in the row corresponding to the particular menu item to which they apply.

===3. 'Article' specific parameters===

These are stored in a text field in the table created by the Component. Whilst there is no strict rule for naming the field, it is common to extend the above pattern using the <code>params</code> name. However, com_content stores article parameters in a field called <code>attribs</code>.

==Accessing the parameters - Back-end==

Joomla! includes some shortcuts to enable component creators to easily add parameter forms to the Back-end of their component. These forms allow a site administrator to enter a parameter value by, for example, entering some text in a box, choosing from a drop-down list, or selecting a radio button. To create these forms, each parameter needs to have an associated <code><param /></code> object in an XML file. The type of <code><nowiki><param /></nowiki></code> object determines the form elements that will be shown in the Back-end. A list of the available form elements is given [[Standard_parameter_types|here]]. More information is given below about the XML file names, structure and location required for each set of parameters.

===1. Component-wide default parameters===

These can be created at installation of the Component, by including <code><param /></code> elements in the installation XML file (typically called COMPONENT_NAME.xml, and located in the root folder of the Component package. As far as the parameters are concerned, this XML file has the following structure:
<source lang="xml">
<install>
...
<params>
<param />


<param name="font_size" default="16" />

...
</params>
<url addpath="....">
<param />
</url>
...
</install>
</source>
Each <code><param /></code> element must be given the attributes <code>name</code> and <code>default</code>, which define the parameter name and value respectively. These values are then copied to the jos_components table in the database.

However, on its own this is not very useful, as it doesn't allow users to change the values of the parameters. To do this, parameter form elements need to be defined in a file named <code>config.xml</code> which is located in <code>/PATH_TO_JOOMLA/administrator/components/com_COMPONENT_NAME/</code>. The file should have the following structure:
<source lang="xml">
<root>
<params>
<url addpath="/administrator/components/com_COMPONENT_NAME/elements">
<param name="cid" type="JELEMENT_TYPE_NAME" scope="com_COMPONENT_NAME" default="0" label="LABEL" description="DESCRIPTION" />
</url>
<param type="type" name="name" description="description" />



<param type="text" name="font_size" size="3" label="Font size:" description="Please enter the required font size" />

...
</params>
</root>
</source>
Note that the <code><root></code> element can have any name you wish, but there must be one element at the root of the document (this is a requirement for a well-formed XML document). You can have more than one <code><params></code> element, but only the first one will be considered. It is not currently possible to group certain parameter form elements together.

The <code><url></code> section contains parameters which are added to the URL of the menu item. To enable this functionality, the <code>type</code> attribute of the <code><param></code> elements must specify the name of a class which extends JElement, and is able to generate HTML forms to display and set the parameter. You can use one of the [[Standard parameter types]]. Or, you can create your own subclass of JElement. Put the class definition file in your component's <code>/administrator/components/com_COMPONENT_NAME/</code> directory, and refer to this path in the <code>addpath</code> attribute of the <code><URL></code> element. More information here: http://forum.joomla.org/viewtopic.php?f=476&t=206062.

So that administrators to access these parameters, you will need to add a button to the toolbar in the Back-end of your component. This can be done using the code:
<source lang="php">
JToolBarHelper::preferences( 'com_COMPONENT_NAME' );
// e.g. for the core Content component, you would use JToolBarHelper::preferences( 'com_content' );
</source>
which is typically placed in the PHP file responsible for the Back-end output. (For example, using an MVC structure, you might place this code at the top of <code>/PATH_TO_JOOMLA/administrator/components/com_COMPONENT_NAME/views/VIEW_NAME/tmpl/default.php</code>.

This adds a <code>Parameters</code> button to the toolbar:

[[Image:Toolbar_newsfeed.png]]

Clicking on the toolbar button produces a pop-up window containing the form fields for each parameter defined in <code>config.xml</code>.

Note that there is no need to define <code>default</code> attributes for the <code><param /></code> elements in the <code>config.xml</code> file, since the default values will already have been saved in the installation of the Component.

===2. Menu item specific parameters===

A menu item is associated with a particular view from your Component's Front-end - following the menu link in the Front-end will display that view. Joomla! 1.5 allows you to define parameters for a particular view, so that a copy of those parameters can be associated with each menu item using the view. In addition, you can also choose to override the Component-wide default parameters defined as above, so that the override values will apply to the particular menu item.

The view parameters are defined in an XML file stored in the ''Front-end'' view output template directory. (This is not to be confused with the site Template directory, which is different!). The XML file has the same name as the layout used with the template. For most applications you will be using the default layout. Thus the path the XML file is something like: <code>/PATH_TO_JOOMLA/components/com_COMPONENT_NAME/views/VIEW_NAME/tmpl/default.xml</code>. The structure of the file is:
<source lang="xml">
<metadata>
...
<state>
...
<params>
<param />
...
</params>
<url>
<param />
...
</url>
<advanced>
<param />
...
</advanced>
</state>
</metadata>
</source>

See [[Standard parameter types]] for a full list of the core parameter types. (You can use these types within a <code><url></code> section without needing to supply an <code>addpath</code> attribute.)

Displaying the forms for these parameters is handled automatically by the core <code>com_menus</code> component, which creates a number of slider panes on the right hand side (at least when viewed using the default Khepri backend site Template) of the menu item edit screen. Any parameters defined within the <code><params></code> or <code><url></code> tags will appear in the <code>Parameters - Basic</code> slider pane. Any parameters defined within the <code><advanced></code> tag will appear in the <code>Parameters - Advanced</code> slider pane.

The following screenshot shows the menu admin page for the Category 'List' layout. You can see that the <code>Parameters - Basic</code> slider pane is open, and contains form elements for five parameters. There are no 'Advanced' parameters for this view, and so the <code>Parameters - Advanced</code> slider pane is not shown:

[[Image:Menu items edit.png]]

For the override of the Component-wide default parameters, <code>com_menus</code> uses the same <code>config.xml</code> file as above, so there is no need to define these parameters again. The override forms are automatically added to a slider pane named <code>Parameters - Component</code>. However, there are a number of changes from the forms used in the Preferences pop-up window (despite being based on the same <code>config.xml</code> file):
* Any <code><param type="radio" /></code> parameter is shown not as a radio button form field, but by a drop-down list.
* All drop-down lists (both those defined as such in <code>config.xml</code>, and those defined as radio buttons) are given an extra option. This extra option displays the text "Use Global" but has an associated value of an empty string. The "Use Global" option is set as the default option for the list. Thus, by default, these parameters will use the Component-wide default values, rather than overriding them. (However, note that any text box fields defined with a default value in <code>config.xml</code> retain that default value, and so will override the component-wide default value if that is different).

===3. 'Article' specific parameters===

These are defined in an XML file which can be stored anywhere you like, but is typically placed within the <code>models</code> folder of the Component Back-end (if you are using an MVC structure) and named according to the model to which they apply, i.e. <code>PATH_TO_JOOMLA/administrator/components/com_COMPONENT_NAME/models/MODEL_NAME.xml</code>. The XML file has the following structure:

<source lang="xml">
<root>
<params>
<param />
...
</params>
<params group="GROUP_NAME">
<param />
...
</params>
...
</root>
</source>

As above, you can give the <code><root></code> element whatever name you wish. You can also have as many <code><params></code> groups as you like, though each group must have a <code>group</code> attribute with a different <code>GROUP_NAME</code>. If there are two or more <code><params></code> groups with the same <code>GROUP_NAME</code>, only the last one in the list will be considered.

To display the forms for these parameters in the Back-end of your Component, you will need to do a little work yourself. Firstly, you need to access the saved parameter data from the database. For this, you will need to identify both the location of the stored parameters data in the database, and the XML file that you are using to define the parameter form fields. Assuming that you have already created a <code>$row</code> variable to hold your component item (i.e. 'article') data, that the parameters data is stored in the <code>params</code> field of the <code>$row</code>, and that the XML file is located in the models folder as specified above, you could use the following code:
<source lang="php">
$paramsdata = $row->params;
$paramsdefs = JPATH_COMPONENT.DS.'models'.DS.'MODEL_NAME.xml';
$params = new JParameter( $paramsdata, $paramsdefs );

$this->assignRef('params', $params);
</source>
This code is typically placed in the View file (e.g. view.html.php) within the corresponding folder.

To display the parameters forms in slider panes (in the same way that they are displayed in the menu item Back-end), you should use the following code in the template file (e.g. <code>PATH_TO_JOOMLA/administrator/com_COMPONENT_NAME/views/VIEW_NAME/tmpl/default.php</code>):
<source lang="php">
jimport('joomla.html.pane');

$pane =& JPane::getInstance( 'sliders' );

echo $pane->startPane( 'content-pane' );

// First slider panel
// Create a slider panel with a title of SLIDER_PANEL_1_TITLE and a title id attribute of SLIDER_PANEL_1_NAME
echo $pane->startPanel( JText::_( 'SLIDER_PANEL_1_TITLE' ), 'SLIDER_PANEL_1_NAME' );
// Display the parameters defined in the <params> group with no 'group' attribute
echo $this->params->render( 'params' );
echo $pane->endPanel();

//Second slider panel
// Create a slider panel with a title of SLIDER_PANEL_2_TITLE and a title id attribute of SLIDER_PANEL_2_NAME
echo $pane->startPanel( JText::_( 'SLIDER_PANEL_2_TITLE' ), 'SLIDER_PANEL_2_NAME' );
// Display the parameters defined in the <params> group with the 'group' attribute of 'GROUP_NAME'
echo $this->params->render( 'params', 'GROUP_NAME' );
echo $pane->endPanel();

// Repeat for each additional slider panel required

echo $pane->endPane();
</source>
In order to save the parameters to the database you have to overload the bind() function which can be found in
<code>PATH_TO_JOOMLA/administrator/com_COMPONENT_NAME/tables/COMPONENT_NAME.php</code>
<source lang="php">
function bind($array, $ignore = '')
{
if (key_exists( 'params', $array ) && is_array( $array['params'] ))
{
$registry = new JRegistry();
$registry->loadArray($array['params']);
$array['params'] = $registry->toString();
}
return parent::bind($array, $ignore);
}
</source>

==Accessing the parameters - frontend==

The Front-end situation is a bit more complex than the Back-end. The 'standard' way to deal with parameters in the Front-end is to set up a cascade of overrides, as described above:
<blockquote>Item-specific ''overrides'' Menu-specific ''overrides'' Component-default</blockquote>
If you '''don't''' want to do this, then a little extra work is required

===With overrides===

The following code will access the Component-wide default parameters, ''already overridden'' with those for the menu item (if applicable):

<source lang="php">
<?php
$params = &JComponentHelper::getParams( 'COMPONENT_NAME' );

// e.g. for the com_weblinks component, you would use:
// $params = &JComponentHelper::getParams( 'com_weblinks' )
?>
</source>

In an MVC structure, this code would be placed in the <code>view.html.php</code> file for the particular view required.

Assuming that the item parameters are stored in the <code>params</code> field, and that the particular item has been loaded into the <code>$row</code> object by the method, you would then add in the item parameters to the <code>$params</code> object using:

<source lang="php">
<?php
$params->merge( new JParameter( &$row->params ) );
?>
</source>

Note that, in both cases (i.e. overrides by menu-specific parameters, and overrides by item-specific parameters), we aren't ''just'' doing overrides - we also add in any new parameters that weren't found in the defaults. In other words, the <code>$params</code> object ends up with all the parameters we need!

To access the value of a specific parameter, we would use:

<source lang="php">
<?php
$params->get( 'PARAMETER_NAME' );

// e.g. to obtain the value of 'parameter1', we use:
// $params->get( 'parameter1' );
?>
</source>

It is important to realise that any <code>merge</code> carried out is persistent, so the following code (where for example you have an array containing the parameters sets for several items, and you want the parameters for each item to individually override the defaults) would not produce the result you might expect:

<source lang="php">
<?php
foreach ($itemparamsgroup as $itemparams)
{
$params = &JComponentHelper::getParams( 'COMPONENT_NAME' );
$params->merge( $itemparams );
echo $params->get( 'PARAMETER_NAME' );
}
?>
</source>

In such cases, you will need to use the non-override method, and then force the overrides manually, as described below.

===Without overrides===

There will be cases where you don't want to use the default override pattern. For example, you may want to ignore the menu-specific parameters, and have only the item-specific parameters overriding the defaults. This is a little more difficult to accomplish, although it can still be done.

You can access the Component-wide default parameter values, ''without the menu overrides'', as follows:

<source lang="php">
<?php
$component = JComponentHelper::getComponent( 'COMPONENT_NAME' );
$params = new JParameter( $component->params );
?>
</source>

If you want to override these with the menu parameters, but ''without'' the 'persistence' effect described above, you can:

<source lang="php">
<?php
$menuitemid = JRequest::getInt( 'Itemid' );
if ($menuitemid)
{
$menu = JSite::getMenu();
$menuparams = $menu->getParams( $menuitemid );
$params->merge( $menuparams );
}
?>
</source>

You can access the item parameters as before, and choose whether to merge them in using the code above, or simply store them in a separate object:

<source lang="php">
<?php
$itemparams = new JParameter( $row->params );
?>
</source>

You can combine this code to achieve the effect that you want. For example, you could override the Component-wide defaults with the item-specific parameters, but ignore those for the menu. Or you could use the menu-specific parameters in some circumstances, and the item-specific ones in others. [Whenever you depart from the standard approach, though, you should be careful that you inform your users how your Component works. Users will expect your component to work the same way as those from the Joomla! core, so you should have a good reason for departing from this approach.]

Accessing the value of a particular parameter is done in the same way as described above.

[[Category:Components]]
[[Category:Parameters]]
[[Category:Tutorials]]
[[Category:Component Management]]
[[Category:Component Development]]

J2.5:File Structure and Naming Conventions

2011-02-03T17:14:39Z

Datashuttle: /* The /site folder */ edited the view.html.php paragraph to define the .html section as that part of the filename.

__NOTOC__
Components in Jooomla! 1.5 can now benefit from the flexibility and power of using Object Oriented Programming (OOP) practices. Most complex components will follow the Model-View-Controller (MVC) design pattern. This pattern separates the data gathering (Model), presentation (View) and user interaction (Controller) activities of a component. Such separation allows for expanding or revising properties and methods of one section without requiring additional changes to the other sections. Please see [[Developing a Model-View-Controller Component - Part 1|the MVC tutorial]] for an explanations of the MVC structure.

Joomla!'s file loading system enables developers to work with separate files for controllers, views and models without worrying about importing the right file in the right place. However, for this to work, certain naming conventions need to be observed.

The Joomla! framework is extremely flexible, and it is possible to diverge from these conventions in many ways. It is nonetheless recommended to apply standard naming wherever possible to increase readability and maintainability. Additionally, the framework will take care of the many tedious class management tasks when the files and classes of a component are named correctly.

Throughout this article, {ComponentName} is used to represent the name of the component (for example, Content). Notice also that case is important. {componentname} will refer to the lowercase version of {ComponentName}, eg. <code>CamelCasedController</code> -> <code>camelcasedcontroller</code>.
Similarly, {ViewName} and {viewname}, {ModelName} and {modelname}, {ControllerName} and {controllername}.

== Reserved words ==

There are reserved words which can't be used in names of classes and components.

An example is the word "view" (in any case) for view classes (except "view" that must be second part of that class name)<ref>Reason is in line 420 of file libraries/joomla/application/component/view.php: "<code>if (!preg_match('/View((view)*(.*(view)?.*))$/i', get_class($this), $r)) {</code>"</ref>. Because the first part of the name of view classes is the same as the controller class name, controller class names can't contain the word "view" either. And because of the conventions (although violating of it won't produce an error), controller class names must contain the component name, so component names can't contain the word "view" either. So components can't be named "com_reviews", or if they are, they must violate the naming conventions and have a different base controller class name (or have some other hacks).

== Installation package vs. actual file placement ==

All Joomla! extensions must be packaged as a .zip installation file. According to the most common file arrangement, the package should contain at least the following two folders as a basic structure:
* <code>site</code>
* <code>admin</code>
If you set up your XML manifest file according to standard practice, the contents of <code>site</code> will be installed to <code>/components/com_{componentname}</code>, whereas the contents of <code>admin</code> will be installed to <code>/administrator/components/com_{componentname}</code>.

== The /site folder==
This folder keeps the files for the frontend part of the component.

:'''<code>/site/{componentname}.php</code>'''
:This is the component's main file and entry point ''for the frontend part''.

:'''<code>/site/controller.php</code>'''
:This file holds the default frontend controller, which is a class called <code>{ComponentName}Controller</code>. This class must extend the base class <code>JController</code>.

:'''<code>/site/views</code>'''
:This folder holds the different views for the component.

::'''<code>/site/views/{viewname}</code>'''
::This folder holds the files for the view {ViewName}.

:::'''<code>/site/views/{viewname}/view.html.php</code>'''
:::This file is the entry point for the view {ViewName}. It should declare the class <code>{ComponentName}View{ViewName}</code>. This class must extend the base class <code>JView</code>. The <code>.html</code> section of the filename is related to the format the view will be loaded in. For example, if the <code>format</code> URL parameter is set to <code>format=feed</code>, the file <code>view.feed.php</code> will be loaded.

:::'''<code>/site/views/{viewname}/tmpl</code>'''
:::This folder holds the template files for the view {ViewName}.

::::'''<code>/site/views/{viewname}/tmpl/default.php</code>'''
::::This is the default template for the view {ViewName}. In this PHP file, the <code>$this</code> keyword refers to the view class that the template belongs to.

:'''<code>/site/models</code>'''
:This folder holds additional models, if needed by the application.

::'''<code>/site/models/{modelname}.php</code>'''
::This file holds the model class <code>{ComponentName}Model{ModelName}</code>. This class must extend the base class <code>JModel</code>. Note that the view named {ViewName} will by default load a model called {ViewName} if it exists. Most models are named after the view they are intended to be used with, but this is '''not''' a requirement. See [[Using multiple models in an MVC component]] for more information.

:'''<code>/site/controllers</code>'''
:This folder holds additional controllers, if needed by the application.

::'''<code>/site/controllers/{controllername}.php</code>'''
::This file holds the controller class <code>{ComponentName}Controller{ControllerName}</code>. This class must extend the base class <code>JController</code>.

== The /admin folder ==
The file structure is exactly the same as in the /site folder. Note that the view, models, controllers etc. of the site and admin parts are by default completely separated, and have nothing to do with each other - the site part and the admin part can be thought of as two different components! A view in the /admin folder may have a counterpart with the same name in the /site folder, yet the two views have nothing in common but their name.

However, it might sometimes make sense to share classes between the site and admin parts of the component. Especially models can be shared to avoid duplicating model code. The Joomla! framework supports this strategy. When sharing any code between site and admin applications, the classes should be designed with great care to avoid the possibility of a site user executing admin actions.
<noinclude>
----
<references/>
[[Category:References]][[Category:Component Development]]</noinclude>

Archived:Developing a MVC Component/Adding ACL

2011-02-02T19:42:50Z

Datashuttle: Reworded the "Setting the value in the assets table" paragraph.

This tutorial is for {{JVer|1.6}}

== Articles in this series ==
{{Chunk:Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Contents}}

== Introduction ==
This tutorial is part of the [[Developing a Model-View-Controller (MVC) Component for Joomla!1.6]] tutorial. You are encouraged to read the previous parts of the tutorial before reading this.

== Describing the ACL ==
Each component has its own ACL. They can be described in an ''access.xml'' file located at the root of the ''admin'' folder. This file describes the ACL for the com_helloworld component in a different section. In this example, we have chosen to separate the different ACL into two sections: components and messages.


''admin/access.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8" ?>
<access component="com_helloworld">
<section name="component">
<action name="core.admin" title="JACTION_ADMIN" description="JACTION_ADMIN_COMPONENT_DESC" />
<action name="core.manage" title="JACTION_MANAGE" description="JACTION_MANAGE_COMPONENT_DESC" />
<action name="core.create" title="JACTION_CREATE" description="JACTION_CREATE_COMPONENT_DESC" />
<action name="core.delete" title="JACTION_DELETE" description="JACTION_DELETE_COMPONENT_DESC" />
<action name="core.edit" title="JACTION_EDIT" description="JACTION_EDIT_COMPONENT_DESC" />
</section>
<section name="message">
<action name="core.delete" title="JACTION_DELETE" description="COM_HELLOWORLD_ACCESS_DELETE_DESC" />
<action name="core.edit" title="JACTION_EDIT" description="COM_HELLOWORLD_ACCESS_EDIT_DESC" />
</section>
</access>
</source>


== Restricting access to the component ==

The main idea in ACL is to restrict actions to groups of users. The first action to be restricted is access to the component itself. With your favorite file editor, edit the ''admin/helloworld.php'' file and it these lines


''admin/helloworld.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// Access check.
if (!JFactory::getUser()->authorise('core.manage', 'com_helloworld'))
{
return JError::raiseWarning(404, JText::_('JERROR_ALERTNOAUTHOR'));
}

// require helper file
JLoader::register('HelloWorldHelper', dirname(__FILE__) . DS . 'helpers' . DS . 'helloworld.php');

// import joomla controller library
jimport('joomla.application.component.controller');

// Get an instance of the controller prefixed by HelloWorld
$controller = JController::getInstance('HelloWorld');

// Perform the Request task
$controller->execute(JRequest::getCmd('task'));

// Redirect if set by the controller
$controller->redirect();

</source>


== Displaying only the right toolbar buttons ==

The toolbar buttons that have to displayed depends on the ACL rights.

In the ''admin/views/helloworlds/view.html.php'', put this code


''admin/views/helloworlds/view.html.php''
<source lang="php">
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// import Joomla view library
jimport('joomla.application.component.view');

/**
* HelloWorlds View
*/
class HelloWorldViewHelloWorlds extends JView
{
/**
* HelloWorlds view display method
* @return void
*/
function display($tpl = null)
{
// Get data from the model
$items = $this->get('Items');
$pagination = $this->get('Pagination');

// Check for errors.
if (count($errors = $this->get('Errors')))
{
JError::raiseError(500, implode(' ', $errors));
return false;
}
// Assign data to the view
$this->items = $items;
$this->pagination = $pagination;

// Set the toolbar
$this->addToolBar();

// Display the template
parent::display($tpl);

// Set the document
$this->setDocument();
}

/**
* Setting the toolbar
*/
protected function addToolBar()
{
$canDo = HelloWorldHelper::getActions();
JToolBarHelper::title(JText::_('COM_HELLOWORLD_MANAGER_HELLOWORLDS'), 'helloworld');
if ($canDo->get('core.create'))
{
JToolBarHelper::addNew('helloworld.add', 'JTOOLBAR_NEW');
}
if ($canDo->get('core.edit'))
{
JToolBarHelper::editList('helloworld.edit', 'JTOOLBAR_EDIT');
}
if ($canDo->get('core.delete'))
{
JToolBarHelper::deleteList('', 'helloworld.delete', 'JTOOLBAR_DELETE');
}
if ($canDo->get('core.admin'))
{
JToolBarHelper::divider();
JToolBarHelper::preferences('com_helloworld');
}
}
/**
* Method to set up the document properties
*
* @return void
*/
protected function setDocument()
{
$document = JFactory::getDocument();
$document->setTitle(JText::_('COM_HELLOWORLD_ADMINISTRATION'));
}
}
</source>


In the ''admin/views/helloworld/view.html.php'', put this code


''admin/views/helloworld/view.html.php''
<source lang="php">
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// import Joomla view library
jimport('joomla.application.component.view');

/**
* HelloWorld View
*/
class HelloWorldViewHelloWorld extends JView
{
/**
* display method of Hello view
* @return void
*/
public function display($tpl = null)
{
// get the Data
$form = $this->get('Form');
$item = $this->get('Item');
$script = $this->get('Script');

// Check for errors.
if (count($errors = $this->get('Errors')))
{
JError::raiseError(500, implode(' ', $errors));
return false;
}
// Assign the Data
$this->form = $form;
$this->item = $item;
$this->script = $script;

// Set the toolbar
$this->addToolBar();

// Display the template
parent::display($tpl);

// Set the document
$this->setDocument();
}

/**
* Setting the toolbar
*/
protected function addToolBar()
{
JRequest::setVar('hidemainmenu', true);
$user = JFactory::getUser();
$userId = $user->id;
$isNew = $this->item->id == 0;
$canDo = HelloWorldHelper::getActions($this->item->id);
JToolBarHelper::title($isNew ? JText::_('COM_HELLOWORLD_MANAGER_HELLOWORLD_NEW') : JText::_('COM_HELLOWORLD_MANAGER_HELLOWORLD_EDIT'), 'helloworld');
// Built the actions for new and existing records.
if ($isNew)
{
// For new records, check the create permission.
if ($canDo->get('core.create'))
{
JToolBarHelper::apply('helloworld.apply', 'JTOOLBAR_APPLY');
JToolBarHelper::save('helloworld.save', 'JTOOLBAR_SAVE');
JToolBarHelper::custom('helloworld.save2new', 'save-new.png', 'save-new_f2.png', 'JTOOLBAR_SAVE_AND_NEW', false);
}
JToolBarHelper::cancel('helloworld.cancel', 'JTOOLBAR_CANCEL');
}
else
{
if ($canDo->get('core.edit'))
{
// We can save the new record
JToolBarHelper::apply('helloworld.apply', 'JTOOLBAR_APPLY');
JToolBarHelper::save('helloworld.save', 'JTOOLBAR_SAVE');

// We can save this record, but check the create permission to see if we can return to make a new one.
if ($canDo->get('core.create'))
{
JToolBarHelper::custom('helloworld.save2new', 'save-new.png', 'save-new_f2.png', 'JTOOLBAR_SAVE_AND_NEW', false);
}
}
if ($canDo->get('core.create'))
{
JToolBarHelper::custom('helloworld.save2copy', 'save-copy.png', 'save-copy_f2.png', 'JTOOLBAR_SAVE_AS_COPY', false);
}
JToolBarHelper::cancel('helloworld.cancel', 'JTOOLBAR_CLOSE');
}
}
/**
* Method to set up the document properties
*
* @return void
*/
protected function setDocument()
{
$isNew = $this->item->id == 0;
$document = JFactory::getDocument();
$document->setTitle($isNew ? JText::_('COM_HELLOWORLD_HELLOWORLD_CREATING') : JText::_('COM_HELLOWORLD_HELLOWORLD_EDITING'));
$document->addScript(JURI::root() . $this->script);
$document->addScript(JURI::root() . "/administrator/components/com_helloworld/views/helloworld/submitbutton.js");
JText::script('COM_HELLOWORLD_HELLOWORLD_ERROR_UNACCEPTABLE');
}
}
</source>


These two files use the ''getActions'' method defined in the ''admin/helpers/helloworld.php'' file

In the ''admin/helpers/helloworld.php'', put this code


''admin/helpers/helloworld.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die;

/**
* HelloWorld component helper.
*/
abstract class HelloWorldHelper
{
/**
* Configure the Linkbar.
*/
public static function addSubmenu($submenu)
{
JSubMenuHelper::addEntry(JText::_('COM_HELLOWORLD_SUBMENU_MESSAGES'), 'index.php?option=com_helloworld', $submenu == 'messages');
JSubMenuHelper::addEntry(JText::_('COM_HELLOWORLD_SUBMENU_CATEGORIES'), 'index.php?option=com_categories&view=categories&extension=com_helloworld', $submenu == 'categories');
// set some global property
$document = JFactory::getDocument();
$document->addStyleDeclaration('.icon-48-helloworld {background-image: url(../media/com_helloworld/images/tux-48x48.png);}');
if ($submenu == 'categories')
{
$document->setTitle(JText::_('COM_HELLOWORLD_ADMINISTRATION_CATEGORIES'));
}
}
/**
* Get the actions
*/
public static function getActions($messageId = 0)
{
$user = JFactory::getUser();
$result = new JObject;

if (empty($messageId)) {
$assetName = 'com_helloworld';
}
else {
$assetName = 'com_helloworld.message.'.(int) $messageId;
}

$actions = array(
'core.admin', 'core.manage', 'core.create', 'core.edit', 'core.delete'
);

foreach ($actions as $action) {
$result->set($action, $user->authorise($action, $assetName));
}

return $result;
}
}
</source>


== Adding permissions settings in the component preferences ==
Since we now use ACL rights in our component, we need to set them at the component level.


''admin/config.xml''
<source lang="php">
<?xml version="1.0" encoding="utf-8"?>
<config>
<fieldset
name="greetings"
label="COM_HELLOWORLD_CONFIG_GREETING_SETTINGS_LABEL"
description="COM_HELLOWORLD_CONFIG_GREETING_SETTINGS_DESC"
>
<field
name="show_category"
type="radio"
label="COM_HELLOWORLD_HELLOWORLD_FIELD_SHOW_CATEGORY_LABEL"
description="COM_HELLOWORLD_HELLOWORLD_FIELD_SHOW_CATEGORY_DESC"
default="0"
>
<option value="0">JHIDE</option>
<option value="1">JSHOW</option>
</field>
</fieldset>
<fieldset
name="permissions"
label="JCONFIG_PERMISSIONS_LABEL"
description="JCONFIG_PERMISSIONS_DESC"
>
<field
name="rules"
type="rules"
label="JCONFIG_PERMISSIONS_LABEL"
class="inputbox"
validate="rules"
filter="rules"
component="com_helloworld"
section="component"
/>
</fieldset>
</config>
</source>


== Setting the value in the assets table ==

In order to set asset for each message, we have to do two things.

First, the 'core.edit' ACL "right" is taken from the message itself, then from the component.


''admin/models/helloworld.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// import Joomla modelform library
jimport('joomla.application.component.modeladmin');

/**
* HelloWorld Model
*/
class HelloWorldModelHelloWorld extends JModelAdmin
{
/**
* Method override to check if you can edit an existing record.
*
* @param array $data An array of input data.
* @param string $key The name of the key for the primary key.
*
* @return boolean
* @since 1.6
*/
protected function allowEdit($data = array(), $key = 'id')
{
// Check specific edit permission then general edit permission.
return JFactory::getUser()->authorise('core.edit', 'com_helloworld.message.'.((int) isset($data[$key]) ? $data[$key] : 0)) or parent::allowEdit($data, $key);
}
/**
* Returns a reference to the a Table object, always creating it.
*
* @param type The table type to instantiate
* @param string A prefix for the table class name. Optional.
* @param array Configuration array for model. Optional.
* @return JTable A database object
* @since 1.6
*/
public function getTable($type = 'HelloWorld', $prefix = 'HelloWorldTable', $config = array())
{
return JTable::getInstance($type, $prefix, $config);
}
/**
* Method to get the record form.
*
* @param array $data Data for the form.
* @param boolean $loadData True if the form is to load its own data (default case), false if not.
* @return mixed A JForm object on success, false on failure
* @since 1.6
*/
public function getForm($data = array(), $loadData = true)
{
// Get the form.
$form = $this->loadForm('com_helloworld.helloworld', 'helloworld', array('control' => 'jform', 'load_data' => $loadData));
if (empty($form))
{
return false;
}
return $form;
}
/**
* Method to get the script that have to be included on the form
*
* @return string Script files
*/
public function getScript()
{
return 'administrator/components/com_helloworld/models/forms/helloworld.js';
}
/**
* Method to get the data that should be injected in the form.
*
* @return mixed The data for the form.
* @since 1.6
*/
protected function loadFormData()
{
// Check the session for previously entered form data.
$data = JFactory::getApplication()->getUserState('com_helloworld.edit.helloworld.data', array());
if (empty($data))
{
$data = $this->getItem();
}
return $data;
}
}
</source>


Second, set the asset name, asset title and asset parent in the helloworld table.


''admin/tables/helloworld.php''
<source lang="php">
<?php
// No direct access
defined('_JEXEC') or die('Restricted access');

// import Joomla table library
jimport('joomla.database.table');

/**
* Hello Table class
*/
class HelloWorldTableHelloWorld extends JTable
{
/**
* Constructor
*
* @param object Database connector object
*/
function __construct(&$db)
{
parent::__construct('#__helloworld', 'id', $db);
}
/**
* Overloaded bind function
*
* @param array named array
* @return null|string null is operation was satisfactory, otherwise returns an error
* @see JTable:bind
* @since 1.5
*/
public function bind($array, $ignore = '')
{
if (isset($array['params']) && is_array($array['params']))
{
// Convert the params field to a string.
$parameter = new JRegistry;
$parameter->loadArray($array['params']);
$array['params'] = (string)$parameter;
}
return parent::bind($array, $ignore);
}

/**
* Overloaded load function
*
* @param int $pk primary key
* @param boolean $reset reset data
* @return boolean
* @see JTable:load
*/
public function load($pk = null, $reset = true)
{
if (parent::load($pk, $reset))
{
// Convert the params field to a registry.
$params = new JRegistry;
$params->loadJSON($this->params);
$this->params = $params;
return true;
}
else
{
return false;
}
}
/**
* Method to compute the default name of the asset.
* The default name is in the form `table_name.id`
* where id is the value of the primary key of the table.
*
* @return string
* @since 1.6
*/
protected function _getAssetName()
{
$k = $this->_tbl_key;
return 'com_helloworld.message.'.(int) $this->$k;
}

/**
* Method to return the title to use for the asset table.
*
* @return string
* @since 1.6
*/
protected function _getAssetTitle()
{
return $this->greeting;
}

/**
* Get the parent asset id for the record
*
* @return int
* @since 1.6
*/
protected function _getAssetParentId()
{
$asset = JTable::getInstance('Asset');
$asset->loadByName('com_helloworld');
return $asset->id;
}
}
</source>


== Packaging the component ==

Content of your code directory
* ''[[#helloworld.xml|helloworld.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_02#site/helloworld.php|site/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_02#site/controller.php|site/controller.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/views/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/views/helloworld/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_13#site/views/helloworld/view.html.php|site/views/helloworld/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/views/helloworld/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_06#site/views/helloworld/tmpl/default.xml|site/views/helloworld/tmpl/default.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_13#site/views/helloworld/tmpl/default.php|site/views/helloworld/tmpl/default.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/models/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_13#site/models/helloworld.php|site/models/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/language/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/language/en-GB/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_08#site/language/en-GB/en-GB.com_helloworld.ini|site/language/en-GB/en-GB.com_helloworld.ini]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/index.html]]''
* ''[[#admin/access.xml|admin/access.xml]]''
* ''[[#admin/config.xml|admin/config.xml]]''
* ''[[#admin/helloworld.php|admin/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_12#admin/controller.php|admin/controller.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/sql/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_13#admin/sql/install.mysql.utf8.sql|admin/sql/install.mysql.utf8.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_06#admin/sql/uninstall.mysql.utf8.sql|admin/sql/uninstall.mysql.utf8.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/sql/updates/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/sql/updates/mysql/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#admin/sql/updates/mysql/0.0.1.sql|admin/sql/updates/mysql/0.0.1.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_06#admin/sql/install.mysql.utf8.sql|admin/sql/updates/mysql/0.0.6.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_12#admin/sql/updates/mysql/0.0.12.sql|admin/sql/updates/mysql/0.0.12.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_13#admin/sql/updates/mysql/0.0.13.sql|admin/sql/updates/mysql/0.0.13.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/models/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/models/fields/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_12#admin/models/fields/helloworld.php|admin/models/fields/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/models/forms/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_13#admin/models/forms/helloworld.xml|admin/models/forms/helloworld.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_11#admin/models/forms/helloworld.js|admin/models/forms/helloworld.js]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/models/rules/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_11#admin/models/rules/greeting.php|admin/models/rules/greeting.php]]''
* ''[[#admin/models/helloworld.php|admin/models/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_09#admin/models/helloworlds.php|admin/models/helloworlds.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/views/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/views/helloworlds/index.html]]''
* ''[[#admin/views/helloworlds/view.html.php|admin/views/helloworlds/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/views/helloworlds/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_11#admin/views/helloworlds/tmpl/default.php|admin/views/helloworlds/tmpl/default.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_07#admin/views/helloworlds/tmpl/default_head.php|admin/views/helloworlds/tmpl/default_head.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_07#admin/views/helloworlds/tmpl/default_body.php|admin/views/helloworlds/tmpl/default_body.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_07#admin/views/helloworlds/tmpl/default_foot.php|admin/views/helloworlds/tmpl/default_foot.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/views/helloworld/index.html]]''
* ''[[#admin/views/helloworld/view.html.php|admin/views/helloworld/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_11#admin/views/helloworld/submitbutton.js|admin/views/helloworld/submitbutton.js]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/views/helloworld/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_13#admin/views/helloworld/tmpl/edit.php|admin/views/helloworld/tmpl/edit.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/helpers/index.html]]''
* ''[[#admin/helpers/helloworld.php|admin/helpers/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/tables/index.html]]''
* ''[[#admin/tables/helloworld.php|admin/tables/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_13#admin/language/en-GB/en-GB.com_helloworld.ini|admin/language/en-GB/en-GB.com_helloworld.ini]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_08#admin/language/en-GB/en-GB.com_helloworld.sys.ini|admin/language/en-GB/en-GB.com_helloworld.sys.ini]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/controllers/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_11#admin/controllers/helloworld.php|admin/controllers/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_11#admin/controllers/helloworlds.php|admin/controllers/helloworlds.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_08#language/en-GB/en-GB.ini|language/en-GB/en-GB.ini]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|media/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|media/images/index.html]]''
* ''media/images/tux-16x16.png''
* ''media/images/tux-48x48.png''

Create a compressed file of this directory or directly download the [http://joomlacode.org/gf/download/frsrelease/11394/58412/com_helloworld-1.6-part14.zip archive] and install it using the extension manager of Joomla!1.6. You can add a menu item of this component using the menu manager in the backend.


''helloworld.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="1.6.0" method="upgrade">

<name>COM_HELLOWORLD</name>

<creationDate>November 2009</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>

<version>0.0.14</version>

<description>COM_HELLOWORLD_DESCRIPTION</description>

<install> 
<sql>
<file driver="mysql" charset="utf8">sql/install.mysql.utf8.sql</file>
</sql>
</install>
<uninstall> 
<sql>
<file driver="mysql" charset="utf8">sql/uninstall.mysql.utf8.sql</file>
</sql>
</uninstall>
<update> 
<schemas>
<schemapath type="mysql">sql/updates/mysql</schemapath>
</schemas>
</update>



<files folder="site">
<filename>index.html</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>
<folder>views</folder>
<folder>models</folder>
<folder>language</folder>
</files>

<media destination="com_helloworld" folder="media">
<filename>index.html</filename>
<folder>images</folder>
</media>

<administration>

<menu img="../media/com_helloworld/images/tux-16x16.png">COM_HELLOWORLD_MENU</menu>


<files folder="admin">

<filename>index.html</filename>
<filename>config.xml</filename>
<filename>access.xml</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>

<folder>sql</folder>

<folder>tables</folder>

<folder>models</folder>

<folder>views</folder>

<folder>controllers</folder>

<folder>helpers</folder>
</files>

<languages folder="admin">
<language tag="en-GB">language/en-GB/en-GB.com_helloworld.ini</language>
<language tag="en-GB">language/en-GB/en-GB.com_helloworld.sys.ini</language>
</languages>
</administration>

</extension>
</source>


== Navigate ==

[[Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Part 13|Prev: Adding configuration]]
[[Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Part 15|Next: Adding an install/uninstall/update script file]]

== Contributors ==
*[[User:cdemko|Christophe Demko]]

[[Category:Development]]
[[category:Joomla! 1.6]]
[[category:Manual]]

Archived:Developing a MVC Component/Adding ACL

2011-02-02T19:34:41Z

Datashuttle: Reworded the "Restricting access to the component" paragraph.

This tutorial is for {{JVer|1.6}}

== Articles in this series ==
{{Chunk:Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Contents}}

== Introduction ==
This tutorial is part of the [[Developing a Model-View-Controller (MVC) Component for Joomla!1.6]] tutorial. You are encouraged to read the previous parts of the tutorial before reading this.

== Describing the ACL ==
Each component has its own ACL. They can be described in an ''access.xml'' file located at the root of the ''admin'' folder. This file describes the ACL for the com_helloworld component in a different section. In this example, we have chosen to separate the different ACL into two sections: components and messages.


''admin/access.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8" ?>
<access component="com_helloworld">
<section name="component">
<action name="core.admin" title="JACTION_ADMIN" description="JACTION_ADMIN_COMPONENT_DESC" />
<action name="core.manage" title="JACTION_MANAGE" description="JACTION_MANAGE_COMPONENT_DESC" />
<action name="core.create" title="JACTION_CREATE" description="JACTION_CREATE_COMPONENT_DESC" />
<action name="core.delete" title="JACTION_DELETE" description="JACTION_DELETE_COMPONENT_DESC" />
<action name="core.edit" title="JACTION_EDIT" description="JACTION_EDIT_COMPONENT_DESC" />
</section>
<section name="message">
<action name="core.delete" title="JACTION_DELETE" description="COM_HELLOWORLD_ACCESS_DELETE_DESC" />
<action name="core.edit" title="JACTION_EDIT" description="COM_HELLOWORLD_ACCESS_EDIT_DESC" />
</section>
</access>
</source>


== Restricting access to the component ==

The main idea in ACL is to restrict actions to groups of users. The first action to be restricted is access to the component itself. With your favorite file editor, edit the ''admin/helloworld.php'' file and it these lines


''admin/helloworld.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// Access check.
if (!JFactory::getUser()->authorise('core.manage', 'com_helloworld'))
{
return JError::raiseWarning(404, JText::_('JERROR_ALERTNOAUTHOR'));
}

// require helper file
JLoader::register('HelloWorldHelper', dirname(__FILE__) . DS . 'helpers' . DS . 'helloworld.php');

// import joomla controller library
jimport('joomla.application.component.controller');

// Get an instance of the controller prefixed by HelloWorld
$controller = JController::getInstance('HelloWorld');

// Perform the Request task
$controller->execute(JRequest::getCmd('task'));

// Redirect if set by the controller
$controller->redirect();

</source>


== Displaying only the right toolbar buttons ==

The toolbar buttons that have to displayed depends on the ACL rights.

In the ''admin/views/helloworlds/view.html.php'', put this code


''admin/views/helloworlds/view.html.php''
<source lang="php">
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// import Joomla view library
jimport('joomla.application.component.view');

/**
* HelloWorlds View
*/
class HelloWorldViewHelloWorlds extends JView
{
/**
* HelloWorlds view display method
* @return void
*/
function display($tpl = null)
{
// Get data from the model
$items = $this->get('Items');
$pagination = $this->get('Pagination');

// Check for errors.
if (count($errors = $this->get('Errors')))
{
JError::raiseError(500, implode(' ', $errors));
return false;
}
// Assign data to the view
$this->items = $items;
$this->pagination = $pagination;

// Set the toolbar
$this->addToolBar();

// Display the template
parent::display($tpl);

// Set the document
$this->setDocument();
}

/**
* Setting the toolbar
*/
protected function addToolBar()
{
$canDo = HelloWorldHelper::getActions();
JToolBarHelper::title(JText::_('COM_HELLOWORLD_MANAGER_HELLOWORLDS'), 'helloworld');
if ($canDo->get('core.create'))
{
JToolBarHelper::addNew('helloworld.add', 'JTOOLBAR_NEW');
}
if ($canDo->get('core.edit'))
{
JToolBarHelper::editList('helloworld.edit', 'JTOOLBAR_EDIT');
}
if ($canDo->get('core.delete'))
{
JToolBarHelper::deleteList('', 'helloworld.delete', 'JTOOLBAR_DELETE');
}
if ($canDo->get('core.admin'))
{
JToolBarHelper::divider();
JToolBarHelper::preferences('com_helloworld');
}
}
/**
* Method to set up the document properties
*
* @return void
*/
protected function setDocument()
{
$document = JFactory::getDocument();
$document->setTitle(JText::_('COM_HELLOWORLD_ADMINISTRATION'));
}
}
</source>


In the ''admin/views/helloworld/view.html.php'', put this code


''admin/views/helloworld/view.html.php''
<source lang="php">
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// import Joomla view library
jimport('joomla.application.component.view');

/**
* HelloWorld View
*/
class HelloWorldViewHelloWorld extends JView
{
/**
* display method of Hello view
* @return void
*/
public function display($tpl = null)
{
// get the Data
$form = $this->get('Form');
$item = $this->get('Item');
$script = $this->get('Script');

// Check for errors.
if (count($errors = $this->get('Errors')))
{
JError::raiseError(500, implode(' ', $errors));
return false;
}
// Assign the Data
$this->form = $form;
$this->item = $item;
$this->script = $script;

// Set the toolbar
$this->addToolBar();

// Display the template
parent::display($tpl);

// Set the document
$this->setDocument();
}

/**
* Setting the toolbar
*/
protected function addToolBar()
{
JRequest::setVar('hidemainmenu', true);
$user = JFactory::getUser();
$userId = $user->id;
$isNew = $this->item->id == 0;
$canDo = HelloWorldHelper::getActions($this->item->id);
JToolBarHelper::title($isNew ? JText::_('COM_HELLOWORLD_MANAGER_HELLOWORLD_NEW') : JText::_('COM_HELLOWORLD_MANAGER_HELLOWORLD_EDIT'), 'helloworld');
// Built the actions for new and existing records.
if ($isNew)
{
// For new records, check the create permission.
if ($canDo->get('core.create'))
{
JToolBarHelper::apply('helloworld.apply', 'JTOOLBAR_APPLY');
JToolBarHelper::save('helloworld.save', 'JTOOLBAR_SAVE');
JToolBarHelper::custom('helloworld.save2new', 'save-new.png', 'save-new_f2.png', 'JTOOLBAR_SAVE_AND_NEW', false);
}
JToolBarHelper::cancel('helloworld.cancel', 'JTOOLBAR_CANCEL');
}
else
{
if ($canDo->get('core.edit'))
{
// We can save the new record
JToolBarHelper::apply('helloworld.apply', 'JTOOLBAR_APPLY');
JToolBarHelper::save('helloworld.save', 'JTOOLBAR_SAVE');

// We can save this record, but check the create permission to see if we can return to make a new one.
if ($canDo->get('core.create'))
{
JToolBarHelper::custom('helloworld.save2new', 'save-new.png', 'save-new_f2.png', 'JTOOLBAR_SAVE_AND_NEW', false);
}
}
if ($canDo->get('core.create'))
{
JToolBarHelper::custom('helloworld.save2copy', 'save-copy.png', 'save-copy_f2.png', 'JTOOLBAR_SAVE_AS_COPY', false);
}
JToolBarHelper::cancel('helloworld.cancel', 'JTOOLBAR_CLOSE');
}
}
/**
* Method to set up the document properties
*
* @return void
*/
protected function setDocument()
{
$isNew = $this->item->id == 0;
$document = JFactory::getDocument();
$document->setTitle($isNew ? JText::_('COM_HELLOWORLD_HELLOWORLD_CREATING') : JText::_('COM_HELLOWORLD_HELLOWORLD_EDITING'));
$document->addScript(JURI::root() . $this->script);
$document->addScript(JURI::root() . "/administrator/components/com_helloworld/views/helloworld/submitbutton.js");
JText::script('COM_HELLOWORLD_HELLOWORLD_ERROR_UNACCEPTABLE');
}
}
</source>


These two files use the ''getActions'' method defined in the ''admin/helpers/helloworld.php'' file

In the ''admin/helpers/helloworld.php'', put this code


''admin/helpers/helloworld.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die;

/**
* HelloWorld component helper.
*/
abstract class HelloWorldHelper
{
/**
* Configure the Linkbar.
*/
public static function addSubmenu($submenu)
{
JSubMenuHelper::addEntry(JText::_('COM_HELLOWORLD_SUBMENU_MESSAGES'), 'index.php?option=com_helloworld', $submenu == 'messages');
JSubMenuHelper::addEntry(JText::_('COM_HELLOWORLD_SUBMENU_CATEGORIES'), 'index.php?option=com_categories&view=categories&extension=com_helloworld', $submenu == 'categories');
// set some global property
$document = JFactory::getDocument();
$document->addStyleDeclaration('.icon-48-helloworld {background-image: url(../media/com_helloworld/images/tux-48x48.png);}');
if ($submenu == 'categories')
{
$document->setTitle(JText::_('COM_HELLOWORLD_ADMINISTRATION_CATEGORIES'));
}
}
/**
* Get the actions
*/
public static function getActions($messageId = 0)
{
$user = JFactory::getUser();
$result = new JObject;

if (empty($messageId)) {
$assetName = 'com_helloworld';
}
else {
$assetName = 'com_helloworld.message.'.(int) $messageId;
}

$actions = array(
'core.admin', 'core.manage', 'core.create', 'core.edit', 'core.delete'
);

foreach ($actions as $action) {
$result->set($action, $user->authorise($action, $assetName));
}

return $result;
}
}
</source>


== Adding permissions settings in the component preferences ==
Since we now use ACL rights in our component, we need to set them at the component level.


''admin/config.xml''
<source lang="php">
<?xml version="1.0" encoding="utf-8"?>
<config>
<fieldset
name="greetings"
label="COM_HELLOWORLD_CONFIG_GREETING_SETTINGS_LABEL"
description="COM_HELLOWORLD_CONFIG_GREETING_SETTINGS_DESC"
>
<field
name="show_category"
type="radio"
label="COM_HELLOWORLD_HELLOWORLD_FIELD_SHOW_CATEGORY_LABEL"
description="COM_HELLOWORLD_HELLOWORLD_FIELD_SHOW_CATEGORY_DESC"
default="0"
>
<option value="0">JHIDE</option>
<option value="1">JSHOW</option>
</field>
</fieldset>
<fieldset
name="permissions"
label="JCONFIG_PERMISSIONS_LABEL"
description="JCONFIG_PERMISSIONS_DESC"
>
<field
name="rules"
type="rules"
label="JCONFIG_PERMISSIONS_LABEL"
class="inputbox"
validate="rules"
filter="rules"
component="com_helloworld"
section="component"
/>
</fieldset>
</config>
</source>


== Setting the value in the assets table ==

In order to set asset for each message, we have to do two things.

First, we precise that the 'core.edit' ACL right has to be taken from the message itself, then from the component


''admin/models/helloworld.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// import Joomla modelform library
jimport('joomla.application.component.modeladmin');

/**
* HelloWorld Model
*/
class HelloWorldModelHelloWorld extends JModelAdmin
{
/**
* Method override to check if you can edit an existing record.
*
* @param array $data An array of input data.
* @param string $key The name of the key for the primary key.
*
* @return boolean
* @since 1.6
*/
protected function allowEdit($data = array(), $key = 'id')
{
// Check specific edit permission then general edit permission.
return JFactory::getUser()->authorise('core.edit', 'com_helloworld.message.'.((int) isset($data[$key]) ? $data[$key] : 0)) or parent::allowEdit($data, $key);
}
/**
* Returns a reference to the a Table object, always creating it.
*
* @param type The table type to instantiate
* @param string A prefix for the table class name. Optional.
* @param array Configuration array for model. Optional.
* @return JTable A database object
* @since 1.6
*/
public function getTable($type = 'HelloWorld', $prefix = 'HelloWorldTable', $config = array())
{
return JTable::getInstance($type, $prefix, $config);
}
/**
* Method to get the record form.
*
* @param array $data Data for the form.
* @param boolean $loadData True if the form is to load its own data (default case), false if not.
* @return mixed A JForm object on success, false on failure
* @since 1.6
*/
public function getForm($data = array(), $loadData = true)
{
// Get the form.
$form = $this->loadForm('com_helloworld.helloworld', 'helloworld', array('control' => 'jform', 'load_data' => $loadData));
if (empty($form))
{
return false;
}
return $form;
}
/**
* Method to get the script that have to be included on the form
*
* @return string Script files
*/
public function getScript()
{
return 'administrator/components/com_helloworld/models/forms/helloworld.js';
}
/**
* Method to get the data that should be injected in the form.
*
* @return mixed The data for the form.
* @since 1.6
*/
protected function loadFormData()
{
// Check the session for previously entered form data.
$data = JFactory::getApplication()->getUserState('com_helloworld.edit.helloworld.data', array());
if (empty($data))
{
$data = $this->getItem();
}
return $data;
}
}
</source>


Second, we precise the asset name, asset title and asset parent in the helloworld table


''admin/tables/helloworld.php''
<source lang="php">
<?php
// No direct access
defined('_JEXEC') or die('Restricted access');

// import Joomla table library
jimport('joomla.database.table');

/**
* Hello Table class
*/
class HelloWorldTableHelloWorld extends JTable
{
/**
* Constructor
*
* @param object Database connector object
*/
function __construct(&$db)
{
parent::__construct('#__helloworld', 'id', $db);
}
/**
* Overloaded bind function
*
* @param array named array
* @return null|string null is operation was satisfactory, otherwise returns an error
* @see JTable:bind
* @since 1.5
*/
public function bind($array, $ignore = '')
{
if (isset($array['params']) && is_array($array['params']))
{
// Convert the params field to a string.
$parameter = new JRegistry;
$parameter->loadArray($array['params']);
$array['params'] = (string)$parameter;
}
return parent::bind($array, $ignore);
}

/**
* Overloaded load function
*
* @param int $pk primary key
* @param boolean $reset reset data
* @return boolean
* @see JTable:load
*/
public function load($pk = null, $reset = true)
{
if (parent::load($pk, $reset))
{
// Convert the params field to a registry.
$params = new JRegistry;
$params->loadJSON($this->params);
$this->params = $params;
return true;
}
else
{
return false;
}
}
/**
* Method to compute the default name of the asset.
* The default name is in the form `table_name.id`
* where id is the value of the primary key of the table.
*
* @return string
* @since 1.6
*/
protected function _getAssetName()
{
$k = $this->_tbl_key;
return 'com_helloworld.message.'.(int) $this->$k;
}

/**
* Method to return the title to use for the asset table.
*
* @return string
* @since 1.6
*/
protected function _getAssetTitle()
{
return $this->greeting;
}

/**
* Get the parent asset id for the record
*
* @return int
* @since 1.6
*/
protected function _getAssetParentId()
{
$asset = JTable::getInstance('Asset');
$asset->loadByName('com_helloworld');
return $asset->id;
}
}
</source>


== Packaging the component ==

Content of your code directory
* ''[[#helloworld.xml|helloworld.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_02#site/helloworld.php|site/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_02#site/controller.php|site/controller.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/views/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/views/helloworld/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_13#site/views/helloworld/view.html.php|site/views/helloworld/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/views/helloworld/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_06#site/views/helloworld/tmpl/default.xml|site/views/helloworld/tmpl/default.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_13#site/views/helloworld/tmpl/default.php|site/views/helloworld/tmpl/default.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/models/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_13#site/models/helloworld.php|site/models/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/language/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/language/en-GB/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_08#site/language/en-GB/en-GB.com_helloworld.ini|site/language/en-GB/en-GB.com_helloworld.ini]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/index.html]]''
* ''[[#admin/access.xml|admin/access.xml]]''
* ''[[#admin/config.xml|admin/config.xml]]''
* ''[[#admin/helloworld.php|admin/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_12#admin/controller.php|admin/controller.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/sql/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_13#admin/sql/install.mysql.utf8.sql|admin/sql/install.mysql.utf8.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_06#admin/sql/uninstall.mysql.utf8.sql|admin/sql/uninstall.mysql.utf8.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/sql/updates/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/sql/updates/mysql/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#admin/sql/updates/mysql/0.0.1.sql|admin/sql/updates/mysql/0.0.1.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_06#admin/sql/install.mysql.utf8.sql|admin/sql/updates/mysql/0.0.6.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_12#admin/sql/updates/mysql/0.0.12.sql|admin/sql/updates/mysql/0.0.12.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_13#admin/sql/updates/mysql/0.0.13.sql|admin/sql/updates/mysql/0.0.13.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/models/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/models/fields/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_12#admin/models/fields/helloworld.php|admin/models/fields/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/models/forms/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_13#admin/models/forms/helloworld.xml|admin/models/forms/helloworld.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_11#admin/models/forms/helloworld.js|admin/models/forms/helloworld.js]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/models/rules/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_11#admin/models/rules/greeting.php|admin/models/rules/greeting.php]]''
* ''[[#admin/models/helloworld.php|admin/models/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_09#admin/models/helloworlds.php|admin/models/helloworlds.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/views/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/views/helloworlds/index.html]]''
* ''[[#admin/views/helloworlds/view.html.php|admin/views/helloworlds/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/views/helloworlds/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_11#admin/views/helloworlds/tmpl/default.php|admin/views/helloworlds/tmpl/default.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_07#admin/views/helloworlds/tmpl/default_head.php|admin/views/helloworlds/tmpl/default_head.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_07#admin/views/helloworlds/tmpl/default_body.php|admin/views/helloworlds/tmpl/default_body.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_07#admin/views/helloworlds/tmpl/default_foot.php|admin/views/helloworlds/tmpl/default_foot.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/views/helloworld/index.html]]''
* ''[[#admin/views/helloworld/view.html.php|admin/views/helloworld/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_11#admin/views/helloworld/submitbutton.js|admin/views/helloworld/submitbutton.js]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/views/helloworld/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_13#admin/views/helloworld/tmpl/edit.php|admin/views/helloworld/tmpl/edit.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/helpers/index.html]]''
* ''[[#admin/helpers/helloworld.php|admin/helpers/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/tables/index.html]]''
* ''[[#admin/tables/helloworld.php|admin/tables/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_13#admin/language/en-GB/en-GB.com_helloworld.ini|admin/language/en-GB/en-GB.com_helloworld.ini]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_08#admin/language/en-GB/en-GB.com_helloworld.sys.ini|admin/language/en-GB/en-GB.com_helloworld.sys.ini]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/controllers/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_11#admin/controllers/helloworld.php|admin/controllers/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_11#admin/controllers/helloworlds.php|admin/controllers/helloworlds.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_08#language/en-GB/en-GB.ini|language/en-GB/en-GB.ini]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|media/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|media/images/index.html]]''
* ''media/images/tux-16x16.png''
* ''media/images/tux-48x48.png''

Create a compressed file of this directory or directly download the [http://joomlacode.org/gf/download/frsrelease/11394/58412/com_helloworld-1.6-part14.zip archive] and install it using the extension manager of Joomla!1.6. You can add a menu item of this component using the menu manager in the backend.


''helloworld.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="1.6.0" method="upgrade">

<name>COM_HELLOWORLD</name>

<creationDate>November 2009</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>

<version>0.0.14</version>

<description>COM_HELLOWORLD_DESCRIPTION</description>

<install> 
<sql>
<file driver="mysql" charset="utf8">sql/install.mysql.utf8.sql</file>
</sql>
</install>
<uninstall> 
<sql>
<file driver="mysql" charset="utf8">sql/uninstall.mysql.utf8.sql</file>
</sql>
</uninstall>
<update> 
<schemas>
<schemapath type="mysql">sql/updates/mysql</schemapath>
</schemas>
</update>



<files folder="site">
<filename>index.html</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>
<folder>views</folder>
<folder>models</folder>
<folder>language</folder>
</files>

<media destination="com_helloworld" folder="media">
<filename>index.html</filename>
<folder>images</folder>
</media>

<administration>

<menu img="../media/com_helloworld/images/tux-16x16.png">COM_HELLOWORLD_MENU</menu>


<files folder="admin">

<filename>index.html</filename>
<filename>config.xml</filename>
<filename>access.xml</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>

<folder>sql</folder>

<folder>tables</folder>

<folder>models</folder>

<folder>views</folder>

<folder>controllers</folder>

<folder>helpers</folder>
</files>

<languages folder="admin">
<language tag="en-GB">language/en-GB/en-GB.com_helloworld.ini</language>
<language tag="en-GB">language/en-GB/en-GB.com_helloworld.sys.ini</language>
</languages>
</administration>

</extension>
</source>


== Navigate ==

[[Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Part 13|Prev: Adding configuration]]
[[Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Part 15|Next: Adding an install/uninstall/update script file]]

== Contributors ==
*[[User:cdemko|Christophe Demko]]

[[Category:Development]]
[[category:Joomla! 1.6]]
[[category:Manual]]

Archived:Developing a MVC Component/Adding ACL

2011-02-02T19:31:40Z

Datashuttle: Reworded the "Describing the ACL" paragraph.

This tutorial is for {{JVer|1.6}}

== Articles in this series ==
{{Chunk:Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Contents}}

== Introduction ==
This tutorial is part of the [[Developing a Model-View-Controller (MVC) Component for Joomla!1.6]] tutorial. You are encouraged to read the previous parts of the tutorial before reading this.

== Describing the ACL ==
Each component has its own ACL. They can be described in an ''access.xml'' file located at the root of the ''admin'' folder. This file describes the ACL for the com_helloworld component in a different section. In this example, we have chosen to separate the different ACL into two sections: components and messages.


''admin/access.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8" ?>
<access component="com_helloworld">
<section name="component">
<action name="core.admin" title="JACTION_ADMIN" description="JACTION_ADMIN_COMPONENT_DESC" />
<action name="core.manage" title="JACTION_MANAGE" description="JACTION_MANAGE_COMPONENT_DESC" />
<action name="core.create" title="JACTION_CREATE" description="JACTION_CREATE_COMPONENT_DESC" />
<action name="core.delete" title="JACTION_DELETE" description="JACTION_DELETE_COMPONENT_DESC" />
<action name="core.edit" title="JACTION_EDIT" description="JACTION_EDIT_COMPONENT_DESC" />
</section>
<section name="message">
<action name="core.delete" title="JACTION_DELETE" description="COM_HELLOWORLD_ACCESS_DELETE_DESC" />
<action name="core.edit" title="JACTION_EDIT" description="COM_HELLOWORLD_ACCESS_EDIT_DESC" />
</section>
</access>
</source>


== Restricting access to the component ==

The main idea in ACL is to restrict actions to groups of users. The first action that have to be restricted is the access to the component. With your favorite file editor, edit the ''admin/helloworld.php'' file and it these lines


''admin/helloworld.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// Access check.
if (!JFactory::getUser()->authorise('core.manage', 'com_helloworld'))
{
return JError::raiseWarning(404, JText::_('JERROR_ALERTNOAUTHOR'));
}

// require helper file
JLoader::register('HelloWorldHelper', dirname(__FILE__) . DS . 'helpers' . DS . 'helloworld.php');

// import joomla controller library
jimport('joomla.application.component.controller');

// Get an instance of the controller prefixed by HelloWorld
$controller = JController::getInstance('HelloWorld');

// Perform the Request task
$controller->execute(JRequest::getCmd('task'));

// Redirect if set by the controller
$controller->redirect();

</source>


== Displaying only the right toolbar buttons ==

The toolbar buttons that have to displayed depends on the ACL rights.

In the ''admin/views/helloworlds/view.html.php'', put this code


''admin/views/helloworlds/view.html.php''
<source lang="php">
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// import Joomla view library
jimport('joomla.application.component.view');

/**
* HelloWorlds View
*/
class HelloWorldViewHelloWorlds extends JView
{
/**
* HelloWorlds view display method
* @return void
*/
function display($tpl = null)
{
// Get data from the model
$items = $this->get('Items');
$pagination = $this->get('Pagination');

// Check for errors.
if (count($errors = $this->get('Errors')))
{
JError::raiseError(500, implode(' ', $errors));
return false;
}
// Assign data to the view
$this->items = $items;
$this->pagination = $pagination;

// Set the toolbar
$this->addToolBar();

// Display the template
parent::display($tpl);

// Set the document
$this->setDocument();
}

/**
* Setting the toolbar
*/
protected function addToolBar()
{
$canDo = HelloWorldHelper::getActions();
JToolBarHelper::title(JText::_('COM_HELLOWORLD_MANAGER_HELLOWORLDS'), 'helloworld');
if ($canDo->get('core.create'))
{
JToolBarHelper::addNew('helloworld.add', 'JTOOLBAR_NEW');
}
if ($canDo->get('core.edit'))
{
JToolBarHelper::editList('helloworld.edit', 'JTOOLBAR_EDIT');
}
if ($canDo->get('core.delete'))
{
JToolBarHelper::deleteList('', 'helloworld.delete', 'JTOOLBAR_DELETE');
}
if ($canDo->get('core.admin'))
{
JToolBarHelper::divider();
JToolBarHelper::preferences('com_helloworld');
}
}
/**
* Method to set up the document properties
*
* @return void
*/
protected function setDocument()
{
$document = JFactory::getDocument();
$document->setTitle(JText::_('COM_HELLOWORLD_ADMINISTRATION'));
}
}
</source>


In the ''admin/views/helloworld/view.html.php'', put this code


''admin/views/helloworld/view.html.php''
<source lang="php">
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// import Joomla view library
jimport('joomla.application.component.view');

/**
* HelloWorld View
*/
class HelloWorldViewHelloWorld extends JView
{
/**
* display method of Hello view
* @return void
*/
public function display($tpl = null)
{
// get the Data
$form = $this->get('Form');
$item = $this->get('Item');
$script = $this->get('Script');

// Check for errors.
if (count($errors = $this->get('Errors')))
{
JError::raiseError(500, implode(' ', $errors));
return false;
}
// Assign the Data
$this->form = $form;
$this->item = $item;
$this->script = $script;

// Set the toolbar
$this->addToolBar();

// Display the template
parent::display($tpl);

// Set the document
$this->setDocument();
}

/**
* Setting the toolbar
*/
protected function addToolBar()
{
JRequest::setVar('hidemainmenu', true);
$user = JFactory::getUser();
$userId = $user->id;
$isNew = $this->item->id == 0;
$canDo = HelloWorldHelper::getActions($this->item->id);
JToolBarHelper::title($isNew ? JText::_('COM_HELLOWORLD_MANAGER_HELLOWORLD_NEW') : JText::_('COM_HELLOWORLD_MANAGER_HELLOWORLD_EDIT'), 'helloworld');
// Built the actions for new and existing records.
if ($isNew)
{
// For new records, check the create permission.
if ($canDo->get('core.create'))
{
JToolBarHelper::apply('helloworld.apply', 'JTOOLBAR_APPLY');
JToolBarHelper::save('helloworld.save', 'JTOOLBAR_SAVE');
JToolBarHelper::custom('helloworld.save2new', 'save-new.png', 'save-new_f2.png', 'JTOOLBAR_SAVE_AND_NEW', false);
}
JToolBarHelper::cancel('helloworld.cancel', 'JTOOLBAR_CANCEL');
}
else
{
if ($canDo->get('core.edit'))
{
// We can save the new record
JToolBarHelper::apply('helloworld.apply', 'JTOOLBAR_APPLY');
JToolBarHelper::save('helloworld.save', 'JTOOLBAR_SAVE');

// We can save this record, but check the create permission to see if we can return to make a new one.
if ($canDo->get('core.create'))
{
JToolBarHelper::custom('helloworld.save2new', 'save-new.png', 'save-new_f2.png', 'JTOOLBAR_SAVE_AND_NEW', false);
}
}
if ($canDo->get('core.create'))
{
JToolBarHelper::custom('helloworld.save2copy', 'save-copy.png', 'save-copy_f2.png', 'JTOOLBAR_SAVE_AS_COPY', false);
}
JToolBarHelper::cancel('helloworld.cancel', 'JTOOLBAR_CLOSE');
}
}
/**
* Method to set up the document properties
*
* @return void
*/
protected function setDocument()
{
$isNew = $this->item->id == 0;
$document = JFactory::getDocument();
$document->setTitle($isNew ? JText::_('COM_HELLOWORLD_HELLOWORLD_CREATING') : JText::_('COM_HELLOWORLD_HELLOWORLD_EDITING'));
$document->addScript(JURI::root() . $this->script);
$document->addScript(JURI::root() . "/administrator/components/com_helloworld/views/helloworld/submitbutton.js");
JText::script('COM_HELLOWORLD_HELLOWORLD_ERROR_UNACCEPTABLE');
}
}
</source>


These two files use the ''getActions'' method defined in the ''admin/helpers/helloworld.php'' file

In the ''admin/helpers/helloworld.php'', put this code


''admin/helpers/helloworld.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die;

/**
* HelloWorld component helper.
*/
abstract class HelloWorldHelper
{
/**
* Configure the Linkbar.
*/
public static function addSubmenu($submenu)
{
JSubMenuHelper::addEntry(JText::_('COM_HELLOWORLD_SUBMENU_MESSAGES'), 'index.php?option=com_helloworld', $submenu == 'messages');
JSubMenuHelper::addEntry(JText::_('COM_HELLOWORLD_SUBMENU_CATEGORIES'), 'index.php?option=com_categories&view=categories&extension=com_helloworld', $submenu == 'categories');
// set some global property
$document = JFactory::getDocument();
$document->addStyleDeclaration('.icon-48-helloworld {background-image: url(../media/com_helloworld/images/tux-48x48.png);}');
if ($submenu == 'categories')
{
$document->setTitle(JText::_('COM_HELLOWORLD_ADMINISTRATION_CATEGORIES'));
}
}
/**
* Get the actions
*/
public static function getActions($messageId = 0)
{
$user = JFactory::getUser();
$result = new JObject;

if (empty($messageId)) {
$assetName = 'com_helloworld';
}
else {
$assetName = 'com_helloworld.message.'.(int) $messageId;
}

$actions = array(
'core.admin', 'core.manage', 'core.create', 'core.edit', 'core.delete'
);

foreach ($actions as $action) {
$result->set($action, $user->authorise($action, $assetName));
}

return $result;
}
}
</source>


== Adding permissions settings in the component preferences ==
Since we now use ACL rights in our component, we need to set them at the component level.


''admin/config.xml''
<source lang="php">
<?xml version="1.0" encoding="utf-8"?>
<config>
<fieldset
name="greetings"
label="COM_HELLOWORLD_CONFIG_GREETING_SETTINGS_LABEL"
description="COM_HELLOWORLD_CONFIG_GREETING_SETTINGS_DESC"
>
<field
name="show_category"
type="radio"
label="COM_HELLOWORLD_HELLOWORLD_FIELD_SHOW_CATEGORY_LABEL"
description="COM_HELLOWORLD_HELLOWORLD_FIELD_SHOW_CATEGORY_DESC"
default="0"
>
<option value="0">JHIDE</option>
<option value="1">JSHOW</option>
</field>
</fieldset>
<fieldset
name="permissions"
label="JCONFIG_PERMISSIONS_LABEL"
description="JCONFIG_PERMISSIONS_DESC"
>
<field
name="rules"
type="rules"
label="JCONFIG_PERMISSIONS_LABEL"
class="inputbox"
validate="rules"
filter="rules"
component="com_helloworld"
section="component"
/>
</fieldset>
</config>
</source>


== Setting the value in the assets table ==

In order to set asset for each message, we have to do two things.

First, we precise that the 'core.edit' ACL right has to be taken from the message itself, then from the component


''admin/models/helloworld.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// import Joomla modelform library
jimport('joomla.application.component.modeladmin');

/**
* HelloWorld Model
*/
class HelloWorldModelHelloWorld extends JModelAdmin
{
/**
* Method override to check if you can edit an existing record.
*
* @param array $data An array of input data.
* @param string $key The name of the key for the primary key.
*
* @return boolean
* @since 1.6
*/
protected function allowEdit($data = array(), $key = 'id')
{
// Check specific edit permission then general edit permission.
return JFactory::getUser()->authorise('core.edit', 'com_helloworld.message.'.((int) isset($data[$key]) ? $data[$key] : 0)) or parent::allowEdit($data, $key);
}
/**
* Returns a reference to the a Table object, always creating it.
*
* @param type The table type to instantiate
* @param string A prefix for the table class name. Optional.
* @param array Configuration array for model. Optional.
* @return JTable A database object
* @since 1.6
*/
public function getTable($type = 'HelloWorld', $prefix = 'HelloWorldTable', $config = array())
{
return JTable::getInstance($type, $prefix, $config);
}
/**
* Method to get the record form.
*
* @param array $data Data for the form.
* @param boolean $loadData True if the form is to load its own data (default case), false if not.
* @return mixed A JForm object on success, false on failure
* @since 1.6
*/
public function getForm($data = array(), $loadData = true)
{
// Get the form.
$form = $this->loadForm('com_helloworld.helloworld', 'helloworld', array('control' => 'jform', 'load_data' => $loadData));
if (empty($form))
{
return false;
}
return $form;
}
/**
* Method to get the script that have to be included on the form
*
* @return string Script files
*/
public function getScript()
{
return 'administrator/components/com_helloworld/models/forms/helloworld.js';
}
/**
* Method to get the data that should be injected in the form.
*
* @return mixed The data for the form.
* @since 1.6
*/
protected function loadFormData()
{
// Check the session for previously entered form data.
$data = JFactory::getApplication()->getUserState('com_helloworld.edit.helloworld.data', array());
if (empty($data))
{
$data = $this->getItem();
}
return $data;
}
}
</source>


Second, we precise the asset name, asset title and asset parent in the helloworld table


''admin/tables/helloworld.php''
<source lang="php">
<?php
// No direct access
defined('_JEXEC') or die('Restricted access');

// import Joomla table library
jimport('joomla.database.table');

/**
* Hello Table class
*/
class HelloWorldTableHelloWorld extends JTable
{
/**
* Constructor
*
* @param object Database connector object
*/
function __construct(&$db)
{
parent::__construct('#__helloworld', 'id', $db);
}
/**
* Overloaded bind function
*
* @param array named array
* @return null|string null is operation was satisfactory, otherwise returns an error
* @see JTable:bind
* @since 1.5
*/
public function bind($array, $ignore = '')
{
if (isset($array['params']) && is_array($array['params']))
{
// Convert the params field to a string.
$parameter = new JRegistry;
$parameter->loadArray($array['params']);
$array['params'] = (string)$parameter;
}
return parent::bind($array, $ignore);
}

/**
* Overloaded load function
*
* @param int $pk primary key
* @param boolean $reset reset data
* @return boolean
* @see JTable:load
*/
public function load($pk = null, $reset = true)
{
if (parent::load($pk, $reset))
{
// Convert the params field to a registry.
$params = new JRegistry;
$params->loadJSON($this->params);
$this->params = $params;
return true;
}
else
{
return false;
}
}
/**
* Method to compute the default name of the asset.
* The default name is in the form `table_name.id`
* where id is the value of the primary key of the table.
*
* @return string
* @since 1.6
*/
protected function _getAssetName()
{
$k = $this->_tbl_key;
return 'com_helloworld.message.'.(int) $this->$k;
}

/**
* Method to return the title to use for the asset table.
*
* @return string
* @since 1.6
*/
protected function _getAssetTitle()
{
return $this->greeting;
}

/**
* Get the parent asset id for the record
*
* @return int
* @since 1.6
*/
protected function _getAssetParentId()
{
$asset = JTable::getInstance('Asset');
$asset->loadByName('com_helloworld');
return $asset->id;
}
}
</source>


== Packaging the component ==

Content of your code directory
* ''[[#helloworld.xml|helloworld.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_02#site/helloworld.php|site/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_02#site/controller.php|site/controller.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/views/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/views/helloworld/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_13#site/views/helloworld/view.html.php|site/views/helloworld/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/views/helloworld/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_06#site/views/helloworld/tmpl/default.xml|site/views/helloworld/tmpl/default.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_13#site/views/helloworld/tmpl/default.php|site/views/helloworld/tmpl/default.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/models/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_13#site/models/helloworld.php|site/models/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/language/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/language/en-GB/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_08#site/language/en-GB/en-GB.com_helloworld.ini|site/language/en-GB/en-GB.com_helloworld.ini]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/index.html]]''
* ''[[#admin/access.xml|admin/access.xml]]''
* ''[[#admin/config.xml|admin/config.xml]]''
* ''[[#admin/helloworld.php|admin/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_12#admin/controller.php|admin/controller.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/sql/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_13#admin/sql/install.mysql.utf8.sql|admin/sql/install.mysql.utf8.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_06#admin/sql/uninstall.mysql.utf8.sql|admin/sql/uninstall.mysql.utf8.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/sql/updates/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/sql/updates/mysql/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#admin/sql/updates/mysql/0.0.1.sql|admin/sql/updates/mysql/0.0.1.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_06#admin/sql/install.mysql.utf8.sql|admin/sql/updates/mysql/0.0.6.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_12#admin/sql/updates/mysql/0.0.12.sql|admin/sql/updates/mysql/0.0.12.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_13#admin/sql/updates/mysql/0.0.13.sql|admin/sql/updates/mysql/0.0.13.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/models/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/models/fields/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_12#admin/models/fields/helloworld.php|admin/models/fields/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/models/forms/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_13#admin/models/forms/helloworld.xml|admin/models/forms/helloworld.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_11#admin/models/forms/helloworld.js|admin/models/forms/helloworld.js]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/models/rules/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_11#admin/models/rules/greeting.php|admin/models/rules/greeting.php]]''
* ''[[#admin/models/helloworld.php|admin/models/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_09#admin/models/helloworlds.php|admin/models/helloworlds.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/views/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/views/helloworlds/index.html]]''
* ''[[#admin/views/helloworlds/view.html.php|admin/views/helloworlds/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/views/helloworlds/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_11#admin/views/helloworlds/tmpl/default.php|admin/views/helloworlds/tmpl/default.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_07#admin/views/helloworlds/tmpl/default_head.php|admin/views/helloworlds/tmpl/default_head.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_07#admin/views/helloworlds/tmpl/default_body.php|admin/views/helloworlds/tmpl/default_body.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_07#admin/views/helloworlds/tmpl/default_foot.php|admin/views/helloworlds/tmpl/default_foot.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/views/helloworld/index.html]]''
* ''[[#admin/views/helloworld/view.html.php|admin/views/helloworld/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_11#admin/views/helloworld/submitbutton.js|admin/views/helloworld/submitbutton.js]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/views/helloworld/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_13#admin/views/helloworld/tmpl/edit.php|admin/views/helloworld/tmpl/edit.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/helpers/index.html]]''
* ''[[#admin/helpers/helloworld.php|admin/helpers/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/tables/index.html]]''
* ''[[#admin/tables/helloworld.php|admin/tables/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_13#admin/language/en-GB/en-GB.com_helloworld.ini|admin/language/en-GB/en-GB.com_helloworld.ini]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_08#admin/language/en-GB/en-GB.com_helloworld.sys.ini|admin/language/en-GB/en-GB.com_helloworld.sys.ini]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/controllers/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_11#admin/controllers/helloworld.php|admin/controllers/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_11#admin/controllers/helloworlds.php|admin/controllers/helloworlds.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_08#language/en-GB/en-GB.ini|language/en-GB/en-GB.ini]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|media/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|media/images/index.html]]''
* ''media/images/tux-16x16.png''
* ''media/images/tux-48x48.png''

Create a compressed file of this directory or directly download the [http://joomlacode.org/gf/download/frsrelease/11394/58412/com_helloworld-1.6-part14.zip archive] and install it using the extension manager of Joomla!1.6. You can add a menu item of this component using the menu manager in the backend.


''helloworld.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="1.6.0" method="upgrade">

<name>COM_HELLOWORLD</name>

<creationDate>November 2009</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>

<version>0.0.14</version>

<description>COM_HELLOWORLD_DESCRIPTION</description>

<install> 
<sql>
<file driver="mysql" charset="utf8">sql/install.mysql.utf8.sql</file>
</sql>
</install>
<uninstall> 
<sql>
<file driver="mysql" charset="utf8">sql/uninstall.mysql.utf8.sql</file>
</sql>
</uninstall>
<update> 
<schemas>
<schemapath type="mysql">sql/updates/mysql</schemapath>
</schemas>
</update>



<files folder="site">
<filename>index.html</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>
<folder>views</folder>
<folder>models</folder>
<folder>language</folder>
</files>

<media destination="com_helloworld" folder="media">
<filename>index.html</filename>
<folder>images</folder>
</media>

<administration>

<menu img="../media/com_helloworld/images/tux-16x16.png">COM_HELLOWORLD_MENU</menu>


<files folder="admin">

<filename>index.html</filename>
<filename>config.xml</filename>
<filename>access.xml</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>

<folder>sql</folder>

<folder>tables</folder>

<folder>models</folder>

<folder>views</folder>

<folder>controllers</folder>

<folder>helpers</folder>
</files>

<languages folder="admin">
<language tag="en-GB">language/en-GB/en-GB.com_helloworld.ini</language>
<language tag="en-GB">language/en-GB/en-GB.com_helloworld.sys.ini</language>
</languages>
</administration>

</extension>
</source>


== Navigate ==

[[Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Part 13|Prev: Adding configuration]]
[[Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Part 15|Next: Adding an install/uninstall/update script file]]

== Contributors ==
*[[User:cdemko|Christophe Demko]]

[[Category:Development]]
[[category:Joomla! 1.6]]
[[category:Manual]]

Archived:Developing a MVC Component/Adding an install-uninstall-update script file

2011-02-02T19:17:47Z

Datashuttle: Removed the admin file reference to the script file. The reference is in the <scriptfile> tag. Was causing install problems.