Joomla! Documentation - User contributions [en]

Packaging a extension

2013-06-30T07:04:32Z

Burek: added a proper link for AppleDouble on Wikipedia

A directory with several loose files is not a convenient package for distribution. So the final step is to make a ''package''. This is a compressed archive containing the directory structure and all the files. The package can be in '''ZIP''' format (with a <tt>.zip</tt> extension), in '''TAR-gzip''' format (with a <tt>.tar.gz</tt> extension), or in '''TAR-bz2''' format (with a <tt>.tar.bz2</tt> extension).

If your template is in a directory <tt>mytemplate/</tt> then to make the package you can connect to that directory and use commands like:
* <tt>tar cvvzf ../mytemplate.tar.gz *</tt>
* <tt>zip -a -r ..\mytemplate.zip *.*</tt>

=== Note to Mac OS X users ===
Note to template developers using Mac OS X systems: the Finder's "compress" menu item produces a usable ZIP format package, but with one catch. It stores the files in [[AppleDouble]] format, adding extra files with names beginning with "<tt>._</tt>". Thus it adds a file named "<tt>._templateDetails.xml</tt>, which Joomla 1.5.x can sometimes misinterpret. The symptom is an error message, "XML Parsing Error at 1:1. Error 4: Empty document". The workaround is to compress from the command line, and set a shell environment variable "COPYFILE_DISABLE" to "true" before using "compress" or "tar". See the [http://en.wikipedia.org/wiki/AppleSingle_and_AppleDouble_formats AppleDouble] article for more information.

To set an environment variable on a Mac, open a terminal window and type:
export COPYFILE_DISABLE=true

Then in the same terminal window, change directories into where your template files reside and issue the zip command. For instance, if your template files have been built in a folder in your personal directory called myTemplate, then you would do the following:
cd myTemplate
zip -r myTemplate.zip *

[[Category:Extension development]]

J1.5:Plugin/Events/User

2012-10-24T14:30:09Z

Burek: moved TOC to the right for more convenient page display

{{RightTOC}}

In a standard installation of Joomla! 1.5 we have several predefined events which, when triggered, call functions in the associated plugins.

The user events are divided into two parts. First we have the events used while
authentication of a user takes place:
*onLoginUser
*onLogoutUser
*onAuthenticate
*onAuthenticateFailure

Second we have the events triggered during user management:
*onBeforeStoreUser
*onAfterStoreUser
*onBeforeDeleteUser
*onAfterDeleteUser

==onLoginUser==
===Description===
This event is triggered after the user is authenticated against the Joomla! user-base.

