Joomla! Documentation - User contributions [en]

Custom error pages

2015-11-13T09:42:14Z

Flimm: Use getCode() instead of private attribute

<noinclude><languages /></noinclude>
<noinclude>{{JSplit}}</noinclude>
<translate>

Joomla! uses the <tt>templates/system/error.php</tt> file to handle several HTTP Status errors, including "403 Forbidden", "404 Not Found", and "500 Internal Server" errors. You can style the error results, if desired.
</translate>

<translate>

It is important to understand that ''error.php'' is an independent file from the Joomla! CMS but dependent on the Joomla! Platform. Plugins do not run on the file. You cannot include modules or use <tt><jdoc:include></tt> statements.
</translate>

<translate>
====Overriding the System Error Results==== 
To override the system error results, copy the <tt>templates/system/error.php</tt> file into your <tt>templates/<template-name></tt> directory.
</translate>

<translate>

If it finds one, Joomla! will use the <tt>error.php</tt> file from the current template, in place of the system file.
</translate>

<translate>
You can format the page, as desired, to match your template.</translate>

<translate>
====Overriding the System Styling==== 
If you want to change the styling, copy the <tt>templates/system/css/error.css</tt> file into your <tt>templates/<template-name>/css</tt> directory.
</translate>
<translate>

Next, update your <tt>templates/<template-name>/error.php</tt> file to reference the new location of the stylesheet by changing this line, accordingly:
</translate>

<source lang="css"><link rel="stylesheet" href="<?php echo $this->baseurl; ?>/templates/system/css/error.css" type="text/css" /></source>

<translate>
Then, simply change the <tt>error.css</tt>, as desired, for your styling requirements.</translate>

<translate>
====Customizing Error Messages==== 
You can add conditional logic to vary the message returned, dependent upon the specific error code.
</translate>

<translate>

Here is an example of how to trap a 404 error and provide a custom message.
</translate>

<source lang="php">
<?php if ($this->error->getCode() == '404') { ?>
<div id="errorboxheader">Page not found</div>
<div id="errorboxbody"><p>Sorry! That page cannot be found.</p>
</div>
</div>
<?php } ?>
</source>

<translate>
====HTTP Status Code==== 
When a request is made for a page on your site, the server returns an HTTP status code in response to the request. Joomla! returns a '200 - the server successfully returned the page' for error pages. This is problematic for those working with Google Webmaster Services and trying to get a sitemap resolved.
</translate>

<translate>

If you want Joomla! to return a status code for the error, you can do so by adding logic before the DOCTYPE line, as follows:
</translate>

<source lang="php">
<?php
if ($this->error->getCode() == '404') {
header("HTTP/1.0 404 Not Found");
} ?>
</source>

<translate>
====More HTTP Status Code Information==== 
</translate>

<translate>

* [[S:MyLanguage/Create_a_Custom_404_Error_Page|Create a Custom 404 Error Page]]
* [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP/1.1 Status Code Definitions]
* [[wikipedia:List_of_HTTP_status_codes|List of HTTP status codes]]
</translate>

<translate>
====Using Theme Header and Footer on Standard Error Page==== 
</translate>
{{JVer|1.5}}
<translate>

If you want to see the error page in theme design and don't like redirecting to error page URL or duplicating HTML in the error page template, here is a way to apply your theme template to the error page.
</translate>

<translate>

First, put the following code in <tt>templates/<template-name>/error.php</tt>:
</translate>

<source lang="php">
<?php
// no direct access
defined( '_JEXEC' ) or die( 'Restricted access' );

include dirname(__FILE__) . "/index.php";
?>

</source>

<translate>

Then make the following edits to <tt>templates/<template-name>/index.php</tt>:
</translate>

<translate>

1. Find the following code in <tt>index.php</tt>
</translate>

<source lang="php">
<jdoc:include type="head" />
</source>

<translate>

and replace it with the following
</translate>

