Joomla! Documentation - User contributions [en]

Sending email from extensions

2012-02-29T13:56:38Z

Jumpy972: /* See also */

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/1.5/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(JPATH_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]. When sending HTML emails you should normally set the [http://api.joomla.org/Unknown/PHPMailer.html#$Encoding Encoding] to base64 in order to avoid unwanted characters in the output. 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->Encoding = 'base64';
$mailer->setBody($body);
// Optionally add embedded image
$mailer->AddEmbeddedImage( JPATH_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/1.5/Joomla-Framework/JFactory.html#getMailer JFactory->getMailer on api.joomla.org]

[[Category:Development]]

Sending email from extensions

2012-02-29T13:56:14Z

Jumpy972: /* Recipient */

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/1.5/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(JPATH_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]. When sending HTML emails you should normally set the [http://api.joomla.org/Unknown/PHPMailer.html#$Encoding Encoding] to base64 in order to avoid unwanted characters in the output. 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->Encoding = 'base64';
$mailer->setBody($body);
// Optionally add embedded image
$mailer->AddEmbeddedImage( JPATH_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]

[[Category:Development]]

Display error messages and notices

2012-02-29T13:55:36Z

Jumpy972: /* See also */

{{RightTOC}}
Errors, warnings and notices can be displayed from any component, module, plugin or template using the methods outlined below.
<source lang="php">
//Get a handle to the Joomla! application object
$app =& JFactory::getApplication();
//add a message to the message queue
$app->enqueueMessage( JText::_( 'Some error occurred' ), 'error' );

/** Alternatively, in PHP 5 */
JFactory::getApplication()->enqueueMessage( JText::_( 'Some error occurred' ), 'error' );
</source>

The second argument to the [[JApplication/enqueueMessage|enqueueMessage]] function is the type of the message. The default is 'message', but 'error' results in a different style for the message. The message will be displayed in place of a special <tt>jdoc:include</tt> statement in your template. Place the following in your template at the location where you want messages to appear.
<source lang="php">
<jdoc:include type="message" />
</source>

== Message ==
<div style="background-color: #c3d2e5; color: #0055bb; border-top: 3px solid #84a7db; border-bottom: 3px solid #84a7db; padding-left: 1em; font-weight: bold;">
Message
</div>
<source lang="php">
/** PHP 4 */
$app = JFactory::getApplication();
$app->enqueueMessage( 'Message' );

/** Alternatively, in PHP 5 */
JFactory::getApplication()->enqueueMessage( 'Message' );
</source>

== Notice ==

<div style="background-color: #efe7b8; color: #c00; border-top: 3px solid #f0dc7e; border-bottom: 3px solid #f0dc7e; padding-left: 1em; font-weight: bold;">
Notice
</div>
<source lang="php">
JError::raiseNotice( 100, 'Notice' );
</source>

== Warning ==

<div style="background-color: #e6c0c0; color: #c00; border-top: 3px solid #DE7A7B; border-bottom: 3px solid #DE7A7B; padding-left: 1em; font-weight: bold;">
Warning
</div>
<source lang="php">
JError::raiseWarning( 100, 'Warning' );
</source>

== Error ==
<source lang="php">
JError::raiseError( 4711, 'A severe error occurred' );
</source>

== See also ==
* [[JError]]
* [[JApplication]]
* [http://api.joomla.org/1.5/Joomla-Framework/Application/JApplication.html JApplication on api.joomla.org]

<noinclude>[[Category:Development]]</noinclude>
[[Category:Tutorials]][[Category:Component Development]]

J1.5:Retrieving and Filtering GET and POST requests with JRequest::getVar

2012-02-29T13:54:57Z

Jumpy972: /* See also */

When writing any web application, it is crucial that you filter input data before using it. Joomla! provides a set of filtering libraries to help you accomplish this.

===Defined in===
libraries\joomla\environment\request.php

==Methods==

=== 'getVar' ===
To retrieve GET/POST request data, Joomla! uses the getVar method of the JRequest class (JRequest::getVar()).

'''Retrieving Data'''

If you have a form variable named 'address', you would want to use this code to get it:
<source lang="php">
$address = JRequest::getVar('address');
</source>

Unless other parameters are set, all HTML and trailing whitespace will be filtered out.

'''The DEFAULT Parameter'''

If you want to specify a default value in the event that 'address' is not in the request or is unset, use this code:

<source lang="php">
$address = JRequest::getVar('address', 'Address is empty');
echo $address; // Address is empty
</source>

'''The SOURCE Parameter'''

Frequently, you will expect your variable to be found in a specific portion of the HTTP request (POST, GET, etc...). If this is the case, you should specify which portion; this will slightly increase your extension's security. If you expect 'address' to only be in POST, use this code to enforce that:

<source lang="php">
$address = JRequest::getVar('address', 'default value goes here', 'post');
</source>

'''The VARIABLE TYPE Parameter'''

The fourth parameter of getVar() can be used to specify certain filters to force validation of specific value types for the variable.

<source lang="php">
$address = JRequest::getVar('address', 'default value goes here', 'post','variable type');
</source>

Here is a list of types you can validate:

*INT
*INTEGER
*FLOAT
*DOUBLE
*BOOL
*BOOLEAN
*WORD
*ALNUM
*CMD
*BASE64
*STRING
*ARRAY
*PATH
*USERNAME

'''The FILTER MASK Parameter'''

Finally, there are some mask constants you can pass in as the fifth parameter that allow you to bypass portions of the filtering:
<source lang="php">
$address = JRequest::getVar('address', 'default value goes here', 'post','validation type',mask type);
</source>

*JREQUEST_NOTRIM - prevents trimming of whitespace
*JREQUEST_ALLOWRAW - bypasses filtering
*JREQUEST_ALLOWHTML - allows most HTML. If this is not passed in, HTML is stripped out by default.

Note. These are static variables not strings. Do not use quotes around them

=== 'get' ===
To receive a whole array filtered. If you would want to get the POST data, you can use this.
<source lang="php">JRequest::get( 'post' )</source>
<nowiki>This returns the standard POST array. You can use it on a template page if needed, or in the models section if convenient. It returns the most recent POST.
Methods of this object were not found in the Framework section where one would expect to find them. </nowiki>

==See also==
* [http://api.joomla.org/1.5/Joomla-Framework/Environment/JRequest.html JRequest on api.joomla.org]
* [[JURI]]
* [[JRoute]]

==Security==

Why not just use the Superglobals? If you are familiar with PHP already you may be wondering, why not just use $_GET / $_POST / $_REQUEST? To make Joomla more secure, all global variables should be read through this function. It removes the possibility for code injection and/or SQL injection. You can also define a default value (as you can see in line 6). Copied and changed from [[Creating a simple component - Part 1]].

[[Category:Development]]

J1.5:How to add tooltips to your Joomla! website

2012-02-29T13:35:20Z

Jumpy972: /* Create a Tooltip with the JHTML::tooltip Method */

A tooltips is a piece of text that pops up when you hover the mouse over a region on a website. If you use the Joomla! back end, for example, tooltips are used to help explain the action of different parameters, as shown in the screenshot below:

[[Image:Screen_tooltip_example_20090208.png]]

Tooltips are a great way to give the user access to information without using up space on the screen. You can use basic tooltips just by adding a "title" attribute to a tag. However, this doesn't give you the option to style the tooltips. With Joomla! version 1.5, it is very easy to add styled tooltips to your site. This tutorial will show you how. <blockquote>''Note: If you are converting old code, make sure it doesn't use the prototype.js file. That file will keep the tooltips from working.''</blockquote>

== Activate Tooltip Behavior ==
To start, you must activate the tooltip behavior. This is done with the following line of code:
<source lang="php">
JHTML::_('behavior.tooltip');
</source>
Note that you only put this line in once per file. A good place is right after the <code>defined('_JEXEC') or die('Restricted access');</code> line. If you are curious about what this line does, it inserts the following JavaScript code in the heading of the HTML page:
<source lang="html4strict">
<script type="text/javascript">
window.addEvent('domready', function(){
var JTooltips = new Tips($$('.hasTip'),
{ maxTitleChars: 50, fixed: false});
});
</script>
</source>
This allows tooltips to function, as outlined below.

== Create a Tooltip with the JHTML::tooltip Method ==
One way to create a tooltip is using the JHTML::tooltip method. The API documentation is available at [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#tooltip http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#tooltip]. The method definition is shown below.
<source lang="php">
void tooltip (string $tooltip, [string $title = ''], [string $image = 'tooltip.png'],
[string $text = ''], [string $href = ''], [boolean $link = 1])
</source>
The brackets mean the parameter is optional. The first parameter, "$tooltip", is the only required parameter. The equals specifies the default if you do not pass that parameter. For example, the image file 'tooltip.png' is the default image.

The following is a basic tooltip. Keep in mind that the image variable must be in reference to 'includes/js/ThemeOffice'. Use the prefix '../../../' to reference from the root of the Joomla installation.
<source lang="php">
JHTML::tooltip('This is the tooltip text', 'Tooltip title', 'tooltip.png', '',
'http://www.joomla.org');
</source>
The above will make a tooltip using the default "tooltip.png" image, as shown below.[[Image:Tooltip_tutorial_example_screenshot_20090208.png|center|frame]]Clicking the image will take you to <tt>http://www.joomla.org</tt>, since that is the "$href" argument. The HTML source for this tooltip is as follows:
<source lang="html4strict">
<span class="editlinktip hasTip" title="Tooltip title::This is the tooltip text" >
<a href="http://www.joomla.org">
<img src="/my_joomla_path/includes/js/ThemeOffice/tooltip.png" border="0" alt="Tooltip"/></a>
</span>
</source>

<blockquote>''Internet Explorer Bug: As shown above, when you use the JHTML::tooltip method to create an image tooltip, it creates an "alt" attribute with the value "Tooltip". The "alt" attribute is used in cases where the image file cannot be found or for accessibility (for example, for blind users). Internet Explorer automatically -- and incorrectly -- displays the "alt" attribute as a tooltip. This means that image tooltips created by JHTML::tooltip (like the example above) will display with two tooltips when viewed with Internet Explorer, as shown below.''</blockquote>
[[Image:Tooltip_tutorial_ie7bug_20090301.png|center|frame]]
<blockquote>''You can avoid this problem either by using text tooltips or by not using this method for image tooltips. Instead, just enter the HTML manually and set the "alt" attribute to an empty string (alt="").''</blockquote>

This code is almost the same as above except the image will not be a link (because the "$href" argument is omitted).
<source lang="php">
JHTML::tooltip('This is the tooltip text', 'Tooltip title',
'tooltip.png', '', '', false);
</source>

A tooltip can be attached to an image or to text. For example, this code
<source lang="php">
echo JHTML::tooltip('This is a tooltip attached to text', 'Text Tooltip Title',
'', 'Hover on this text to see the tooltip');
</source>
will show a tooltip attached to text, as shown below.

[[Image:Tooltip_tutorial_example_screenshot2_20090208.png|center|frame]]

Note that specifying the "$text" parameter will override any image you have passed to tooltip.

== Create a Tooltip Using a CSS Class Name ==
If we look at the HTML page source generated by the <code>JHTML::tooltip</code> function above, here is what we see:
<source lang="html4strict">
<span class="editlinktip hasTip"
title="Text Tooltip Title::This is a tooltip attached to text"
style="text-decoration: none; color: #333;">
Hover on this text to see the tooltip</span>
</source>
This function generates an HTML "span" tag with the classes "editlinktip" and "hasTip" and an attribute called "title". Notice that the the "title" attribute has two parts, <code><tooltip title>::<tooltip text></code> (for example, "Tooltip Title::This is the tooltip text"). You can create a tooltip with only text or with only a title. The title has implications for styling, as we'll see below.

The Javascript inserted by the <code>JHTML::('behavior_tooltip')</code> command we entered earlier picks up this tag based on the class called "hasTip". So, a second way of creating a tooltip is to simply create a tag with a class called "hasTip" and an attribute of "title". For example, this code
<source lang="html4strict">
<span class="hasTip"
title="Text Tooltip Title::This is a tooltip attached to text">
Hover on this text to see the tooltip</span>
</source>
will produce exactly the same effect as the <code>JHTML::tooltip()</code> example above.

== Adding CSS Styling to the Tooltip ==
The default tooltips, whether using the JHTML::tooltip method or class method, use the following three CSS classes: <tt>.tool-tip</tt>, <tt>.tool-title</tt>, and <tt>.tool-text</tt>.

Here are the default styles.
<source lang="css">
/* Tooltips */
.tool-tip {
float: left;
background: #ffc;
border: 1px solid #D4D5AA;
padding: 5px;
max-width: 200px;
}

.tool-title {
padding: 0;
margin: 0;
font-size: 100%;
font-weight: bold;
margin-top: -15px;
padding-top: 15px;
padding-bottom: 5px;
background: url(../images/selector-arrow.png) no-repeat;
}

.tool-text {
font-size: 100%;
margin: 0;
}
</source>

== Adding CSS Styling to the Tooltip Joomla v1.6+==
The default tooltips, whether using the JHTML::tooltip method or class method, use the following three CSS classes: <tt>.tip</tt>, <tt>.tip-title</tt>, and <tt>.tip-text</tt> plus a wrapper class <tt>.tip-wrap</tt>.

Here are the default styles.
<source lang="css">
/* Tooltips */
.tip-wrap{
z-index: 10000;
}
.tip {
float: left;
background: #ffc;
border: 1px solid #D4D5AA;
padding: 5px;
max-width: 200px;
}

.tip-title {
padding: 0;
margin: 0;
font-size: 100%;
font-weight: bold;
margin-top: -15px;
padding-top: 15px;
padding-bottom: 5px;
background: url(../images/selector-arrow.png) no-repeat;
}

.tip-text {
font-size: 100%;
margin: 0;
}
</source>

If you have a custom CSS file, copy this code and alter it to your liking. Note that the <tt>.tool-title</tt> (<tt>.tip-title</tt> Joomla v1.6+) class uses by default the "selector-arrow.png" image. This is what gives the outline of the tooltip the little pointer in the upper left of the tooltip box. If you leave out a title in your tooltip, you will just get a rectangle, without the pointer.

== Customizing Your Tooltips ==
Ok, now it's time to have some fun. The <code>JHTML::_('behavior.tooltip')</code> can take two optional parameters. The first parameter is the name of the CSS class that will be used to identify the tooltip. As we saw earlier, this defaults to "hasTip". The second optional parameter is an array of parameters that you can use to fine-tune the tooltip functionality. These are explained below.
* '''maxTitleChars:''' The maximum length of the title (the part of the "title" attribute before the "::")
* '''showDelay, hideDelay:''' The time to delay showing or hiding the tooltip, in milliseconds. Default is 100.
* '''className:''' The first part of the class name used to style the actual tooltip. The default, as we saw, is "tool", and the full class names by default are "tool-tip", "tool-title', and "tool-text". So, for example, if we set this to "custom", we would style the classes "custom-tip", "custom-title", and "custom-text".
* '''fixed:''' Whether or not to have the tooltip move with the mouse. If set to "true", the tooltip will be centered below the text or image. If set to "false", the tooltip will move with the mouse. Default is "false".
* '''onShow, onHide:''' Functions to call for the onShow and onHide events. We'll see an example below where we can use these to create a fade-in and fade-out for the tooltip.

In the next section, we'll show how to use these parameters with some examples.

== Tooltip With Different Classes ==
In this example, we will create a tooltip using different selector and tooltip styling classes. Why might we want to do this? One reason would be if we had different types of tooltips and we wanted to style them differently.

Here is the code to create the tooltip Javascript function:
<source lang="php">
$toolTipArray = array('className'=>'custom2');
JHTML::_('behavior.tooltip', '.hasTip2', $toolTipArray);
</source>
In this code, we are creating an array with just one element -- to set the "className" parameter to "custom2". This means that, to style these tooltips, we would use the classes <tt>custom2-tip</tt>, <tt>custom2-title</tt>, and <tt>custom2-text</tt>. Then we call the method with the arguments ".hasTip2" and the array "$toolTipArray". It can be a little confusing, because we have two CSS classes at work here. The class ".hasTip2" is used in the HTML tag. That is how the Javascript program identifies the tooltips to operate on. The class "custom2" is used as the first part of the three CSS classes to use to style the actual tooltip itself.

To use this new tooltip, we could use the following code:
<source lang="html4strict">
<span class="hasTip2"
title="My Tooltip Title :: Tooltip text for hasTip2 class with custom2 style classes.">
hasTip2 and custom2 example</span>
</source>
Since we set the class to "hasTip2", this tag will be processed by the new version of the tooltip program. So, if we use both the default tooltip ("hasTip" class) and the new tooltip ("hasTip2" class) in the same page, we can style them differently using "tool-" styles for the default and "custom2-" styles for the "hasTip2" tooltips.

Next, let's look at a more complex example, shown below.
<source lang="php">
$toolTipArray = array('className' => 'custom2', 'showDelay'=>'500',
'hideDelay'=>'500', 'fixed'=>true,
'onShow'=>"function(tip) {tip.effect('opacity',
{duration: 500, wait: false}).start(0,1)}",
'onHide'=>"function(tip) {tip.effect('opacity',
{duration: 500, wait: false}).start(1,0)}");
JHTML::_('behavior.tooltip', '.hasTip2', $toolTipArray); ?>
</source>
Again, we are building an array to pass to the <code>JHTML::_('behavior.tooltip')</code> function. Again, we are setting the "className" parameter to "custom2". We are also setting the "showDelay" and "hideDelay" parameters to 500 milliseconds (.5 seconds). So the tooltip will show only after the mouse has hovered for this amount of time.

Notice that we are setting the parameter "fixed" to "true" (without the quotes). This means that the tooltip will not move with the mouse. Instead, it will always show centered below the tooltip text or image.

Finally, the tricky part. We are creating functions to pass in to the "onShow" and "onHide" events. These functions cause the tooltip to fade in and fade out over the space of 500 milliseconds. This is done by gradually varying the tooltip's CSS "opacity" style from "0" (completely transparent) to "1" (completely opaque). If we wanted the tooltip to be partially transparent, we could change these to <code>start(0,.8)</code> and <code>start(.8,0)</code>.

These functions are similar to the sample code in the [http://demos111.mootools.net/Tips MooTools demo tutorial]. Click on the link called "js code" and look at the code for the "Tips2" demo. We have just taken the code from the initialize function and incorporated it into the "onShow" and "onHide" functions.

The last line of code above creates the actual Javascript code in our Joomla! document. If we show the page and view source, we see the following:
<source lang="javascript">
window.addEvent('domready', function(){
var JTooltips = new Tips($$('.hasTip2'), {
maxTitleChars: 50, showDelay: 500, hideDelay: 500, className: 'custom2',
fixed: true,
onShow: function(tip) {tip.effect('opacity', {duration: 500, wait: false}).start(0,1)},
onHide: function(tip) {tip.effect('opacity', {duration: 500, wait: false}).start(1,0)}
});
});
</source>
So we can see the effect of the parameters that we passed to the <code>JHTML::_('behavior.tooltip')</code> method.

=== offsets Parameter ===
<blockquote>''Note: The "offsets" parameter doesn't work in version 1.5.9 and earlier because of a bug. As of version 1.5.10 it should work as outlined below.''</blockquote>
You can control the x and y distance, in pixels, from the cursor to the tooltip using the "offsets" parameter. This parameter must be an array as shown in the example code below:
<source lang="php">
// set x (horizontal) distance to 20 pixels, y (vertical) distance to 30 pixels
$toolTipArray = array('offsets'=>array('x'=>20, 'y'=>30), 'maxtitlechars'=>40);
JHTML::_('behavior.tooltip', '.customOffset', $toolTipArray);
</source>

== Using an External Javascript File ==
There are times when you might prefer to work with a separate Javascript file. This gives you complete flexibility to use all of the mootools capabilities. To do this:
# Create the separate Javascript file and save it somewhere in your Joomla! site (for example, "templates/<your template>/js/yourjsfile.js".
# Use the <code>JHTML::script</code> function to add this script to your document. For example:
<source lang="php">
$filename = 'testtooltip.js'; // this file is used for class="hasTip3" titles
$path = 'templates/rhuk_milkyway/js/'; // path to the file
// true means MooTools will load if it is not already loaded
JHTML::script($filename, $path, true);
</source>
This will load your script into the document and make sure that the MooTools library is available.

== Complete Code Example ==
Here is an example that incorporates all of the elements discussed in this tutorial. So you can see the code in action, we will create an override of the "mod_stats" Module and add our test code there. We will use the rhuk_milkyway template.

To set up the template override, create a folder called "templates/rhuk_milkyway/html/mod_stats" and copy the file "modules/mod_stats/tmpl/default.php" to this new folder.

After line 2 of this file (<code>defined('_JEXEC') or die('Restricted access');</code>), insert the following:
<source lang="php">
JHTML::_('behavior.tooltip');
$toolTipArray = array('className' => 'custom2', 'showDelay'=>'500', 'hideDelay'=>'500',
'fixed'=>true
, 'onShow'=>"function(tip) {tip.effect('opacity',
{duration: 500, wait: false}).start(0,1)}"
, 'onHide'=>"function(tip) {tip.effect('opacity',
{duration: 500, wait: false}).start(1,0)}");
JHTML::_('behavior.tooltip', '.hasTip2', $toolTipArray); // class="hasTip2" titles
$filename = 'testtooltip.js'; // used for class="hasTip3" titles
$path = 'templates/rhuk_milkyway/js/';
JHTML::script($filename, $path, true); // MooTools will load if it is not already loaded
</source>
Here we are creating the Javascript functions we will need later. The first line is the simple default declaration that will use the ".hasTip" and "tool-" CSS classes.

The next 5 lines create the more customized function that includes the fade-in and fade-out. It uses the ".hasTip2" to create the tip and the classes starting with "custom2-" to style the tooltip.

The last 3 lines reference the external Javascript file, which will be created below. The class information will be contained in that file.

Now, time for some more coding. At the end of the "modules/mod_stats/tmpl/default.php" file, add the code shown below:
<source lang="php">
<h1>Tooltip Examples</h1>
<?php echo JHTML::tooltip('This is the tooltip text', 'Tooltip title',
'tooltip.png', '', 'http://www.joomla.org');?>
<br/><br/>
<?php echo JHTML::tooltip('This is a tooltip attached to text', 'Text Tooltip Title',
'', 'Hover on this text to see the tooltip');?>
<br/><br/>
<a class="hasTip" title="My Title::Tooltip on 'a' tag text using default 'hasTip' class"
href="http://www.joomla.org">Tooltip on a link example</a>
<br/><br/>
<span class="hasTip2"
title="My Tooltip Title :: Tooltip text for hasTip2 class with custom2 style classes.">
hasTip2 and custom2 example</span>
<br/><br/>
<span class="hasTip3"
title="hasTip3 Title::This is using class 'hasTip3' using external JS script.">
hasTip3 hover text</span>
<br/><br/>
</source>
The first two examples using the <code>JHTML::tooltip</code> function to create the tooltip HTML code.

The third example shows an "a" tag with a tooltip. This illustrates that you can put tooltips on most HTML tags, not just "span" tags. Again, it is using the "hasTip" class, so it will be controlled by the Javascript above called with the ".hasTip" argument and will be styled with the default "tool-" styles.

The fourth example shows a "span" tag using the "hasTip2" class. So it will be styled using the "custom2-" classes and will have the "showDelay" and "hideDelay" of 500 milliseconds and have "fixed" equal to "true" (so the tip will not move with the mouse). Also, it uses the special fade-in and fade-out effects.

The last example will use the Javascript code from the external file, shown below.

Now, some more coding. Create a JavaScript file called "testtooltip.js" and save it into the folder "templates/rhuk_milkyway/js":
<source lang="javascript">
window.addEvent('domready', function(){
//do your tips stuff in here...
var zoomTip = new Tips($$('.hasTip3'), {
className: 'custom3', //this is the prefix for the CSS class
offsets: {
'x': 20, //default is 16
'y': 30 //default is 16
},
initialize:function(){
this.fx = new Fx.Style(this.toolTip, 'opacity',
{duration: 1000, wait: false}).set(0);
},
onShow: function(toolTip) {
this.fx.start(0,.8);
},
onHide: function(toolTip) {
this.fx.start(.8,0);
}
});
});
</source>
This code will operate on the "hasTip3" class and will use style classes starting with "custom3-". We are setting the x distance (from the cursor to the tooltip) to 20 pixels and the y distance to 30 pixels. This also has the fade-in and fade-out functionality, but the final "opacity" value is set to .8, meaning that the tooltip will be slightly transparent.

Finally, add this to the end of your "templates/rhuk_milkyway/css/template.css" file:
<source lang="css">
.custom2-tip {
color: #000;
width: 130px;
z-index: 13000;
}

.custom2-title {
font-weight: bold;
font-size: 11px;
margin: 0;
color: #024A68;
padding: 8px 8px 4px;
background: #3CA0D0;
border-bottom: 1px solid #024A68;
}

.custom2-text {
font-size: 11px;
padding: 4px 8px 8px;
background: #63ADD0;
}

.custom3-tip {
color: #000;
width: 130px;
z-index: 13000;
}

.custom3-title {
font-weight: bold;
font-size: 11px;
margin: 0;
color: #3E4F14;
padding: 8px 8px 4px;
background: #C3DF7D;
border-bottom: 1px solid #B5CF74;
}

.custom3-text {
font-size: 11px;
padding: 4px 8px 8px;
background: #CFDFA7;
}
</source>
Here we are just adding different colors for the "custom2-" and "custom3-" styles so you can see the effect of the different tooltip code.

Notice that <tt>.custom2-title</tt> and <tt>.custom3-title</tt> classes do not have a background property. So these tooltips will be a box without the neat little arrow pointing at the mouse. If you wanted, you could create an image similar to "templates/system/images/selector-arrow.png" of the right color and add that as a background to these classes.

== Example Code Screenshots ==
Here are some screenshots taken from the sample code above. The first screenshot shows the modified "mod_stats" modules with our sample code.
[[Image:Screen_tooltip_example2_20090210.png|center|frame]]
The screenshot below shows the fade-in effect for the ".hasTip2" tooltip. Notice also that the tooltip is centered below the text. This is the effect of setting "fixed" equal to "true".
[[Image:Screen_tooltip_example1_20090209.png|center|frame]]
The last screenshot shows the different styling for the ".hasTip3" tooltip, based on the "custom3-" CSS class styles.
[[Image:Screen_tooltip_example3_20090210.png|center|frame]]

== More Information ==
More information about the topics covered in this tutorial is available at the links below. Note that Joomla! version 1.5 uses MooTools version 1.11. The current version of MooTools is 1.2.
* Joomla API - [http://api.joomla.org http://api.joomla.org]
* Documentation for 1.11 MooTools Tips: [http://docs111.mootools.net/Plugins/Tips.js http://docs111.mootools.net/Plugins/Tips.js]
* Mootools demos for version 1.11 - [http://demos111.mootools.net/Tips http://demos111.mootools.net/Tips]
* Mootools Website - [http://www.mootools.net/ http://www.mootools.net/]

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

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

2012-02-29T13:34:30Z

Jumpy972: /* Retrieving the Data */

== Introduction ==

In the first two tutorials, we showed you how to build a simple model-view-controller component. We had one view which retrieved data from a model (which was created in the 2nd tutorial). In this tutorial, we will be working with the model. Instead of the data being hard coded in the model, the model will retrieve the data from a table in the database.

This tutorial will demonstrate how to use the JDatabase class to retrieve data from the database.

== Retrieving the Data ==

Our model currently has one method: getGreeting(). This method is very simple - all it does is return the hard-coded greeting.

To make things more interesting, we will load the greeting from a database table. We will demonstrate later how to create an SQL file and add the appropriate code to the XML manifest file so that the table and some sample data will be created when the component is installed. For now, we will simply replace our return statement with some code that will retrieve the greeting from the database and return it.

The first step is to obtain a reference to a database object. Since Joomla! uses the database for its normal operation, a database connection already exists; therefore, it is not necessary to create your own. A reference to the existing database can be obtained using:

<source lang="php">$db =& JFactory::getDBO();</source>

JFactory is a static class that is used to retrieve references to many of the system objects. More information about this class can be found in the API documentation [http://docs.joomla.org/JFactory JFactoryAPI].

The method name (getDBO) stands for get DataBase Object, and is easy and important to remember.

Now that we have obtained a reference to the database object, we can retrieve our data. We do this in two steps:

* store our query in the database object
* load the result

Our new getGreeting() method will therefore look like:

<source lang="php">function getGreeting()
{
$db =& JFactory::getDBO();

$query = 'SELECT greeting FROM #__hello';
$db->setQuery( $query );
$greeting = $db->loadResult();

return $greeting;
}</source>

hello is the name of the table that we will create later, and greeting is the name of the field that stores the greetings. If you are not familiar with SQL, it would be helpful to take a tutorial or a lesson to get yourself up to speed. There are many such tutorials on the web and they are easily found using search engines.

The $db->loadResult() method will execute the stored database query and return the first field of the first row of the result. See [http://api.joomla.org/1.5/Joomla-Framework/Database/JDatabase.html JDatabase API reference] for more information about other load methods in the JDatabase class.

== Creating the Installation SQL File ==

The Joomla! installer has built-in support for executing queries during component installation. These queries are all stored in a standard text file.

We will have three queries in our install file: the first will drop the table in case it already exists, the second will create the table with the appropriate fields, and the third will insert the data.

Here are our queries:

<source lang="mysql">DROP TABLE IF EXISTS `#__hello`;

CREATE TABLE `#__hello` (
`id` int(11) unsigned NOT NULL auto_increment,
`greeting` varchar(25) NOT NULL,
PRIMARY KEY (`id`)
) ENGINE=MyISAM AUTO_INCREMENT=0 DEFAULT CHARSET=utf8;

INSERT INTO `#__hello` (`greeting`) VALUES ('Hello, World!'), ('Bonjour, Monde!'), ('Ciao, Mondo!');</source>

You might find the prefix on the table names rather odd. Joomla! will replace this prefix with the prefix used by the current install. For most installs, this table will become jos_hello. This allows multiple installs of Joomla! to use the same database, and prevents collisions with other applications using the same table names (i.e. two applications might share a database, but might both require a 'users' table. This convention avoids problems.)

We have specified two fields in our database. The first field is id, and is called the 'primary key'. The primary key of a database table is a field that is used to uniquely identify a record. This is often used to lookup rows in the database. The other field is greeting. This is the field that stores the greeting that is returned from the query that we used above.

We will save our installation queries in a file called admin/install.sql. (Note: In the original version of this file, install.utf.sql was used - this was incorrect. Also see [[Talk:Developing_a_Model-View-Controller_Component_-_Part_3_-_Using_the_Database | discussion]].)

=== Creating the Uninstall SQL File ===

Though we might hope that people will never want to "uninstall" our component, it is important that if they do, nothing is left behind after uninstalling our component. Joomla! will look after deleting the files and directories that were created during the "install", but we must manually include queries that will remove any tables that were added to the database. Since we have only created one table, we only need one query:

<source lang="mysql">DROP TABLE IF EXISTS `#__hello`;</source>

We will save this uninstall query in a file called admin/uninstall.sql. (Note: In the original version of this file, uninstall.utf.sql was used - this was incorrect. Also see [[Talk:Developing_a_Model-View-Controller_Component_-_Part_3_-_Using_the_Database | discussion]].)

== Updating our XML File ==

We need to change a few things in our hello.xml file. First, we need to add our two new sql files to the list of files to install. Secondly, the SQL install files have to be placed in the admin directory. Thirdly, we need to tell the installer to execute the queries in our files on install and uninstall.

Our new file looks like this:

<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>3.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>

<install>
<sql>
<file charset="utf8" driver="mysql">install.sql</file>
</sql>
</install>
<uninstall>
<sql>
<file charset="utf8" driver="mysql">uninstall.sql</file>
</sql>
</uninstall>

<administration>

<menu>Hello World!</menu>


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

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

You will notice two attributes present on the <file> tags within the <install> and <uninstall> sections: charset and driver. The charset is the type of charset to use. The only valid charset is utf8. If you want to create install files for non-utf8 databases (for older version of MySQL), you should omit this attribute.

The driver attribute specifies which database the queries were written for. Currently, this can only be mysql, but in future versions of Joomla! there may be more database drivers available.

== Conclusion ==

We now have a component that takes advantage of both the Joomla! MVC framework classes and the JDatabase classes. You are now able to write MVC components that interact with the database and can use the Joomla! installer to create and populate database tables.

== 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/8110/29435/com_hello3_01.zip com_hello3_01]

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

Adding JavaScript

2012-02-29T13:32:45Z

Jumpy972: /* Adding Javascript Files Using JHTML */

{{cookiejar}}
===Adding Javascript===
----
This chunk should describe in detail how to add Javascript to the head of
a template using the Joomla! 1.5 API calls. It should be aimed at
people who have only minimal knowledge of PHP, HTML and Javascript.
[[Category:Templates]]
[[Category:Modules]]
[[Category:Components]]
[[Category:Plugins]]
[[Category:Tutorials]]

Add the following code to have the Javascript library /media/system/js/sample.js included in your template.

<source lang="php">
<?php
$document = &JFactory::getDocument();
$document->addScript( '/media/system/js/sample.js' );
?>
</source>

==Explanation==
Ultimately you are trying to have the resulting HTML page have a Javascript included in the head element (i.e. <head> ... </head>):

For example:
<source lang="php">
<script type="text/javascript" src="/media/system/js/sample.js"></script>
</source>
Ensure that the Javascript you want to include is in the directory, from the above example:
<nowiki>/media/system/js/sample.js</nowiki>

Load your page into a browser and verify that the <script> tag is in the <head> area and able to load the Javascript. Again, using the example:
<nowiki>http://www.example.com/media/system/js/sample.js</nowiki>

When successful the script is integrated into your page. Now you can use Javascript in your HTML.

Do not directly add the <script> to your template's index.php. The code will insert the <script> line where your index.php has the following line:
<source lang="php">
<jdoc:include type="head" />
</source>
Add this PHP code to your page, in the head, or next to the Javascript code you will use, depending on your preference.

<source lang="php">
<?php
$document = &JFactory::getDocument();
$document->addScript( '/media/system/js/sample.js' );
?>
</source>
Reload and view the page. Ensure that the sample.js is included in the <head> section.

== Adding Javascript Files Using JHTML ==
You may also use the [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html JHTML] [http://api.joomla.org/1.5/Joomla-Framework/HTML/JHTML.html#script script] method to add a Javascript file to the head of your document.

<source lang="php">
<?php
$filename = 'filename.js';
// Add the path parameter if the path is different than 'media/system/js/'
$path = 'path/to/file/';
JHTML::script($filename, $path);
?>
</source>
There is a third Boolean argument that can be passed to the script method. Set this to true if you also want MooTools loaded.
<source lang="php">
<?php
$filename = 'filename.js';
// Add the path parameter if the path is different than 'media/system/js/'
$path = 'path/to/file/';
// MooTools will load if it is not already loaded
JHTML::script($filename, $path, true);
?>
</source>
'''Please Note:''' Joomla 1.6+ may handle MooTools differently than in previous versions. <ref>[http://forum.joomla.org/viewtopic.php?f=502&t=273960 Whitepaper] Upgrade to mootools 1.2</ref>

== References ==
<references/>