If you need to abort the login process (authentication), you will need to use [http://docs.joomla.org/Reference:User_Events_for_Plugin_System#5.3.4_onAuthenticate onAuthenticate] instead.

===Parameters===
* $user - an associative array of [http://api.joomla.org/Joomla-Framework/User/JAuthenticationResponse.html JAuthenticateResponse] type (see link for array keys)
* $options - an associative array containing these keys: ["remember"] => bool, ["return"] => string, ["entry_url"] => string

===Return Value===
Boolean
===Used in files===
*<tt>libraries/joomla/application/application.php</tt>
*<tt>plugins/user/joomla.php</tt>
===Examples===
*<tt>plugins/user/example.php</tt>

==onLogoutUser==
===Description===
This event is triggered before the user is logged out of the system. <del>If one plugin
returns false, the global logout fails.</del> (needs verification)

===Parameters===
* $credentials - an associative array containing these keys: ["username"] => string, ["id"] => int
* $options - an associative array containing this key: ["clientid"] => int

===Return Value===
Boolean
===Used in files===
*<tt>libraries/joomla/application/application.php</tt>
*<tt>plugins/user/joomla.php</tt>
===Examples===
*<tt>plugins/user/example.php</tt>

==onAuthenticate==
===Description===
This event is triggered to verify that a set of login credentials is valid.
===Parameters===
Array of credentials. Structure:\\
['username']\\
['password']\\
Alternative authentication mechanisms can supply additional credentials.

===Return Value===
An array of [[references:joomla.framework:user:jauthenticateresponse|JAuthenticateResponse]] objects detailing the results of each called plugin, including success or failure.
===Used in files===
*<tt>libraries/joomla/application/user/authentication.php</tt>
*<tt>plugins/authentication/gmail.php</tt>
*<tt>plugins/authentication/joomla.php</tt>
*<tt>plugins/authentication/ldap.php</tt>
===Examples===
*<tt>plugins/authentication/example.php</tt>

==onLoginFailure==
===Description===
This event is triggered whenever a user authentication request is failed by any plugin.
===Parameters===
Two parameters. The credentials array for the user (see onAuthenticate), and the
[[references:joomla.framework:user:jauthenticateresponse|JAuthenticateResponse]] that caused the failure.
===Return Value===
Unknown. The return value appears to be ignored in any case.
===Used in files===
*<tt>libraries/joomla/application/user/authentication.php</tt>

==onBeforeStoreUser==
===Description===
This event is triggered before an update of a user record.

Password in $user array is already hashed at this point. You may retrieve the cleartext password using $_POST['password'].

===Parameters===
* $user - An associative array of the columns in the user table (current values).
* $isnew - Boolean to identify if this is a new user (true - insert) or an existing one (false - update)
Note; You can retrieve the values that are about to get updated with JFactory::getUser();

===Return Value===
None
===Used in files===
*<tt>libraries/joomla/user/user.php</tt>
===Examples===
*<tt>plugins/user/example.php</tt>

==onAfterStoreUser==
===Description===
This event is triggered after an update of a user record, or when a new user has been stored in the database.

Password in $user array is already hashed at this point. You may retrieve the cleartext password using $_POST['password'].

===Parameters===
* '''$user''' - An associative array of the columns in the user table.
* '''$isnew''' - Boolean to identify if this is a new user (true - insert) or an existing one (false - update)
* '''$success''' - Boolean to identify if the store was successful
* '''$msg''' - Error message if store failed
Note: The old values that were just updated are not available here or afterwards. In case you need the old values, use onBeforeStoreUser().

===Return Value===
None
===Used in files===
*<tt>libraries/joomla/user/user.php</tt>
===Examples===
*<tt>plugins/user/example.php</tt>

==onBeforeDeleteUser==
===Description===
The event is triggered when a user is about to be deleted from the system.
===Parameters===
* $user - An associative array of the columns in the user table.

===Return Value===
None.
===Used in files===
*<tt>libraries/joomla/user/user.php</tt>
*<tt>plugins/user/joomla.php</tt>
===Examples===
*<tt>plugins/user/example.php</tt>

==onAfterDeleteUser==
===Description===
The event is triggered after a user has been deleted from the system.
===Parameters===
* $user - An associative array of the columns in the user table.
* $succes - Boolean to identify if the deletion was successful
* $msg - Error message if delete failed ([http://api.joomla.org/Joomla-Framework/Error/JError.html JError] object detailing the error, if any)

===Return Value===
None.
===Used in files===
*<tt>libraries/joomla/user/user.php</tt>
*<tt>plugins/user/joomla.php</tt>
===Examples===
*<tt>plugins/user/example.php</tt>

<noinclude>[[Category:Plugin Development]][[Category:Specifications]]</noinclude>

Archived talk:Developing a MVC Component/Developing a Basic Component

2012-05-17T22:46:01Z

Burek: /* Component name in manifestfile has to be conform */

== Component name in manifestfile has to be conform ==

In Joomla 1.6 the component name specified in the manifest file has to follow the pattern 'com_componentname'. So here it should be

<name>com_helloworld</name>

It will matter at least in the menu manager, where I discovered this problem.

== Archive is created for version 1.6 instead of 2.5 ==

In the section "''Packaging an installation zip file''", archive file offered as an example (located here: http://joomlacode.org/gf/download/frsrelease/11394/58225/com_helloworld-1.6-part01.zip) contains an XML file which has a line:

'''<extension type="component" version="1.6.0" method="upgrade">'''

instead of

'''<extension type="component" version="2.5.0" method="upgrade">'''

which should be fixed, I guess.

J1.5:Developing a MVC Component/Adding a Model

2012-02-08T06:01:28Z

Burek: /* Using the Model */

{{review}}
== Introduction ==

In the first tutorial of this series, creating a simple view-controller component using the Joomla! 1.5 CMS framework was demonstrated.

In the first tutorial, the greeting was hardcoded into the view. This doesn't follow the MVC pattern exactly because the view is intended to only display the data, and not contain it.

In this second part of the tutorial we will demonstrate how to move this out of the view and into a model. In future tutorials we will demonstrate the power and flexibility that this design pattern provides.

== Creating the Model ==

The concept of model gets its name because this class is intended to represent (or 'model') some entity. In our case, our first model will represent a 'hello', or a greeting. This is in line with our design thus far, because we have one view ('hello'), which is a view of our greeting.

The naming convention for models in the Joomla! framework is that the class name starts with the name of the component (in our case 'hello'), followed by 'model', followed by the model name. Therefore, our model class is called HelloModelHello.

At this point, we will only model one behaviour of our hello, and that is retrieving the greeting. We will thus have one method, called getGreeting(). It will simply return the string 'Hello, World!'.

The code for the model at site/models/hello.php:

<source lang="php"><?php
/**
* Hello Model for Hello World Component
*
* @package Joomla.Tutorials
* @subpackage Components
* @link http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_2
* @license GNU/GPL
*/

// No direct access

defined( '_JEXEC' ) or die( 'Restricted access' );

jimport( 'joomla.application.component.model' );

/**
* Hello Model
*
* @package Joomla.Tutorials
* @subpackage Components
*/
class HelloModelHello extends JModel
{
/**
* Gets the greeting
* @return string The greeting to be displayed to the user
*/
function getGreeting()
{
return 'Hello, World!';
}
}</source>

You will notice a line that starts with jimport. The jimport function is used to load files from the Joomla! framework that are required for our component. This particular statement will load the file /libraries/joomla/application/component/model.php. The '.'s are used as directory separators and the last part is the name of the file to load. All files are loaded relative to the libraries directory. This particular file contains the class definition for the JModel class, which is necessary because our model extends this class.

Now that we have created our model, we must modify our view so that it uses it to obtain the greeting.

== Using the Model ==

The Joomla! framework is setup in such a way that the controller will automatically load the model that has the same name as the view and will push it into the view. Since our view is called 'Hello', our 'Hello' model will automatically be loaded and pushed into the view. Therefore, we can easily retrieve a reference to our model using the JView::getModel() method. (If the model had not followed this convention, we could have passed the model name, as a parameter, to [http://api.joomla.org/Joomla-Framework/Application/JView.html#getModel JView::getModel()])

Our previous view code contained the lines:

<source lang="php">$greeting = "Hello World!";</source>

To take advantage of our model, we change this line to:

<source lang="php">$model = &$this->getModel();
$greeting = $model->getGreeting();</source>

The complete view now looks like:

<source lang="php"><?php
/**
* @package Joomla.Tutorials
* @subpackage Components
* @link http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_2
* @license GNU/GPL
*/

// No direct access

defined( '_JEXEC' ) or die( 'Restricted access' );

jimport( 'joomla.application.component.view');

/**
* HTML View class for the HelloWorld Component
*
* @package HelloWorld
*/

class HelloViewHello extends JView
{
function display($tpl = null)
{
$model = &$this->getModel();
$greeting = $model->getGreeting();
$this->assignRef( 'greeting', $greeting );

parent::display($tpl);
}
}</source>

=== Adding the File to the Package ===

All that remains is to add an entry to the XML file so that our new model will be copied. The Joomla! framework will look for our model in the models directory, so the entry for this file will look like (it should be added to the site section):

<source lang="php"><filename>models/hello.php</filename></source>

Our new hello.xml file will look like:

<source lang="xml"><?xml version="1.0" encoding="utf-8"?>
<install type="component" version="1.5.0">
<name>Hello</name>

<creationDate>2007-02-22</creationDate>
<author>John Doe</author>
<authorEmail>john.doe@example.org</authorEmail>
<authorUrl>http://www.example.org</authorUrl>
<copyright>Copyright Info</copyright>
<license>License Info</license>

<version>1.01</version>

<description>Description of the component ...</description>



<files folder="site">
<filename>controller.php</filename>
<filename>hello.php</filename>
<filename>index.html</filename>
<filename>models/hello.php</filename>
<filename>models/index.html</filename>
<filename>views/index.html</filename>
<filename>views/hello/index.html</filename>
<filename>views/hello/view.html.php</filename>
<filename>views/hello/tmpl/default.php</filename>
<filename>views/hello/tmpl/index.html</filename>
</files>

<administration>

<menu>Hello World!</menu>


<files folder="admin">
<filename>hello.php</filename>
<filename>index.html</filename>
</files>

</administration>
</install></source>

== Conclusion ==

We now have a simple MVC component. Each element is very simple at this point, but provides a great deal of flexibility and power.

== Articles in this Series ==
[[Developing a Model-View-Controller Component - Part 1]]

[[Developing a Model-View-Controller Component - Part 2 - Adding a Model]]

[[Developing a Model-View-Controller Component - Part 3 - Using the Database]]

[[Developing a Model-View-Controller Component - Part 4 - Creating an Administrator Interface]]

[[Developing a Model-View-Controller Component - Part 5 - Basic Backend Framework]]

[[Developing a Model-View-Controller Component - Part 6 - Adding Backend Actions]]

== Contributors ==
* staalanden

== Download ==

The component can be downloaded at: [http://joomlacode.org/gf/download/frsrelease/8109/29434/com_hello2_01.zip com_hello2_01]

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

J1.5:Developing a MVC Component/Adding a Model

2012-02-08T05:57:44Z

Burek: /* Creating the Model */

{{review}}
== Introduction ==

In the first tutorial of this series, creating a simple view-controller component using the Joomla! 1.5 CMS framework was demonstrated.

In the first tutorial, the greeting was hardcoded into the view. This doesn't follow the MVC pattern exactly because the view is intended to only display the data, and not contain it.

In this second part of the tutorial we will demonstrate how to move this out of the view and into a model. In future tutorials we will demonstrate the power and flexibility that this design pattern provides.

== Creating the Model ==

The concept of model gets its name because this class is intended to represent (or 'model') some entity. In our case, our first model will represent a 'hello', or a greeting. This is in line with our design thus far, because we have one view ('hello'), which is a view of our greeting.

The naming convention for models in the Joomla! framework is that the class name starts with the name of the component (in our case 'hello'), followed by 'model', followed by the model name. Therefore, our model class is called HelloModelHello.

At this point, we will only model one behaviour of our hello, and that is retrieving the greeting. We will thus have one method, called getGreeting(). It will simply return the string 'Hello, World!'.

The code for the model at site/models/hello.php:

<source lang="php"><?php
/**
* Hello Model for Hello World Component
*
* @package Joomla.Tutorials
* @subpackage Components
* @link http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_2
* @license GNU/GPL
*/

// No direct access

defined( '_JEXEC' ) or die( 'Restricted access' );

jimport( 'joomla.application.component.model' );

/**
* Hello Model
*
* @package Joomla.Tutorials
* @subpackage Components
*/
class HelloModelHello extends JModel
{
/**
* Gets the greeting
* @return string The greeting to be displayed to the user
*/
function getGreeting()
{
return 'Hello, World!';
}
}</source>

You will notice a line that starts with jimport. The jimport function is used to load files from the Joomla! framework that are required for our component. This particular statement will load the file /libraries/joomla/application/component/model.php. The '.'s are used as directory separators and the last part is the name of the file to load. All files are loaded relative to the libraries directory. This particular file contains the class definition for the JModel class, which is necessary because our model extends this class.

Now that we have created our model, we must modify our view so that it uses it to obtain the greeting.

== Using the Model ==

The Joomla! framework is setup in such a way that the controller will automatically load the model that has the same name as the view and will push it into the view. Since our view is called 'Hello', our 'Hello' model will automatically be loaded and pushed into the view. Therefore, we can easily retrieve a reference to our model using the JView::getModel() method. (If the model had not followed this convention, we could have passed the model name to [http://api.joomla.org/Joomla-Framework/Application/JView.html#getModel JView::getModel()])

Our previous view code contained the lines:

<source lang="php">$greeting = "Hello World!";</source>

To take advantage of our model, we change this line to:

<source lang="php">$model = &$this->getModel();
$greeting = $model->getGreeting();</source>

The complete view now looks like:

<source lang="php"><?php
/**
* @package Joomla.Tutorials
* @subpackage Components
* @link http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_2
* @license GNU/GPL
*/

// No direct access

defined( '_JEXEC' ) or die( 'Restricted access' );

jimport( 'joomla.application.component.view');

/**
* HTML View class for the HelloWorld Component
*
* @package HelloWorld
*/

class HelloViewHello extends JView
{
function display($tpl = null)
{
$model = &$this->getModel();
$greeting = $model->getGreeting();
$this->assignRef( 'greeting', $greeting );

parent::display($tpl);
}
}</source>

=== Adding the File to the Package ===

All that remains is to add an entry to the XML file so that our new model will be copied. The Joomla! framework will look for our model in the models directory, so the entry for this file will look like (it should be added to the site section):

<source lang="php"><filename>models/hello.php</filename></source>

Our new hello.xml file will look like:

<source lang="xml"><?xml version="1.0" encoding="utf-8"?>
<install type="component" version="1.5.0">
<name>Hello</name>

<creationDate>2007-02-22</creationDate>
<author>John Doe</author>
<authorEmail>john.doe@example.org</authorEmail>
<authorUrl>http://www.example.org</authorUrl>
<copyright>Copyright Info</copyright>
<license>License Info</license>

<version>1.01</version>

<description>Description of the component ...</description>



<files folder="site">
<filename>controller.php</filename>
<filename>hello.php</filename>
<filename>index.html</filename>
<filename>models/hello.php</filename>
<filename>models/index.html</filename>
<filename>views/index.html</filename>
<filename>views/hello/index.html</filename>
<filename>views/hello/view.html.php</filename>
<filename>views/hello/tmpl/default.php</filename>
<filename>views/hello/tmpl/index.html</filename>
</files>

<administration>

<menu>Hello World!</menu>


<files folder="admin">
<filename>hello.php</filename>
<filename>index.html</filename>
</files>

</administration>
</install></source>

== Conclusion ==

We now have a simple MVC component. Each element is very simple at this point, but provides a great deal of flexibility and power.

== Articles in this Series ==
[[Developing a Model-View-Controller Component - Part 1]]

[[Developing a Model-View-Controller Component - Part 2 - Adding a Model]]

[[Developing a Model-View-Controller Component - Part 3 - Using the Database]]

[[Developing a Model-View-Controller Component - Part 4 - Creating an Administrator Interface]]

[[Developing a Model-View-Controller Component - Part 5 - Basic Backend Framework]]

[[Developing a Model-View-Controller Component - Part 6 - Adding Backend Actions]]

== Contributors ==
* staalanden

== Download ==

The component can be downloaded at: [http://joomlacode.org/gf/download/frsrelease/8109/29434/com_hello2_01.zip com_hello2_01]

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

J1.5:Developing a MVC Component/Introduction

2012-01-29T19:33:51Z

Burek: /* View */

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

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

== Requirements ==
You need Joomla! 1.5 or greater for this tutorial.

== Introduction to Model-View-Controller ==
[[image:MVC basics.png|frameless|right]]While the idea behind a component may seem extremely simple, code can quickly become very complex as additional features are added or the interface is customized.

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

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

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

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

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

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

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

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

== Joomla! MVC Implementation ==
In Joomla!, the MVC pattern is implemented using three classes: [http://api.joomla.org/Joomla-Framework/Application/JModel.html JModel], [http://api.joomla.org/Joomla-Framework/Application/JView.html JView] and [http://api.joomla.org/Joomla-Framework/Application/JController.html JController]. For more detailed information about these classes, please refer to the API reference documentation (WIP).

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

== Creating a Component ==
For our basic component, we only require five files:

* site/hello.php - this is the entry point to our component
* site/controller.php - this file contains our base controller
* site/views/hello/view.html.php - this file retrieves the necessary data and pushes it into the template
* site/views/hello/tmpl/default.php - this is the template for our output
* hello.xml - this is an XML (manifest) file that tells Joomla! how to install our component.

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

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

=== Naming conventions ===

Main article: [[Naming conventions]]

At this point it is important to say that some words are reserved for using in component or its class names, and violating some of that will produce a hard for debugging error. One of them is "view" (in any character case) for view class (subclass of JView) and controller class (subclass of JController), because view class need to have first part of name the same as controller class name, and component name (although violating of last one won't produce an error, it's just a useful convention).

All filenames and foldernames for models, views and controllers must be lower-case in order to operate well on Unix/Linux-systems.

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

<source lang="php">index.php?option=com_hello&view=hello</source>

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

The code for this file is fairly typical across components.

site/hello.php:
<source lang="php"><?php
/**
* @package Joomla.Tutorials
* @subpackage Components
* components/com_hello/hello.php
* @link http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_1
* @license GNU/GPL
*/

// No direct access
defined( '_JEXEC' ) or die( 'Restricted access' );

// Require the base controller

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

// Require specific controller if requested
if($controller = JRequest::getWord('controller')) {
$path = JPATH_COMPONENT.DS.'controllers'.DS.$controller.'.php';
if (file_exists($path)) {
require_once $path;
} else {
$controller = '';
}
}

// Create the controller
$classname = 'HelloController'.$controller;
$controller = new $classname( );

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

// Redirect if set by the controller
$controller->redirect();</source>

The first statement is a security check.

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

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

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

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

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

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

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

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

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

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

The code for the base controller site/controller.php is:
<source lang="php"><?php
/**
* @package Joomla.Tutorials
* @subpackage Components
* @link http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_1
* @license GNU/GPL
*/

// No direct access

defined( '_JEXEC' ) or die( 'Restricted access' );

jimport('joomla.application.component.controller');

/**
* Hello World Component Controller
*
* @package Joomla.Tutorials
* @subpackage Components
*/
class HelloController extends JController
{
/**
* Method to display the view
*
* @access public
*/
function display()
{
parent::display();
}

}</source>

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

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

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

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

=== Creating the View ===
The task of the view is very simple: It retrieves the data to be displayed and pushes it into the template. Data is pushed into the template using the JView::assignRef method.
<small>(Note: The key (the first argument) passed to the assignRef method cannot be preceded by an underscore i.e. $this->assignRef('_greeting',$greeting). Doing so will cause the assignRef method to return false and your variable will not be pushed into the template.)</small>

The code for the view at site/views/hello/view.html.php:

<source lang="php"><?php
/**
* @package Joomla.Tutorials
* @subpackage Components
* @link http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_1
* @license GNU/GPL
*/

// no direct access

defined( '_JEXEC' ) or die( 'Restricted access' );

jimport( 'joomla.application.component.view');

/**
* HTML View class for the HelloWorld Component
*
* @package HelloWorld
*/

class HelloViewHello extends JView
{
function display($tpl = null)
{
$greeting = "Hello World!";
$this->assignRef( 'greeting', $greeting );

parent::display($tpl);
}
}</source>

==== Creating the Template ====

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

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

<source lang="php"><?php

// No direct access

defined('_JEXEC') or die('Restricted access'); ?>
<h1><?php echo $this->greeting; ?></h1></source>

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

* basic descriptive details about your component (i.e. name), and optionally, a description, copyright and license information.
* a list of files that need to be copied.
* optionally, a PHP file that performs additional install and uninstall operations.
* optionally, an SQL file which contains database queries that should be executed upon install/uninstall

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

<source lang="xml"><?xml version="1.0" encoding="utf-8"?>
<install type="component" version="1.5.0">
<name>Hello</name>

<creationDate>2007-02-22</creationDate>
<author>John Doe</author>
<authorEmail>john.doe@example.org</authorEmail>
<authorUrl>http://www.example.org</authorUrl>
<copyright>Copyright Info</copyright>
<license>License Info</license>

<version>1.01</version>

<description>Description of the component ...</description>



<files folder="site">
<filename>controller.php</filename>
<filename>hello.php</filename>
<filename>index.html</filename>
<filename>views/index.html</filename>
<filename>views/hello/index.html</filename>
<filename>views/hello/view.html.php</filename>
<filename>views/hello/tmpl/default.php</filename>
<filename>views/hello/tmpl/index.html</filename>
</files>

<administration>

<menu>Hello World!</menu>


<files folder="admin">
<filename>hello.php</filename>
<filename>index.html</filename>
</files>

</administration>
</install></source>

{{notice|
Put this xml file, also called manifest, in the root of your package (because the installer will take its path as the root path for all other files).{{1}}Don't include itself under <files>...}}

You may have noticed the manifest source above mentioned files we have not discussed. These are the index.html files and the admin files. An index.html file is placed in each directory to prevent prying users from getting a directory listing. If there is no index.html file, some web servers will list the directory contents. This is often undesirable. These files have the simple line:

<source lang="php"><html><body bgcolor="#FFFFFF"></body></html></source>

It will simply display a blank page.

The hello.php file in the admin folder is the entry point for the our component's admin section. Since our component has no administrator needs (yet), this file will have the same content as the index.html files for now.

If you've followed along, you can visit URL index.php?option=com_hello to see your work. To do this, zip up the main folder and install via the extensions manager. If it still does not work, download the package at the bottom of this page and install for a working example.

== Articles in this Series ==
[[Developing a Model-View-Controller Component - Part 1]]

[[Developing a Model-View-Controller Component - Part 2 - Adding a Model]]

[[Developing a Model-View-Controller Component - Part 3 - Using the Database]]

[[Developing a Model-View-Controller Component - Part 4 - Creating an Administrator Interface]]

[[Developing a Model-View-Controller Component - Part 5 - Basic Backend Framework]]

[[Developing a Model-View-Controller Component - Part 6 - Adding Backend Actions]]

== Contributors ==
* mjaz
* staalanden
* dannystaple
* Stilgar
* presto

== Download ==
The component can be downloaded at: [http://joomlacode.org/gf/download/frsrelease/8108/29433/com_hello1_01.zip com_hello1_01]

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

J1.5 talk:Creating an Authentication Plugin for Joomla

2009-11-16T16:25:25Z

Burek:

A google search on 'joomla onauthenticate example' returns this tutorial so I suspect many people tasked with configuring a Joomla! 1.5 system to authenticate a user login against a database external to Joomla's will no doubt arrive here and use the code presented as a starting point to implementing their own auth plugin. At least that is what happend to me!

In this tutorial it says that the example is based on example.php, which can be found in the plugins/authentication directory of your Joomla installation.

After scratching my head and wondering if I could be any dumber than I already am, I noted the following differences between the code in the tutorial and the code in the plugins/authentication/example.php file in my Joomla 1.5.13 installation.

In fact, the code is so different that it may explain why I have had so much trouble implementing the simple process of authenticating against a table in another MySQL database on the same machine.

Would someone be so kind as to confirm that these differences are problematic or deconfuse me on this issue? Please bear in mind that I'm a perl guy drowning in php.

There are two issues:

1. The constructors for the plugin are defined differently.

Tutorial:

function plgAuthenticationMyauth(& $subject) {
parent::__construct($subject);
}

example.php:

function plgAuthenticationExample(& $subject, $config)
{
parent::__construct($subject, $config);
}

2. The definitions of the parameters that onAuthenticate expects are different.

Tutorial:

The onAuthenticate() method is the method that will be called when the system is trying to use your plugin to authenticate the user. This method will be passed three parameters: the username, the password, and a reference to an object of type JAuthenticationResponse

/**
* This method should handle any authentication and report back to the subject
* This example uses simple authentication - it checks if the password is the reverse
* of the username (and the user exists in the database).
*
* @access public
* @param string $username Username for authentication
* @param string $password Password for authentication
* @param object $response Authentication response object
* @return boolean
* @since 1.5
*/

function onAuthenticate( $username, $password, &$response )

example.php:

/**
* This method should handle any authentication and report back to the subject
*
* @access public
* @param array $credentials Array holding the user credentials
* @param array $options Array of extra options
* @param object $response Authentication response object
* @return boolean
* @since 1.5
*/

function onAuthenticate( $credentials, $options, &$response )

== Invalid link ==

The link to http://api.joomla.org/Joomla-Framework/User/JAuthenticationResponse.html is not displayed correctly.

J1.5 talk:Creating an Authentication Plugin for Joomla

2009-11-16T16:25:03Z

Burek: /* Invalid link */ new section

A google search on 'joomla onauthenticate example' returns this tutorial so I suspect many people tasked with configuring a Joomla! 1.5 system to authenticate a user login against a database external to Joomla's will no doubt arrive here and use the code presented as a starting point to implementing their own auth plugin. At least that is what happend to me!

In this tutorial it says that the example is based on example.php, which can be found in the plugins/authentication directory of your Joomla installation.

After scratching my head and wondering if I could be any dumber than I already am, I noted the following differences between the code in the tutorial and the code in the plugins/authentication/example.php file in my Joomla 1.5.13 installation.

In fact, the code is so different that it may explain why I have had so much trouble implementing the simple process of authenticating against a table in another MySQL database on the same machine.

Would someone be so kind as to confirm that these differences are problematic or deconfuse me on this issue? Please bear in mind that I'm a perl guy drowning in php.

There are two issues:

1. The constructors for the plugin are defined differently.

Tutorial:

function plgAuthenticationMyauth(& $subject) {
parent::__construct($subject);
}

example.php:

function plgAuthenticationExample(& $subject, $config)
{
parent::__construct($subject, $config);
}

2. The definitions of the parameters that onAuthenticate expects are different.

Tutorial:

The onAuthenticate() method is the method that will be called when the system is trying to use your plugin to authenticate the user. This method will be passed three parameters: the username, the password, and a reference to an object of type JAuthenticationResponse

/**
* This method should handle any authentication and report back to the subject
* This example uses simple authentication - it checks if the password is the reverse
* of the username (and the user exists in the database).
*
* @access public
* @param string $username Username for authentication
* @param string $password Password for authentication
* @param object $response Authentication response object
* @return boolean
* @since 1.5
*/

function onAuthenticate( $username, $password, &$response )

example.php:

/**
* This method should handle any authentication and report back to the subject
*
* @access public
* @param array $credentials Array holding the user credentials
* @param array $options Array of extra options
* @param object $response Authentication response object
* @return boolean
* @since 1.5
*/

function onAuthenticate( $credentials, $options, &$response )

The link to http://api.joomla.org/Joomla-Framework/User/JAuthenticationResponse.html is not displayed correctly.

== Invalid link ==

The link to http://api.joomla.org/Joomla-Framework/User/JAuthenticationResponse.html is not displayed correctly.

J1.5 talk:Creating an Authentication Plugin for Joomla

2009-11-16T16:24:47Z

Burek:

A google search on 'joomla onauthenticate example' returns this tutorial so I suspect many people tasked with configuring a Joomla! 1.5 system to authenticate a user login against a database external to Joomla's will no doubt arrive here and use the code presented as a starting point to implementing their own auth plugin. At least that is what happend to me!

In this tutorial it says that the example is based on example.php, which can be found in the plugins/authentication directory of your Joomla installation.

After scratching my head and wondering if I could be any dumber than I already am, I noted the following differences between the code in the tutorial and the code in the plugins/authentication/example.php file in my Joomla 1.5.13 installation.

In fact, the code is so different that it may explain why I have had so much trouble implementing the simple process of authenticating against a table in another MySQL database on the same machine.

Would someone be so kind as to confirm that these differences are problematic or deconfuse me on this issue? Please bear in mind that I'm a perl guy drowning in php.

There are two issues:

1. The constructors for the plugin are defined differently.

Tutorial:

function plgAuthenticationMyauth(& $subject) {
parent::__construct($subject);
}

example.php:

function plgAuthenticationExample(& $subject, $config)
{
parent::__construct($subject, $config);
}

2. The definitions of the parameters that onAuthenticate expects are different.

Tutorial:

The onAuthenticate() method is the method that will be called when the system is trying to use your plugin to authenticate the user. This method will be passed three parameters: the username, the password, and a reference to an object of type JAuthenticationResponse

/**
* This method should handle any authentication and report back to the subject
* This example uses simple authentication - it checks if the password is the reverse
* of the username (and the user exists in the database).
*
* @access public
* @param string $username Username for authentication
* @param string $password Password for authentication
* @param object $response Authentication response object
* @return boolean
* @since 1.5
*/

function onAuthenticate( $username, $password, &$response )

example.php:

/**
* This method should handle any authentication and report back to the subject
*
* @access public
* @param array $credentials Array holding the user credentials
* @param array $options Array of extra options
* @param object $response Authentication response object
* @return boolean
* @since 1.5
*/

function onAuthenticate( $credentials, $options, &$response )

The link to http://api.joomla.org/Joomla-Framework/User/JAuthenticationResponse.html is not displayed correctly.

J1.5 talk:Developing a MVC Component/Using the Database

2009-07-21T09:09:27Z

Burek:

Although it is mentioned in the article, I think it is important to underline where the install.sql and uninstall.sql files have to be placed:

install.sql and uninstall.sql files have to be mentioned in two places:
* In one of the file sections. For example:
<files folder="admin">
<filename>...</filename>
<filename>...</filename>
<filename>install.sql</filename>
<filename>uninstall.sql</filename>
</files>
* In the ''install'' / ''uninstall'' sections.

Of course, the files have to be copied in the correct folder (in the example, it should be the ''admin'' folder).

When data is read from a database, it can be retrieved in the class constructor:

// The constructor accesses the database, and retrieves all properties.
function __construct($config = array()) {
parent::__construct($config); // To transmit configuration to parent class.
$db =& JFactory::getDBO();
$query = 'SELECT greeting FROM #__hello';
$db->setQuery( $query );
$this->greeting = $db->loadResult();
}
// The private property
var $greeting;
// The public property accessor
function getGreeting() {
return $this->greeting;
}

/* 2009-07-21 */
* Are those file names for "install.utf8.sql" and "uninstall.utf8.sql" correctly written into XML file? I see files "install.sql" and "uninstall.sql", but in the text, there says the files will be named "install.utf8.sql" and "uninstall.utf8.sql"?

J1.5 talk:Developing a MVC Component/Using the Database

2009-07-21T09:08:33Z

Burek:

Although it is mentioned in the article, I think it is important to underline where the install.sql and uninstall.sql files have to be placed:

install.sql and uninstall.sql files have to be mentioned in two places:
* In one of the file sections. For example:
<files folder="admin">
<filename>...</filename>
<filename>...</filename>
<filename>install.sql</filename>
<filename>uninstall.sql</filename>
</files>
* In the ''install'' / ''uninstall'' sections.

Of course, the files have to be copied in the correct folder (in the example, it should be the ''admin'' folder).

When data is read from a database, it can be retrieved in the class constructor:

// The constructor accesses the database, and retrieves all properties.
function __construct($config = array()) {
parent::__construct($config); // To transmit configuration to parent class.
$db =& JFactory::getDBO();
$query = 'SELECT greeting FROM #__hello';
$db->setQuery( $query );
$this->greeting = $db->loadResult();
}
// The private property
var $greeting;
// The public property accessor
function getGreeting() {
return $this->greeting;
}

Are those file names for "install.utf8.sql" and "uninstall.utf8.sql" correctly written into XML file? I see files "install.sql" and "uninstall.sql", but in the text, there says the files will be named "install.utf8.sql" and "uninstall.utf8.sql"?