<source lang="php">
<?php if (!$this->error->getCode()) : ?>
<jdoc:include type="head" />
<?php else : ?>
<title><?php echo $this->error->getCode() ?> - <?php echo $this->title; ?></title>
<?php endif; ?>
</source>

<translate>

2. Find the following code in <tt>index.php</tt>
</translate>

<source lang="php">
<jdoc:include type="component" />
</source>

<translate>

and replace it with the following
</translate>

<source lang="php">
<?php if ($this->error->getCode()) : /* check if we are on error page, if yes - display error message */ ?>
<p><strong><?php echo $this->error->getCode() ?> - <?php echo $this->error->message ?></strong></p>
<p><strong><?php echo JText::_('JERROR_LAYOUT_NOT_ABLE_TO_VISIT'); ?></strong></p>
<ol>
<li><?php echo JText::_('JERROR_LAYOUT_AN_OUT_OF_DATE_BOOKMARK_FAVOURITE'); ?></li>
<li><?php echo JText::_('JERROR_LAYOUT_SEARCH_ENGINE_OUT_OF_DATE_LISTING'); ?></li>
<li><?php echo JText::_('JERROR_LAYOUT_MIS_TYPED_ADDRESS'); ?></li>
<li><?php echo JText::_('JERROR_LAYOUT_YOU_HAVE_NO_ACCESS_TO_THIS_PAGE'); ?></li>
<li><?php echo JText::_('JERROR_LAYOUT_REQUESTED_RESOURCE_WAS_NOT_FOUND'); ?></li>
<li><?php echo JText::_('JERROR_LAYOUT_ERROR_HAS_OCCURRED_WHILE_PROCESSING_YOUR_REQUEST'); ?></li>
</ol>
<p><strong><?php echo JText::_('JERROR_LAYOUT_PLEASE_TRY_ONE_OF_THE_FOLLOWING_PAGES'); ?></strong></p>

<ul>
<li><a href="<?php echo $this->baseurl; ?>/index.php" title="<?php echo JText::_('JERROR_LAYOUT_GO_TO_THE_HOME_PAGE'); ?>"><?php echo JText::_('JERROR_LAYOUT_HOME_PAGE'); ?></a></li>
</ul>

<p><?php echo JText::_('JERROR_LAYOUT_PLEASE_CONTACT_THE_SYSTEM_ADMINISTRATOR'); ?>.</p>
<?php else : ?>
<jdoc:include type="component" />
<?php endif; ?>
</source>

<translate>

Now your theme template is applied to error pages too.
</translate>

<translate>

'''Note:''' Module includes in template will not work on error page created by this method (but will work on other pages).
</translate>

<noinclude>
<translate>

[[Category:Tutorials]]
[[Category:Template Development]]
</translate>
</noinclude>

Creating a basic Joomla! template

2015-06-29T16:08:01Z

Flimm: Don't hardcode template name

{{version/tutor|1.5,2.5,3.1}}{{JSplit}}
== Introduction ==

The purpose of this tutorial is to serve as an introduction to creating Joomla! templates. It will cover the essential files and code needed to create a basic template. The code is presented so it can be cut and pasted with very little modification needed.

== Setting up a directory structure ==
To make the most basic template, '''create a new folder''' in the ''templates'' folder. Name this folder after your template i.e. ''mynewtemplate''.

Using your favourite text editor create the files <code>index.php</code> and <code>templateDetails.xml</code>.
To keep things organized, make '''2 new folders''' called ''images'' and ''css''. Inside the ''css'' folder create a file called <code>template.css</code>.

Although it is fine to place all your [[CSS]] code directly in your index.php file to start, many web developers prefer to place their CSS code in a separate file that can be linked from multiple pages using the <code>link</code> tag. This may also shorten the loading time of your pages, since the separate file can be cached.

This is the most basic practical setup. Outline of folder and file structure:
* mynewtemplate/
** css/
*** template.css
** images/
** index.php
** templateDetails.xml

