Joomla! Documentation - User contributions [en]

Sending email from extensions

2010-01-21T13:32:43Z

Hasse bjork:

This is an example of how to send an email from a component. You would typically put this into your components controller.

=== Fetch the mail object ===
A reference to the global mail object (JMail) is fetched through the JFactory object. This is the object creating our mail.

<source lang="php">
$mailer =& JFactory::getMailer();
</source>

=== Set a sender ===
The sender of an email is set with [http://api.joomla.org/Joomla-Framework/Mail/JMail.html#setSender setSender]. The function takes an array with an email address and a name as an argument. We fetch the sites email address and name from the global configuration. These are set in the administration back-end (Global Configuration -> Server -> Mail Settings).

<source lang="php">
$config =& JFactory::getConfig();
$sender = array(
$config->getValue( 'config.mailfrom' ),
$config->getValue( 'config.fromname' ) );

$mailer->setSender($sender);
</source>

=== Recipient ===
You set the recipient of an email with the function [http://api.joomla.org/Joomla-Framework/Mail/JMail.html# addRecipient].
To set the email address to the currently logged in user, we fetch it from the user object.

<source lang="php">
$user =& JFactory::getUser();
$recipient = $user->email;

$mailer->addRecipient($recipient);
</source>

If we had multiple recipients we would put each recipients email address in an array.

<source lang="php">
$recipient = array( 'person1@domain.com', 'person2@domain.com', 'person3@domain.com' );

$mailer->addRecipient($recipient);
</source>

=== Create the mail ===
We need to set a subject line and create the text body. The subject is set with [http://api.joomla.org/Joomla-Framework/Mail/JMail.html#setSubject setSubject].

The easy way to create an email body is as a string with plain text. Use the function [http://api.joomla.org/Joomla-Framework/Mail/JMail.html#setBody setBody] to add a message to the mail body. You can also attach a file with [http://api.joomla.org/Joomla-Framework/Mail/JMail.html#addAttachment addAttachment]. It takes a single file name or an array of file names as argument.

<source lang="php">
$body = "Your body string\nin double quotes if you want to parse the \nnewlines etc";
$mailer->setSubject('Your subject string');
$mailer->setBody($body);
// Optional file attached
$mailer->addAttachment(PATH_COMPONENT.DS.'assets'.DS.'document.pdf');
</source>

If you prefer to format your email in HTML, you need to tell the mailer it is HTML. This is done with [http://api.joomla.org/Unknown/PHPMailer.html#methodIsHTML IsHTML]. The subject line and any attachments are handled as above, with the exception of images embedded in the HTML. These are taken care of with the function [http://api.joomla.org/Unknown/PHPMailer.html#AddEmbeddedImage AddEmbeddedImage].

<source lang="php">
$body = '<h2>Our mail</h2>'
. '<div>A message to our dear readers'
. '<img src="cid:logo_id" alt="logo"/></div>';
$mailer->isHTML(true);
$mailer->setBody($body);
// Optionally add embedded image
$mailer->AddEmbeddedImage( PATH_COMPONENT.DS.'assets'.DS.'logo128.jpg', 'logo_id', 'logo.jpg', 'base64', 'image/jpeg' );
</source>

Normally you would leave any images on your server and refer to them with an ordinary HTML image tag, to reduce size of the mail and the time sending it.

=== Sending the mail ===

The mail is sent with the function [http://api.joomla.org/Joomla-Framework/Mail/JMail.html#Send Send]. It returns '''true''' on success or a JError object.

<source lang="php">
$send =& $mailer->Send();
if ( $send !== true ) {
echo 'Error sending email: ' . $send->message;
} else {
echo 'Mail sent';
}
</source>

You would probably want to write your own error handler, if there is an error sending the mail.

The JMail object is used for sending mail in Joomlas contact manager. See the file joomla/components/com_contact/controller.php

===See also===
* [http://docs.joomla.org/JFactory/getMailer Docs on JFactory->getMailer]
* [http://api.joomla.org/Joomla-Framework/JFactory.html#getMailer JFactory->getMailer on api.joomla.org]

Sending email from extensions

2010-01-21T13:08:25Z

Hasse bjork: Added attachements

This is an example of how to send an email from a component. You would typically put this into your components controller.

=== Fetch the mail object ===
A reference to the global mail object (JMail) is fetched through the JFactory object. This is the object creating our mail.

<source lang="php">
$mailer =& JFactory::getMailer();
</source>

=== Set a sender ===
The mailer expect the sender to be an array of an email address and a name. We fetch the sites email address and name from the configuration. These are set in the administration back-end (Global Configuration -> Server -> Mail Settings).

<source lang="php">
$config =& JFactory::getConfig();
$sender = array(
$config->getValue( 'config.mailfrom' ),
$config->getValue( 'config.fromname' ) );

$mailer->setSender($sender);
</source>

=== Recipient ===
The currently logged in users email address is stored in the user object.

<source lang="php">
$user =& JFactory::getUser();
$recipient = $user->email;

$mailer->addRecipient($recipient);
</source>

If we had multiple recipients we would put each recipients email in an array.

<source lang="php">
$recipient = array( 'person1@domain.com', 'person2@domain.com', 'person3@domain.com' );

$mailer->addRecipient($recipient);
</source>

=== Create the mail ===
We need to set a subject line and create the text body. The subject is set with [http://api.joomla.org/Joomla-Framework/Mail/JMail.html#setSubject setSubject].

The easy way to create an email body is as a string with plain text. Use the function [http://api.joomla.org/Joomla-Framework/Mail/JMail.html#setBody setBody] to add a message to the mail body. You can also attach a file with [http://api.joomla.org/Joomla-Framework/Mail/JMail.html#addAttachment addAttachment]. It takes a single file name or an array of file names as argument.

<source lang="php">
$body = "Your body string\nin double quotes if you want to parse the \nnewlines etc";
$mailer->setSubject('Your subject string');
$mailer->setBody($body);
// Optional file attached
$mailer->addAttachment(PATH_COMPONENT.DS.'assets'.DS.'document.pdf');
</source>

If you prefer to format your email in HTML, you need to tell the mailer it is HTML. This is done with [http://api.joomla.org/Unknown/PHPMailer.html#methodIsHTML IsHTML]. The subject line and any attachments are handled as above, with the exception of images embedded in the HTML. These are taken care of with the function [http://api.joomla.org/Unknown/PHPMailer.html#AddEmbeddedImage AddEmbeddedImage].

<source lang="php">
$body = '<h2>Our mail</h2>'
. '<div>A message to our dear readers'
. '<img src="cid:logo_id" alt="logo"/></div>';
$mailer->isHTML(true);
$mailer->setBody($body);
// Optionally add embedded image
$mailer->AddEmbeddedImage( PATH_COMPONENT.DS.'assets'.DS.'logo128.jpg', 'logo_id', 'logo.jpg', 'base64', 'image/jpeg' );
</source>

Normally you would leave any images on your server and refer to them with an ordinary HTML image tag, to reduce size of the mail and the time sending it.

=== Sending the mail ===

<source lang="php">
$send = $mailer->Send();
if ( $send !== true ) {
echo 'Error sending email: ' . $send->message;
} else {
echo 'Mail sent';
}
</source>

You would probably want to write your own error handler, if there is an error sending the mail.

The JMail object is used for sending mail in Joomlas contact manager. See the file joomla/components/com_contact/controller.php

===See also===
* [http://docs.joomla.org/JFactory/getMailer Docs on JFactory->getMailer]
* [http://api.joomla.org/Joomla-Framework/JFactory.html#getMailer JFactory->getMailer on api.joomla.org]

Sending email from extensions

2010-01-21T11:58:48Z

Hasse bjork: Complete rewrite

Sending email from extensions

2010-01-21T10:28:37Z

Hasse bjork: Added link to "Docs JFactory->getMailer" and tagge source as php

This works to send an email to the currently logged in user when used in a function in a model for a component and called from a view:
<source lang="php">
$user =& JFactory::getUser();
$message =& JFactory::getMailer();
$message->addRecipient($user->email);
$message->setSubject('Your subject string');
$message->setBody("Your body string\nin double quotes if you want to parse the \nnewlines etc");
$sender = array( 'sender@email.address.org', 'Sender Name' );
$message->setSender($sender);
$sent = $message->send();
if ($sent != 1) echo 'Error sending email';
</source>

===See also===
* [http://docs.joomla.org/JFactory/getMailer Docs on JFactory->getMailer]

Accessing the database using JDatabase

2010-01-15T13:26:28Z

Hasse bjork: Added <source lang="php"> to code

J1.5:Ajax client code using MooTools

2010-01-13T09:07:12Z

Hasse bjork: Removed redundant curly bracket in javascript code

In a typical Ajax application you will want to pull some data from a server, which could be your own Joomla site or a remote web service, and update some element on the web page with the data returned by the server. There are three elements to a typical Ajax implementation:
* An HTML element whose change of state will trigger the Ajax request.
* Another HTML element where the response data will be placed. Often this will show an "Ajax loading" icon or message while the response from the server is being awaited.
* The Ajax JavaScript code itself.

Starting with the first of these, you need to identify the element on the page that will trigger the Ajax request. The element needs to be identified by a unique <tt>id</tt> attribute. For example, suppose you have a drop-down select box on your page and you want to do an Ajax request whenever the user changes the item selected. Then you must ensure that the select element has a unique <tt>id</tt> attribute like this:
<source lang="html4strict">
<select name="drop-down" id="drop-down">
<option value="1">Item 1</option>
<option value="2">Item 2</option>
<option value="3">Item 3</option>
</select>
</source>
You can generate this select list programmatically using the [[JHTML]] class like this:
<source lang="php">
<?php
$options = array();
$options[] = JHTML::_( 'select.option', '1', 'Item 1' );
$options[] = JHTML::_( 'select.option', '2', 'Item 2' );
$options[] = JHTML::_( 'select.option', '3', 'Item 3' );
echo JHTML::_( 'select.genericlist', $options, 'drop-down' );
</source>
Secondly, you need to add an HTML element that will hold the output from the Ajax call. This could be a suitably-placed DIV, which must also have a unique <tt>id</tt> attribute, like this:
<source lang="html4strict">
<div id="ajax-container"></div>
</source>
You can, of course, use the <tt>id</tt> in a selector to style the output using CSS.

Thirdly, you need to add the JavaScript code that will make the Ajax request and place the response into the screen output. You generally don't need to be concerned about loading MooTools itself as this is done automatically for you by Joomla, but sometimes you need to do this manually by adding the following code:
<source lang="php">
<?php
JHTML::_( 'behavior.mootools' );
</source>
There are many ways to add JavaScript code to the output from Joomla. One way, which avoids complex quoting, is to use the PHP "heredoc" syntax (see [http://uk.php.net/manual/en/language.types.string.php#language.types.string.syntax.heredoc] for more details) like this:
<source lang="php">
<?php
$ajax = <<<EOD
/* <![CDATA[ */
Your JavaScript code goes here.
/* ]]> */
EOD;

$doc = & JFactory::getDocument();
$doc->addScriptDeclaration( $ajax );
</source>
Wrapping the JavaScript code between <tt>/* <![CDATA[ */</tt> and <tt>/* ]]> */</tt> allows the JavaScript to be output without causing problems with HTML validators.

You can embed PHP variables in the heredoc text by surrounding them with braces, like this:
<source lang="php">
<?php
$ajax = <<<EOD
/* <![CDATA[ */
This is some JavaScript code with {$this->embedded} PHP variable in it.
/* ]]> */
EOD;

$doc = & JFactory::getDocument();
$doc->addScriptDeclaration( $ajax );
</source>

The JavaScript code must add an event handler to the element that will trigger the Ajax call. This is done in MooTools using the following call:
<source lang="javascript">
window.addEvent( 'domready', function() {

$('drop-down').addEvent( 'change', <function-declaration> );

});
</source>
where <function-declaration> is the JavaScript code that is to be called when the state of the element identified as <tt>drop-down</tt> is changed. Notice that you should always delay the call to <tt>addEvent</tt> until the DOM is ready following a page load. This is done by telling <tt>window.addEvent</tt> to hang the Ajax addEvent function onto the onDomReady event.

You don't have to hang the Ajax call on the onChange event; for example, you could use onClick as the trigger.

The <function-declaration> that you will add will be an instantiation of the MooTools Ajax class, looking something like this:
<source lang="javascript">
var a = new Ajax( {$url}, {
method: 'get',
update: $('ajax-container')
}).request();
</source>
where <tt>{$url}</tt> is a PHP variable containing the URL for the Ajax request. In this example the <tt>update</tt> argument has been used to copy the entire response from the server into the <tt>ajax-container</tt> element. This is quick and convenient, but very often you will want to process the response in some way before showing it to the user. Commonly, the response is JSON-encoded and you must decode the response and format it appropriately before updating <tt>ajax-container</tt>. To do this, use the <tt>onComplete</tt> argument to the <tt>Ajax</tt> object rather than the <tt>update</tt> argument.
<source lang="javascript">
var a = new Ajax( {$url}, {
method: 'get',
onComplete: <completion-function>
}).request();
</source>
where <completion-function> is a JavaScript function that will be called when a response from the remote server is received. Typically, this function will process the raw data from the server before pushing it into the <tt>ajax-container</tt> element.

The following is a more complete example of an Ajax function which receives data from the server in JSON format, decodes it, then pushes data from the response into <tt>ajax-container</tt>.
<source lang="javascript">
window.addEvent( 'domready', function() {

$('drop-down').addEvent( 'change', function() {

$('ajax-container').empty().addClass('ajax-loading');

var a = new Ajax( {$url}, {
method: 'get',
onComplete: function( response ) {
var resp = Json.evaluate( response );

// Other code to execute when the request completes.

$('ajax-container').removeClass('ajax-loading').setHTML( output );

}
}).request();
});
});
</source>
Notice that in this example there is also some code to add, and subsequently remove, an <tt>ajax-loading</tt> CSS class from the <tt>ajax-container</tt> element. Typically, the presence of this class will cause a "spinner" graphic element to be loaded as a background image to make the user aware that the system is still alive.
<noinclude>[[Category:Development]]</noinclude>

J1.5:Component parameters

2009-12-18T14:17:55Z

Hasse bjork: /* 3. 'Article' specific parameters */

==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 must 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.

<noinclude>[[Category:Development]][[Category:Components]][[Category:Parameters]]</noinclude>

Archived talk:Creating a file uploader in your component

2009-12-14T11:12:59Z

Hasse bjork:

Hi

Implementing the SWFUpload Application demo for my component. The joomla document explains only the simple demo (http://docs.joomla.org/Creating_a_file_uploader_in_your_component )

what are the changes i have to do from the joomla doc. How i rewrite the thumbnail picture function for joomla 1.5

I tried so many time but not works out

<?php
// This script accepts an ID and looks in the user's session for stored thumbnail data.
// It then streams the data to the browser as an image

// Work around the Flash Player Cookie Bug
if (isset($_POST["PHPSESSID"])) {
session_id($_POST["PHPSESSID"]);
}

session_start();

$image_id = isset($_GET["id"]) ? $_GET["id"] : false;

if ($image_id === false) {
header("HTTP/1.1 500 Internal Server Error");
echo "No ID";
exit(0);
}

if (!is_array($_SESSION["file_info"]) || !isset($_SESSION["file_info"][$image_id])) {
header("HTTP/1.1 404 Not found");
exit(0);
}

header("Content-type: image/jpeg") ;
header("Content-Length: ".strlen($_SESSION["file_info"][$image_id]));
echo $_SESSION["file_info"][$image_id];
exit(0);
?>

Pls help

Regards
Gopi

== Changed PHP script in Part 5 ==

I made some changes to my own work, before using it. Some tests to use JFile versions and the code is shorter. Return value '''true''' on success or else '''false''' if there was an error.
<source lang="php">
jimport('joomla.filesystem.file');
jimport('joomla.filesystem.folder');

$fieldName = 'file_upload';
$fileTemp = $_FILES[$fieldName]['tmp_name'];
$fileName = JFile::makeSafe( $_FILES[$fieldName]['name'] );
$fileExt = strtolower( JFile::getExt( $fileName ) );
$imageinfo = getimagesize( $fileTemp );
$mimetypes = array( 'image/jpeg', 'image/pjpeg', 'image/png', 'image/x-png', 'image/gif' );
$uploadPath = JPATH_COMPONENT . DS . 'images' . DS . $fileName;

switch ( $_FILES[$fieldName]['error'] ) {
case 1:
echo JText::_( 'FILE LARGER THAN PHP INI ALLOW' );
return false;

case 2:
echo JText::_( 'FILE LARGER THAN HTML FORM ALLOW' );
return false;

case 3:
echo JText::_( 'ERROR PARTIAL UPLOAD' );
return false;

case 4:
echo JText::_( 'ERROR NO FILE' );
return false;

default:
}

if ( $_FILES[$fieldName]['size'] > 2000000 ) {
echo JText::_( 'FILE BIGGER THAN 2MB' );
}

if ( !in_array( $fileExt, explode(',', 'jpeg,jpg,png,gif') ) ) {
echo JText::_( 'INVALID EXTENSION' );
return false;
} else if ( !in_array( $imageinfo['mime'], $mimetypes ) ) {
echo JText::_( 'INVALID FILE TYPE' );
return false;
} else if ( !is_int( $imageinfo[0] ) || !is_int( $imageinfo[0] ) ) {
echo JText::_( 'INVALID FILE SIZE' );
return false;
}

if( !JFile::upload( $fileTemp, $uploadPath ) ) {
echo JText::_( 'ERROR MOVING FILE' );
return false;
}
return true;
</source>

Regards
hasse_bjork

Archived talk:Creating a file uploader in your component

2009-12-14T11:10:39Z

Hasse bjork:

Hi

Implementing the SWFUpload Application demo for my component. The joomla document explains only the simple demo (http://docs.joomla.org/Creating_a_file_uploader_in_your_component )

what are the changes i have to do from the joomla doc. How i rewrite the thumbnail picture function for joomla 1.5

I tried so many time but not works out

<?php
// This script accepts an ID and looks in the user's session for stored thumbnail data.
// It then streams the data to the browser as an image

// Work around the Flash Player Cookie Bug
if (isset($_POST["PHPSESSID"])) {
session_id($_POST["PHPSESSID"]);
}

session_start();

$image_id = isset($_GET["id"]) ? $_GET["id"] : false;

if ($image_id === false) {
header("HTTP/1.1 500 Internal Server Error");
echo "No ID";
exit(0);
}

if (!is_array($_SESSION["file_info"]) || !isset($_SESSION["file_info"][$image_id])) {
header("HTTP/1.1 404 Not found");
exit(0);
}

header("Content-type: image/jpeg") ;
header("Content-Length: ".strlen($_SESSION["file_info"][$image_id]));
echo $_SESSION["file_info"][$image_id];
exit(0);
?>

Pls help

Regards
Gopi

A few comments on Part 5 and the PHP script

I changed some tests to use JFile versions and shortened the code. Return value '''true''' on success or else '''false''' if there was an error.
<source lang="php">
jimport('joomla.filesystem.file');
jimport('joomla.filesystem.folder');

$fieldName = 'file_upload';
$fileTemp = $_FILES[$fieldName]['tmp_name'];
$fileName = JFile::makeSafe( $_FILES[$fieldName]['name'] );
$fileExt = strtolower( JFile::getExt( $fileName ) );
$imageinfo = getimagesize( $fileTemp );
$mimetypes = array( 'image/jpeg', 'image/pjpeg', 'image/png', 'image/x-png', 'image/gif' );
$uploadPath = JPATH_COMPONENT . DS . 'images' . DS . $fileName;

switch ( $_FILES[$fieldName]['error'] ) {
case 1:
echo JText::_( 'FILE LARGER THAN PHP INI ALLOW' );
return false;

case 2:
echo JText::_( 'FILE LARGER THAN HTML FORM ALLOW' );
return false;

case 3:
echo JText::_( 'ERROR PARTIAL UPLOAD' );
return false;

case 4:
echo JText::_( 'ERROR NO FILE' );
return false;

default:
}

if ( $_FILES[$fieldName]['size'] > 2000000 ) {
echo JText::_( 'FILE BIGGER THAN 2MB' );
}

if ( !in_array( $fileExt, explode(',', 'jpeg,jpg,png,gif') ) ) {
echo JText::_( 'INVALID EXTENSION' );
return false;
} else if ( !in_array( $imageinfo['mime'], $mimetypes ) ) {
echo JText::_( 'INVALID FILE TYPE' );
return false;
} else if ( !is_int( $imageinfo[0] ) || !is_int( $imageinfo[0] ) ) {
echo JText::_( 'INVALID FILE SIZE' );
return false;
}

if( !JFile::upload( $fileTemp, $uploadPath ) ) {
echo JText::_( 'ERROR MOVING FILE' );
return false;
}
return true;
</source>

Archived:Creating a file uploader in your component

2009-12-14T10:51:40Z

Hasse bjork: /* Part 5: Recieveing The File With PHP */

== Creating a file uploader in your component: Method 1, SWFUpload ==

=== Part 1: Introduction ===

SWFUpload is a free open source multiple file uploader available for download from http://swfupload.org/

A demo of swfupload is available here: http://demo.swfupload.org/v220/simpledemo/index.php

The standard way to upload a file is with a HTML form. This works great if you are uploading one file, but browsers do not let you select and upload more than one file at a time.

The most common way of selecting multiple files for upload is to use flash and javascript. The flash part of the script opens up a select file dialog where multiple files can be selected, and the flash/javascript sends each file, and recieves the response from the server.

The most popular scripts used to do this are SWFUpload and Fancy upload (http://digitarald.de/project/fancyupload/). The flash uploader in Joomla's media manager is based on Fancy Upload version 1.0. As Fancy upload 2.0 and 3.0 use mootools 1.2, and Joomla 1.5 uses mootools 1.11, we can not use Fancy Upload 2.0/3.0 in the admin pages of Joomla. Fancy Upload 1.0 could be used, but it is not updated or supported anymore.

SWFUpload does not use Mootools or Jquery. Because of this it will likely work on any page with Mootools 1.11 (Joomla 1.5), or Mootools 1.2 (Joomla 1.6). Therefore we will be using SWFUpload in this article.

Download ths latest version of SWFUpload from the download page (http://code.google.com/p/swfupload/). Download the SWFUpload v2.2.0.1 Samples.zip file.

Inside the file there will be a demos folder, and inside that a simpledemo folder. This is the example we are going to integrate into a Joomla component.

This tutorial assumes you have followed the http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_1 tutorial and are familiar with Joomla's MVC structure.

----

=== Part 2: Adding The External Javascript ===

We need to add in the external links in the head of the document, put some javascript into the head of the doc, and put some HTML in our body.

If you look at the simpledemo/index.php page you will see links to 5 files in the head of the page.

Make a folder within the root of your components folder called swfupload, copy the ../css/default.css, ../swfupload/swfupload.js, js/swfupload.queue.js, js/fileprogress.js and js/handlers.js files into this folder.

We also need to copy the ../swfupload/swfupload.swf and images/TestImageNoText_65x29.png files into this folder.

Within your view.html.php file add in the following code:
<source lang="php">
//get the hosts name
jimport('joomla.environment.uri' );
$host = JURI::root();

//add the links to the external files into the head of the webpage (note the 'administrator' in the path, which is not nescessary if you are in the frontend)
$document =& JFactory::getDocument();
$document->addScript($host.'administrator/components/com_mycomponent/swfupload/swfupload.js');
$document->addScript($host.'administrator/components/com_mycomponent/swfupload/swfupload.queue.js');
$document->addScript($host.'administrator/components/com_mycomponent/swfupload/fileprogress.js');
$document->addScript($host.'administrator/components/com_mycomponent/swfupload/handlers.js');
$document->addStyleSheet($host.'administrator/components/com_mycomponent/swfupload/default.css');
</source>
That is the external files part done. We still have to add in the head javascript, and the body html.

----
=== Part 3: Adding The Head Javascript ===

Head javascript part:
The javascript below is almost the same as the javascript from the simple demo, the few modifications are commented. It is nescessary to read through it and change the parts (such as task) that are relevant to your component.
<source lang="php">
//when we send the files for upload, we have to tell Joomla our session, or we will get logged out
$session = & JFactory::getSession();

$swfUploadHeadJs ='
var swfu;

window.onload = function()
{

var settings =
{
//this is the path to the flash file, you need to put your components name into it
flash_url : "'.$host.'administrator/components/com_mycomponent/swfupload/swfupload.swf",

//we can not put any vars into the url for complicated reasons, but we can put them into the post...
upload_url: "index.php",
post_params:
{
"option" : "com_mycomponent",
"controller" : "mycontroller",
"task" : "mytask",
"id" : "'.$myItemObject->id.'",
"'.$session->getName().'" : "'.$session->getId().'",
"format" : "raw"
},
//you need to put the session and the "format raw" in there, the other ones are what you would normally put in the url
file_size_limit : "5 MB",
//client side file chacking is for usability only, you need to check server side for security
file_types : "*.jpg;*.jpeg;*.gif;*.png",
file_types_description : "All Files",
file_upload_limit : 100,
file_queue_limit : 100,
custom_settings :
{
progressTarget : "fsUploadProgress",
cancelButtonId : "btnCancel"
},
debug: false,

// Button settings
button_image_url: "'.$host.'administrator/components/com_mycomponent/swfupload/images/TestImageNoText_65x29.png",
button_width: "85",
button_height: "29",
button_placeholder_id: "spanButtonPlaceHolder",
button_text: \'<span class="theFont">Choose Files</span>\',
button_text_style: ".theFont { font-size: 13; }",
button_text_left_padding: 5,
button_text_top_padding: 5,

// The event handler functions are defined in handlers.js
file_queued_handler : fileQueued,
file_queue_error_handler : fileQueueError,
file_dialog_complete_handler : fileDialogComplete,
upload_start_handler : uploadStart,
upload_progress_handler : uploadProgress,
upload_error_handler : uploadError,
upload_success_handler : uploadSuccess,
upload_complete_handler : uploadComplete,
queue_complete_handler : queueComplete // Queue plugin event
};
swfu = new SWFUpload(settings);
};

';

//add the javascript to the head of the html document
$document->addScriptDeclaration($swfUploadHeadJs);
</source>
If you want more info on what each paramater is, have a look at the swfupload docs:
http://demo.swfupload.org/Documentation/

----

=== Part 4: Adding The Body HTML ===

We still have to add in our body HTML, in you tmpl/default.php file add in:
<source lang="html4strict">
<div id="swfuploader">
<form id="form1" action="index.php" method="post" enctype="multipart/form-data">
<fieldset class="adminform">

<div class="fieldset flash" id="fsUploadProgress">
<span class="legend">Upload Queue</span>
</div>
<div id="divStatus">0 Files Uploaded</div>
<div>
<span id="spanButtonPlaceHolder"></span>
<input id="btnCancel" type="button" value="Cancel All Uploads" onclick="swfu.cancelQueue();" disabled="disabled" style="margin-left: 2px; font-size: 8pt; height: 29px;" />

</div>
</fieldset>
</form>
</div>
</source>
If all has gone well, you will be able to upload files to your components script, although nothing will happen on the server as there is no PHP to recieve the image.

=== Part 5: Recieveing The File With PHP ===

It is worth noting that allowing users to upload files to the server is possibly the most dangerous thing to do in terms of security, and if someone with malicious intentions manages to upload a php file to your server, then they can easily take control of the site.

It is recommeneded you do some reading on file upload security. This is a good start:

http://www.scanit.be/uploads/php-file-upload.pdf

And there are many other good resources on the internet. It is important you understand how file upload security works, rather than copying and pasting some code that checks the MIME type, and assuming the script is safe.

Here is some example PHP that will check if the file is an image, and upload it. It is not an exhaustive example of security checking, but it is a good start:
<source lang="php">
//import joomlas filesystem functions, we will do all the filewriting with joomlas functions,
//so if the ftp layer is on, joomla will write with that, not the apache user, which might
//not have the correct permissions
jimport('joomla.filesystem.file');
jimport('joomla.filesystem.folder');

//this is the name of the field in the html form, filedata is the default name for swfupload
//so we will leave it as that
$fieldName = 'Filedata';

//any errors the server registered on uploading
$fileError = $_FILES[$fieldName]['error'];
if ($fileError > 0)
{
switch ($fileError)
{
case 1:
echo JText::_( 'FILE TO LARGE THAN PHP INI ALLOWS' );
return;

case 2:
echo JText::_( 'FILE TO LARGE THAN HTML FORM ALLOWS' );
return;

case 3:
echo JText::_( 'ERROR PARTIAL UPLOAD' );
return;

case 4:
echo JText::_( 'ERROR NO FILE' );
return;
}
}

//check for filesize
$fileSize = $_FILES[$fieldName]['size'];
if($fileSize > 2000000)
{
echo JText::_( 'FILE BIGGER THAN 2MB' );
}

//check the file extension is ok
$fileName = $_FILES[$fieldName]['name'];
$uploadedFileNameParts = explode('.',$fileName);
$uploadedFileExtension = array_pop($uploadedFileNameParts);

$validFileExts = explode(',', 'jpeg,jpg,png,gif');

//assume the extension is false until we know its ok
$extOk = false;

//go through every ok extension, if the ok extension matches the file extension (case insensitive)
//then the file extension is ok
foreach($validFileExts as $key => $value)
{
if( preg_match("/$value/i", $uploadedFileExtension ) )
{
$extOk = true;
}
}

if ($extOk == false)
{
echo JText::_( 'INVALID EXTENSION' );
return;
}

//the name of the file in PHP's temp directory that we are going to move to our folder
$fileTemp = $_FILES[$fieldName]['tmp_name'];

//for security purposes, we will also do a getimagesize on the temp file (before we have moved it
//to the folder) to check the MIME type of the file, and whether it has a width and height
$imageinfo = getimagesize($fileTemp);

//we are going to define what file extensions/MIMEs are ok, and only let these ones in (whitelisting), rather than try to scan for bad
//types, where we might miss one (whitelisting is always better than blacklisting)
$okMIMETypes = 'image/jpeg,image/pjpeg,image/png,image/x-png,image/gif';
$validFileTypes = explode(",", $okMIMETypes);

//if the temp file does not have a width or a height, or it has a non ok MIME, return
if( !is_int($imageinfo[0]) || !is_int($imageinfo[1]) || !in_array($imageinfo['mime'], $validFileTypes) )
{
echo JText::_( 'INVALID FILETYPE' );
return;
}

//lose any special characters in the filename
$fileName = ereg_replace("[^A-Za-z0-9.]", "-", $fileName);

//always use constants when making file paths, to avoid the possibilty of remote file inclusion
$uploadPath = JPATH_SITE.DS.'images'.DS.'stories'.DS.$fileName;

if(!JFile::upload($fileTemp, $uploadPath))
{
echo JText::_( 'ERROR MOVING FILE' );
return;
}
</source>
If all want well the uploaded files will be in the images/stories folder.

=== Part 6: Flash plugin COOKIE bug on non-IE browsers ===

Also you should pay attention to Flash player cookie bug!

It is described here http://swfupload.org/forum/generaldiscussion/383

The Flash Player Plugin for FireFox, Opera and Safari (and probably other non-IE based browsers) has a bug which sends persistent cookies from IE to the upload URL instead of the cookies from the browser. Session only cookies from IE are not sent.

1) Any cookies from a non-IE browser (ie, authentication, login, etc) will not be sent with the file upload. Rather the cookies from IE will be sent. So, no cookies or the wrong cookies will be sent. In most cases this means sessions and cookie based authentication are lost when making an upload.

2) Cookies set by the upload script do get set, but only for Flash. The browser will not see them.

3) This bug affects Flash 8 and Flash 9 and all versions of SWFUpload

4) You cannot rely on cookies when using SWFUpload (or any Flash based upload tool). You must send the data you need from the cookies in another way. There are several threads regarding this issue in the forum and many of the demos show workarounds for restoring PHP sessions and some sample files show how to restore the cookies so Session and Authentication are restored in ASP.Net.

5) This could be considered a security issue but probably not severe enough to actually compromise any data. The cookies created in IE by Flash still have all the rules and restricts associated with cookies in any browser.

Solution is modify function _start() (libraries\joomla\session\session.php):
<source lang="php">

$sn = session_name();

if(isset($_COOKIE[$sn]) && isset($_POST[$sn]))
{
$_COOKIE[$sn] = $_POST[$sn];
session_id($_POST[$sn]);
}

session_start();
</source>

J1.5:Adding sortable columns to a table in a component

2009-12-13T09:31:27Z

Hasse bjork: /* Step 2: The model */

Given that you have a table of data already in your component, how do you make some, or all, of the table columns sortable, like many of them are in the Joomla Administrator? It's not particularly hard to do, but there are several steps and you need to be aware of the details so that everything fits together properly. There are variations on the procedure given here and once you are confident that you understand how it all works you should feel free to explore other possibilities that may suit your purposes better.

This procedure assumes that your component is structured according to the [[Model-View-Controller]] (MVC) design pattern. The general idea behind the procedure will still be applicable to non-MVC components if you apply a bit of imagination!

==Step 1: The component layout file==
Starting with the user interface, you need to add some elements to the component layout file. The table must be included in a form. This might already be the case as, for example, you might already have implemented pagination or filtering on the table. But if the table is not yet in a form then now is the time to wrap it in <form> and </form> tags. The reason that a form is required is that the sortable columns rely on a bit of JavaScript that will submit the form with fresh parameters to obtain a new table. Naturally, this will involve a page load, so if you would prefer an [[AJAX]]-based solution, then this procedure is not for you.

The form tags will look something like this:

<source lang="php">
<form id="adminForm" action="<?php echo JRoute::_( 'index.php' );?>" method="post" name="adminForm">

.... table goes here ....

</form>
</source>
Notice that the form name must be "adminForm". You may need to adjust the action URL in some cases.

You also need to add a couple of hidden fields to the form. They can be placed anywhere between the <form> and </form> tags, but generally they are placed just before the closing tag, like this:
<source lang="php">
<form id="adminForm" action="<?php echo JRoute::_( 'index.php' );?>" method="post" name="adminForm">

.... table goes here ....

<input type="hidden" name="filter_order" value="<?php echo $this->lists['order']; ?>" />
<input type="hidden" name="filter_order_Dir" value="<?php echo $this->lists['order_Dir']; ?>" />
</form>
</source>

Now look at the table itself. You might have a table with static headings already, looking vaguely like this:
<source lang="php">
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</source>
You need to replace the static column names with calls to the Joomla [[JHTML]] static class, so that your code will look something like this:
<source lang="php">
<tr>
<th><?php echo JHTML::_( 'grid.sort', 'Name', 'DbName', $this->lists['order_Dir'], $this->lists['order']); ?></th>
<th><?php echo JHTML::_( 'grid.sort', 'Description', 'DbDescription', $this->lists['order_Dir'], $this->lists['order']); ?></th>
</tr>
</source>
You will definitely need to adapt this code to your specific requirements. The arguments to the [[JHTML]] call are as follows:
# Must be 'grid.sort' so that [[JHTML]] will insert the correct behaviour for a sortable column.
# This is the name of the column that your visitors will actually see. You need to change this for your particular table columns.
# This is the name of the corresponding database field (column) that is to be sorted on. This will be passed to the model, most likely so it can be added to an "ORDER BY" clause in the SQL query statement.
# Must be exactly as shown here. It is the current order direction (ascending or descending) and comes from the view (see later).
# Must be exactly as shown here. It is the name of the column that the table is currently sorted on and comes from the view (see later).

In short, you need to amend the second and third arguments to each [[JHTML]] call appropriately.

Finally, if your sortable table is going to be in the front-end of your site, then you need to add a little snippet of JavaScript to the layout. Alternatively, you can add it to the view code (using [[JDocument/addScriptDeclaration|JDocument->addScriptDeclaration]]) if you would rather keep your JavaScript code in the HTML <head> section.
<source lang="javascript">
<script language="javascript" type="text/javascript">
function tableOrdering( order, dir, task )
{
var form = document.adminForm;

form.filter_order.value = order;
form.filter_order_Dir.value = dir;
document.adminForm.submit( task );
}
</script>
</source>
You don't need to add this code if your sortable table is in the Administrator as this code is loaded for you automatically anyway.

This completes the changes you need to make to the layout. [[JHTML]] [[JHTMLGrid|grid.sort]] will now add a call to the ''tableOrdering'' function so that ''tableOrdering'' will be called whenever the user clicks on the column header. ''tableOrdering'' puts the name of the column that was clicked, and the sort direction, into the hidden form fields and submits the form. In the next step you will see how the model picks up those field values and amends the database query appropriately.

==Step 2: The model==
In the model which generates the data that will form the table, you need to make a change to the method which builds the database query that will be used to populate the table. Most often this is the [[JModel/getData|getData()]] method, but might not be; check in the view to see which method is actually being used (see later).

The model could pull data in from anywhere; it doesn't have to be a database, but in the vast majority of cases the model will be using the Joomla database API to submit SQL queries to a database. Assuming that to be the case, you need to adjust the query so that the sort parameters are taken into account.

The following is typical of a private method used to build the ORDER BY clause:
<source lang="php">
function _buildContentOrderBy()
{
global $mainframe, $option;

$filter_order = $mainframe->getUserStateFromRequest( $option.'filter_order', 'filter_order', 'DbOrder', 'cmd' );
$filter_order_Dir = $mainframe->getUserStateFromRequest( $option.'filter_order_Dir', 'filter_order_Dir', 'asc', 'word' );

$orderby = ' ORDER BY '.$filter_order.' '.$filter_order_Dir;

return $orderby;
}
</source>
You will need to adjust the "DbOrder" to match the name of the database column to sort on by default. If you want the default ordering to be descending order then change the "asc" to "desc" in the $filter_order_Dir statement.

==Step 3: The view==
Having generated the data in the model, using the sort parameters that were passed using the form which wraps the table in the layout, you now need to make sure that these same sort parameters are passed back into the layout so that when the page loads with freshly sorted data, the correct defaults for the sort column and sort direction are shown to the user.

To do this you need to add a few lines of code to your view file, view.html.php:
<source lang="php">
$state =& $this->get( 'state' );

// Table ordering.
$lists['order_Dir'] = $state->get( 'filter_order_Dir' );
$lists['order'] = $state->get( 'filter_order' );

$this->assignRef( 'lists', $lists );
</source>
There shouldn't be any need to customise this code.

You should now test to make sure it all works as it should.

==Step 4: Styling the result==
Finally. you might want to apply a bit of CSS styling to make the output a bit more attractive.

Selecting the sortable columns can only be done via their context, so you will probably need to add a CSS class to the <nowiki><table></nowiki>, the <nowiki><tr></nowiki> or to the <nowiki><th></nowiki> tags. This is what the output might look like with a class added to the <tr> tag:
<source lang="html4strict">
<tr class="sortable">
<th><a href="javascript:tableOrdering('DbName','asc','');" title="Click to sort by this column">Training provider</a></th>
<th><a href="javascript:tableOrdering('DbDescription','asc','');" title="Click to sort by this column">Location</a></th>
</tr>
</source>
To add a bit of space between the column name and the ascending/descending indicator image (a common requirement), you could then apply CSS like this:
<source lang="css">
tr.sortable th img {
margin-left: 5px;
}
</source>

==See also==
* [[JHTMLGrid]]
* [[JModel/getData|JModel->getData]]
* [[JApplication/getUserStateFromRequest|JApplication->getUserStateFromRequest]]
* [[Using JPagination in your component]]
* [[Developing a Model-View-Controller Component - Part 1]]
<noinclude>[[Category:Development]]</noinclude>