== Creating a basic templateDetails.xml file ==
The <tt>templateDetails.xml</tt> file is essential. Without it, your template won't be seen by Joomla!. The file holds key [[Wikipedia:Metadata|metadata]] about the template.

The syntax of the file is different for each Joomla version.

For {{JVer|1.5}}, use the following:

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE install PUBLIC "-//Joomla! 1.5//DTD template 1.0//EN" "http://www.joomla.org/xml/dtd/1.5/template-install.dtd">
<install version="1.5" type="template">
<name>mynewtemplate</name>
<creationDate>2008-05-01</creationDate>
<author>John Doe</author>
<authorEmail>john@example.com</authorEmail>
<authorUrl>http://www.example.com</authorUrl>
<copyright>John Doe 2008</copyright>
<license>GNU/GPL</license>
<version>1.0.2</version>
<description>My New Template</description>
<files>
<filename>index.php</filename>
<filename>templateDetails.xml</filename>
<folder>images</folder>
<folder>css</folder>
</files>
<positions>
<position>breadcrumb</position>
<position>left</position>
<position>right</position>
<position>top</position>
<position>user1</position>
<position>user2</position>
<position>user3</position>
<position>user4</position>
<position>footer</position>
</positions>
</install>
</source>

For {{JVer|2.5}} and later, use the following version. Change <code>version="2.5"</code> into the version of your Joomla! installation.

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension version="2.5" type="template">
<name>mynewtemplate</name>
<creationDate>2008-05-01</creationDate>
<author>John Doe</author>
<authorEmail>john@example.com</authorEmail>
<authorUrl>http://www.example.com</authorUrl>
<copyright>John Doe 2008</copyright>
<license>GNU/GPL</license>
<version>1.0.2</version>
<description>My New Template</description>
<files>
<filename>index.php</filename>
<filename>templateDetails.xml</filename>
<folder>images</folder>
<folder>css</folder>
</files>
<positions>
<position>breadcrumb</position>
<position>left</position>
<position>right</position>
<position>top</position>
<position>user1</position>
<position>user2</position>
<position>user3</position>
<position>user4</position>
<position>footer</position>
</positions>
</extension>
</source>

So, as you can see, we have a set of information between markup tags (the <code><element></code>s). Your best approach is to cut and paste this into your <tt>templateDetails.xml</tt> file and change the relevant bits (such as <code><name></code> and <code><author></code>).

The <code><files></code> part should contain all the files that you use - you possibly don't know what they are called yet - don't worry, update it later. The <code><folder></code> element can be used to define an entire folder at once.

Leave the positions as they are - these are a common set so you will be able to switch easily from the standard templates.

== Creating a basic index.php file ==
{{:Creating a basic index file}}

This leaves a final file of:
<source lang="php">
<?php defined('_JEXEC') or die('Restricted access');?>
<!DOCTYPE html>
<html xml:lang="<?php echo $this->language; ?>" lang="<?php echo $this->language; ?>" >
<head>
<jdoc:include type="head" />
<link rel="stylesheet" href="<?php echo $this->baseurl ?>/templates/<?php echo $this->template ?>/css/template.css" type="text/css" />
</head>
<body>
<jdoc:include type="modules" name="top" />
<jdoc:include type="component" />
<jdoc:include type="modules" name="bottom" />
</body>
</html>
</source>

== Testing the template ==
Find the template in the Template Manager, select it and click '''Default''' to make it the default template.

{{JVer|1.5}} In Joomla! 1.5, your new template will show up immediately in the [[Help15:Screen.templates.15|Template Manager]], accessible via Extensions -> Template Manager.

{{JVer|2.5}}+ In the Joomla! 2.5 series and later, you first need to tell Joomla! that you have created a new template. This feature is called ''Discover Extensions'' and can be accessed via Extensions -> Extension Manager -> Discover (i.e. the Discover ''tab''). Click '''Discover''' (i.e. the Discover ''button'') to discover your template, then select it and click '''Install''' to install it. Now your template should show up in the [[Help16:Extensions_Template_Manager_Styles|Template Manager (Styles)]], accessible via Extensions -> Template Manager.

Note you can create your template outside of Joomla and simply install it like any regular extension.

HINT: there are a couple of ways you can preview your index page as you put it together, either insert the styles into the head of the index page or directly link it to the style sheet you will be using temporarily. You can remove these links before packaging the file.

== Packaging the template for installation ==
{{:Packaging_a_extension}}

== Conclusion ==

You should now have created a template that works. It won't look like much yet. The best thing to do now is start experimenting with the layout.

<noinclude>
[[Category:Templates]]
[[Category:Tutorials]]
</noinclude>

Editor form field type

2015-06-18T09:30:58Z

Flimm: /* See also */ Fixed broken link

The '''Editor''' field type provides a WYSIWYG editor.

* '''type''' (mandatory) must be ''editor''.
* '''name''' (mandatory) is the unique name of the parameter.
* '''label''' (mandatory) (translatable) is the descriptive title of the field.
* '''width''' (optional) defines the width (in pixels) of the wysiwyg editor and defaults to 100%.
* '''height''' (optional) defines the height (in pixels) of the wysiwyg editor and defaults to 250px.
* '''cols''' (optional) defines the width of the editor (in columns).
* '''rows''' (optional) defines the height of the editor (in rows).
* '''buttons''' (optional) can be an array of plugin buttons to be excluded or set to false. The default editors-xtd are: article, image, pagebreak and readmore.
* '''hide''' (optional) array of plugin buttons to be hidden. eg... set buttons="true" hide="readmore,pagebreak"
* '''editor''' specifies the editor to be used and can include two options (editor="desired|alternative")
* '''filter''' (optional) allow the system to save certain html tags or raw data.

Example XML Definition
<source lang="xml"><field name="test1" label ="Test Field" type="editor" width="300" filter="safehtml" /></source>
<noinclude>

=== See also ===
* [[Textarea form field type]]
* [[Standard form field types|Table of all standard form field types]]
[[Category:Standard form field types]]
</noinclude>

Packaging a extension

2015-06-16T15:22:38Z

Flimm: There's no need to provide the -a to zip

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

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

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

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

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

[[Category:Extension development]]

J3.x:Adding JavaScript and CSS to the page

2015-05-22T11:56:30Z

Flimm: Add links to API and more details about minification

{{notice|The API of the JHtml::script() and JHtml::stylesheet() method changed after Joomla 1.5 - it worked but was deprecated in Joomla 2.5 and support for the old API was removed in Joomla 3.x|title=API Change}}

== Inserting from a File ==
To have a well-formed HTML document, you must put all references to Javascript and CSS files within the <code><head></code> portion. Since Joomla! generates all the HTML that makes up a page before output, it is possible to add these references within the <head> tags from your extension. The simplest way to do this is to make use of the functionality built in to Joomla!

===JDocument===
This is a much less flexible option. However it is more efficient for a large number of scenarios such as including a stylesheet in a template. Of course, you will also need to manually code some of the steps that would be done automatically using the JHtml method below.

First, get a reference to the current document object:
<source lang="php">
$document = JFactory::getDocument();
</source>

Then for a stylesheet, use this code:
<source lang="php">
$document->addStyleSheet($url);
</source>

To add a Javascript file, use this code:
<source lang="php">
$document->addScript($url);
</source>

where <code>$url</code> is the variable containing the full path to the javascript or CSS file for example:
<code>JUri::base() . 'templates/custom/js/sample.js'</code>

Note this will **NOT** include Mootools or jQuery. If your script requires Mootools or jQuery see [[Javascript_Frameworks]] for full details on how to include them (note jQuery can only be included natively on Joomla 3.0+).

===JHtml===
JHtml offers much more flexibility than JDocument, whilst using the same base functionality - indeed at the end of the day JHtml will call <code>JFactory::getDocument()->addStyleSheet()</code> or <code>JFactory::getDocument()->addScript()</code>.

If you wish to just include a straight file path, in a template for example, then you are better using JDocument. However if you wish to take into account whether debug is enabled to include a compressed script or take advantage of template overridable scripts and stylesheets then using JHtml is generally better. It is recommended all 3rd Party Developers use JHtml to allow template overrides of their CSS and javascript for template designers.

====JHtml::script====

The following is the signature of this function, you can see more at [https://api.joomla.org/cms-3/classes/JHtml.html#method_script JHtml::script on api.joomla.org]:

<source lang="php">
script(string $file, boolean $framework = false, boolean $relative = false, boolean $path_only = false, boolean $detect_browser = true, boolean $detect_debug = true) : mixed</source>

Using JHtml to include a javascript file can bring you several benefits. The first of these is if your javascript file has a mootools dependency then you can automatically include it by setting the second parameter of this method to true as below
<source lang="php">
<?php
JHtml::script(JUri::base() . 'templates/custom/js/sample.js', true);
?>
</source>

The third parameter of this method allows template overridable javascript files to allow greater customization of extensions. The first parameter is now assumes you are starting in the <code>JPATH_BASE/media</code> folder - within here you specify your extension name followed by the name of your javascript file. The path searched is then <code>JPATH_BASE/media/com_search/js/search.js</code> for the following JHtml snippet

<source lang="php">
<?php
JHtml::script('com_search/search.js', false, true);
?>
</source>

Note the js subdirectory that is searched in the com_search directory shouldn't be specified in the JHtml method.

However on top of this if a file exists in <code>js/com_search/search.js</code> then this will be included instead. For example say a extension has a mootools dependent file but the user only wants jQuery to be loaded. This means that a user could override the file with a jQuery version.

By default Joomla will automatically include a compressed and uncompressed version of any scripts depending on whether debug mode is turned off or on. Call your compressed script search.min.js and the uncompressed version script-uncompressed.js or script.js to use this functionality and aid with debugging of any scripts. You should call the function with the compressed version, like this:

<source lang="php">
<?php
JHtml::script('com_search/search.min.js');
?>
</source>

Furthermore you can include browser specific files. Joomla can look for the files of the following types
* filename.ext
* filename_browser.ext
* filename_browser_major.ext
* filename_browser_major_minor.ext

This can allow you to include internet explorer 6 specific files for example. By having a search.js for general use with a search_msie_6.js for a file with extra internet explorer 6 fixes.

====JHtml::stylesheet====

The following is the signature of this function, you can see more at [https://api.joomla.org/cms-3/classes/JHtml.html#method_stylesheet JHtml::stylesheet on api.joomla.org]:

Using JHtml to include a CSS file can bring you several benefits. The first of these is allowing template overridable CSS files to allow greater customization of extensions. Setting the third parameter to true now assumes you are starting in the <code>JPATH_BASE/media</code> folder - within here you specify your extension name followed by the name of your CSS file. The path searched is then <code>JPATH_BASE/media/com_search/css/search.css</code> for the following JHtml snippet

<source lang="php">
<?php
JHtml::stylesheet('com_search/search.css', array(), true);
?>
</source>

Note the <code>css</code> subdirectory that is searched in the <code>com_search</code> directory shouldn't be specified in the JHtml method.

However on top of this if a file exists in <code>css/com_search/search.css</code> then this will be included instead. This allows people to customize the appearance of an extension to better match their templates styling.

Furthermore you can include browser specific files. Joomla can look for the files of the following types
* filename.ext
* filename_browser.ext
* filename_browser_major.ext
* filename_browser_major_minor.ext

This can allow you to include internet explorer 6 specific files for example. By having a search.css for general use with a search_msie_6.css for a file with extra internet explorer 6 fixes.

Similarly as with JHtml::script, if $detect_debug is true and you pass it a minified stylesheet example.min.css, when debug mode is on, the unminified stylesheet will be used instead, if it exists.

== Inserting inline scripts from within a PHP file ==
If your Javascript or CSS are generated using PHP, you can add the script or stylesheet directly into the head of your document:
<source lang="php">
$document = JFactory::getDocument();

// Add Javascript
$document->addScriptDeclaration('
window.event("domready", function() {
alert("An inline JavaScript Declaration");
});
');

// Add styles
$style = 'body {'
. 'background: #00ff00;'
. 'color: rgb(0,0,255);'
. '}';
$document->addStyleDeclaration($style);
</source>

=== Javascript Example ===
For example, the following code is used to define a custom tool tip that takes advantage of mootools.
<source lang="php">
function getToolTipJS($toolTipVarName, $toolTipClassName){
$javascript = 'window.addEvent(\"domready\", function(){' ."\n";
$javascript .= "\t" .'var $toolTipVarName = new Tips($$("' . $toolTipVarName .'"), {' ."\n";
$javascript .= "\t\t" .'className: "' .$toolTipClassName .'",' ."\n";
$javascript .= "\t\t" .'initialize: function(){' ."\n";
$javascript .= "\t\t\t" .'this.fx = new Fx.Style(this.toolTip, "opacity", {duration: 500, wait: false}).set(0);' ."\n";
$javascript .= "\t\t" .'},' ."\n";
$javascript .= "\t\t" .'onShow: function(toolTip){' ."\n";
$javascript .= "\t\t\t" .'this.fx.start(1);' ."\n";
$javascript .= "\t\t" .'},' ."\n";
$javascript .= "\t\t" .'onHide: function(toolTip) {' ."\n";
$javascript .= "\t\t\t" .'this.fx.start(0);' ."\n";
$javascript .= "\t\t" .'}' ."\n";
$javascript .= "\t" .'});' ."\n";
$javascript .= '});' ."\n\n";
return $javascript;
}

$document = JFactory::getDocument();
$document->addStyleSheet("/joomla/components/com_mycustomcomponent/css/mytooltip.css",'text/css',"screen");
$document->addScriptDeclaration(getToolTipJS("mytool","MyToolTip"));
</source>
Note that in order for this Javascript to be functionally useful, it would be necessary to include the appropriate class name in the HTML, as well as providing the <code>mytooltip.css</code> file. Both are outside the scope of this article.

=== CSS Examples ===
This is also useful if your inserting a form field of CSS into your code. For example in a module, you might want a user to choose to call the colour of the border. After calling the form fields value and assigning it a variable $bordercolor in mod_example.php. Then in tmpl/default.php you can include the following
<source lang="php">
$document = JFactory::getDocument();
$document->addStyleSheet('mod_example/mod_example.css', array(), true);
$style = '#example {
border-color:#' . $bordercolor . ';
}';
$document->addStyleDeclaration( $style );
</source>
Here mod_example.css contains the CSS file of any non-parameter based styles. Then the bordercolor parameter/form field is added in separately

==Add Custom Tag==
There will be some occasions where even these functions are not flexible enough, as they are limited to writing the contents of <code><script /></code> or <code><style /></code> tags, and cannot add anything outside those tags. One example would be the inclusion of a stylesheet link within conditional comments, so that it is picked up only by Internet Explorer 6 and earlier. To do this, use <code>$document->addCustomTag</code>:
<source lang="php">
$stylelink = '' ."\n";

$document = JFactory::getDocument();
$document->addCustomTag($stylelink);
</source>

<noinclude>
[[Category:Development]] [[Category:Tutorials]][[Category:Component Development]][[Category:Module Development]] [[Category:JavaScript]] [[Category:CSS]]
</noinclude>

User:Flimm

2015-05-22T11:18:22Z

Flimm: Created page with "Experienced developer but a beginner at Joomla. Joomla StackExchange profile: joomla.stackexchange.com/users/5239/flimm Stack Overflow profile: stackoverflow.com/users/24769..."

Experienced developer but a beginner at Joomla.

Joomla StackExchange profile: joomla.stackexchange.com/users/5239/flimm

Stack Overflow profile: stackoverflow.com/users/247696/flimm