Joomla! Documentation - User contributions [en]

Talk:How to debug your code

2014-06-30T22:14:43Z

Purplebeanie: Created page with "Hi, does anyone know if there are any guidelines as to what speed and memory performance "SHOULD" be like at each of the event points? ie: onAfterInitialize etc? ~~~~"

Hi, does anyone know if there are any guidelines as to what speed and memory performance "SHOULD" be like at each of the event points? ie: onAfterInitialize etc?

[[User:Purplebeanie|Purplebeanie]] ([[User talk:Purplebeanie|talk]]) 17:14, 30 June 2014 (CDT)

How to debug your code

2014-06-30T22:11:07Z

Purplebeanie: Adds a little more information about JDebug

{{page|needs improvement|Updated Joomla! System-debug plugin features not listed here.}}

==The Easy Way 1 (echo)==
The simplest way to see what is going on inside your code is to temporarily add echo statements for variables to show their values on the screen. For example, say you want to know what the value of some variables are when $i is "5". You could use code like this:

<source lang="PHP">for ( $i = 0; $i < 10; $i++ ) {
if ( $i == 5 ) {
echo '$i=' . $i;
// other echo statements
}
}</source>

This works for simple situations. However, if you are planning on doing a lot of Joomla! development, it is worth the effort to install and learn an integrated development environment (IDE) that includes a real PHP debugger.

==The Easy Way 2 (joomla message)==
Your code won't always display simple echo statements. In that case you can try this alternative, still easy way:
<source lang="PHP">JFactory::getApplication()->enqueueMessage( 'Some debug string(s)');</source>
You can choose different [[Display_error_messages_and_notices|message types]] which corresponds to grouping with different styles (colors mainly).

==Using an IDE==
Check this 3 minutes video that shows [http://www.youtube.com/watch?v=sP4dHAuq2kc&feature=youtu.be how you can debug your code with a Browser and an IDE]

{{#ev:youtube|sP4dHAuq2kc}}

Many Joomla! developers use the Eclipse IDE. This is free and includes a debugger. Instructions for installing it are available at [[Setting up your workstation for Joomla! development]].

==Using the PHP Expert editor==
Another option is the PHP Expert editor with an installed extension for debugging. Add the following lines to the php.ini file:

extension=php_dbg.dll
[Debugger]
debugger.enabled=on
debugger.profiler_enabled=off

It is best to set profiler_enable to "off". Then you need to set options in the Run/Options menu to use HTTP-server and the directory in which your script is located.

If all options are correct, you may run your script in debug mode by clicking on the Debug button (F8)
==J!Dump==
An often handy extension that can be found in the JED is the J!Dump extension that will allow you to dump variable, stack traces, and system information into a popup window at run time. This extension works like the PHP command `var_dump` but formats the output in a much more readable fashion.
==JDEBUG==
To check whether the Website is in the debug mode, test the JDEBUG variable:
<source lang="PHP">
if(JDEBUG){
//whatever debugging code you want to run
}
</source>

JDEBUG can be enabled from the Joomla! Global Configuration under the System tab. Once enabled the JDEBUG module will be published to the bottom of each page.

[[File:Jdebug-module.jpg|framed|center|The JDebug Module]]

This module provides important information that can assist in debugging and improving the performance of your component.

===Profile Information===

The Profile Information tab from the JDEBUG module provides information about the time and memory taken to render the page based on each of the application events. This can help to identify areas outside of network speed that are contributing to long page load times high server memory usage.

[[File:Jdebug-profile.jpg|framed|center|JDEBUG Profile]]

===Database Queries===

One of the most useful tabs is the Database Queries tab. This will provide a log of all queries that have been executed while loading the page and identify both the time taken to execute the query and whether duplicate queries have occurred. This is particularly useful when debugging performance problems on larger components as duplicate queries are often a contributing factor.

[[File:Jdebug-query.jpg|framed|center]]

==JFirePHP==
Use the Joomla [http://extensions.joomla.org/extensions/miscellaneous/development/11343 JFirePHP extension].

[[Category:Development]]
[[Category:Video]]

File:Jdebug-query-en.jpg

2014-06-30T22:09:47Z

Purplebeanie: Display detailed information about queries.

== Summary ==
Display detailed information about queries.
== Licensing ==
{{GPL}}

File:Jdebug-profile-en.jpg

2014-06-30T22:04:46Z

Purplebeanie:

== Licensing ==
{{GPL}}

File:Jdebug-module-en.jpg

2014-06-30T21:56:50Z

Purplebeanie: Screenshot of JDEBUG module published.

== Summary ==
Screenshot of JDEBUG module published.
== Licensing ==
{{GPL}}

Framework talk:Home

2014-01-29T23:38:09Z

Purplebeanie: Created page with "~~~~ Just added links to the Framework:Getting_Started page under a section Getting Started"

[[User:Purplebeanie|Purplebeanie]] ([[User talk:Purplebeanie|talk]]) 17:38, 29 January 2014 (CST)
Just added links to the Framework:Getting_Started page under a section Getting Started

Framework:Home

2014-01-29T23:37:27Z

Purplebeanie: Added getting started section and link to Framemwork::Getting_Started

{{:{{FULLPAGENAME}}/header}}
<div style="float:right; padding-left:15px;"><markdown>
[![Build Status](https://travis-ci.org/joomla/joomla-framework.png?branch=master)](https://travis-ci.org/joomla/joomla-framework)
</markdown></div>
== What is the Joomla! Framework ? ==
__TOC__
The <code>Joomla! Framework</code> is a framework for writing web and command line applications in PHP. It is free and open source software, distributed under the GNU General Public License version 2 or later.

It is composed of code originally developed for the Joomla Content Management System (CMS). For more information about the Joomla CMS visit http://www.joomla.org/about-joomla.html.

For news and information about developing with Joomla, please visit http://developer.joomla.org.

View the Joomla Framework API Documentation at http://api.joomla.org and is powered by [http://www.phpdoc.org phpDocumentor 2].

You can discuss Joomla Framework development by joining the mailing list at http://groups.google.com/group/joomla-dev-framework.

== Requirements ==

* PHP 5.3.10

== Installation ==
=== Via Composer ===

* Create a project and add a <code>composer.json</code> file to it with the content :

<pre class="json">{
"require": {
"joomla/joomla-framework": "dev-master"
}
}</pre>
* Download Composer

<code>curl -sS <nowiki>https://getcomposer.org/installer</nowiki> | php</code>

* Install the Joomla Framework

<code>php composer.phar install</code>

=== Via Git ===

<code><nowiki>git clone git://github.com/joomla/joomla-framework.git</nowiki></code>

== Getting Started ==

This page has some questions and answers to some common problems that may occur getting started with your first app. [[Framework:Getting_Started]]. Another great resource is the sample framework app. You can find this on github here. https://github.com/dbhurley/framework-app

== Documentation ==

General documentation about the Joomla Framework can be found under the [https://github.com/joomla/joomla-framework/tree/master/docs /docs] folder of the Git repository. In addition, each package has documentation in a <code>README.md</code> file.

== Reporting Bugs and Issue ==

Bugs and issues found in the Joomla Framework code can be reported on the [https://github.com/joomla/joomla-framework/issues Issues] list.

== Contributing ==

All kind of contributions are welcome. Please read about how to contribute [https://github.com/joomla/joomla-framework/blob/master/CONTRIBUTING.markdown here].

You may find tasks you can do on the [https://github.com/joomla/joomla-framework/issues Issues] list by filtering on labels and milestones

[[Category:Joomla! Framework]]

Framework talk:Getting Started

2014-01-29T23:32:39Z

Purplebeanie: Created page with "~~~~ I've created this page to try and answer some problems I was bumping into getting started and couldn't find easy answers for on Google so referred back to source code. H..."

[[User:Purplebeanie|Purplebeanie]] ([[User talk:Purplebeanie|talk]]) 17:32, 29 January 2014 (CST)
I've created this page to try and answer some problems I was bumping into getting started and couldn't find easy answers for on Google so referred back to source code. Hopefully these might help reduce the learning curve.

Framework:Getting Started

2014-01-29T23:31:17Z

Purplebeanie: This page has some Q&A's for some of the issues I encountered when getting started with the Framework

These are some questions and answers that may help make getting started with the Framework easier.

==Why does the router keep throwing "Unable to handle request for route"==

This error is generated when the \Joomla\Router\Router class is unable to find a valid route to match the URL the user has entered.

This could be due to:

* There is no route defined for the resource and the router does not have a defaultController (defined using $router->setDefaultController(fully namespaces controller name)). Check to see if a route exists, or the defaultController has been set.
* You have not created a .htaccess file to rewrite the URL To remove the index.php component of the URL. Use the example .htaccess in the framework-app. (https://github.com/dbhurley/framework-app/blob/master/www/.htaccess)

==How do I create a default route when no existing route matches?==

A default controller can be created for the Joomla\Router\Router class. This is used when no existing route matches the request URI.

To define a default controller call the \Joomla\Router\Router class setDefaultController function and pass the fully namespaced controller name you wish to use:

<source lang="php">
$router->setDefultControllerPrefix('App');
$router->setDefaultController('\Controller\DefaultController');</source>

This will attempt to load the DefaultController.php file from the App/Controller directory. The class name would be DefaultController.

==How can I easily create a lot of routes?==

The \Joomla\Router\Router class has a function addMaps that takes an array of routes.

<source lang="php">
$router->addMaps(my array of routes)</source>

These can be loaded from an array defined elsewhere or from an external file. The framework-app (https://github.com/dbhurley/framework-app/) shows how to load these from an external JSON file.

<source lang="php">
$router = new Router();
$maps = json_decode(file_get_contents(JPATH_CONFIGURATION.'/routes.json'));
$router->addMaps($maps);</source>

I find creating routes in a routes.json file easier to manage.

==How do I connect to the database from a Controller?==

Connecting to the database is managed through the \Joomla\Database\DatabaseFactory class. While you could create this each time in each controller this would be extra code to manage for any changes. I found the easiest way was to create this when bootstrapping the application and maintaining a reference in the AbstractWebApplication class.

Much of this code has been lifted from the Framework-app at (https://github.com/dbhurley/framework-app).

First, create a json file called config.json in the App/Config directory:

<source lang="javascript">
{
"database":{"driver":"mysql","host":"localhost","user":"root","password":"root","name":"mydatabase","prefix":"app_"},
"system":{"list_limit":"20","gzip":"0","offset":"UTC"},"languages":["en-GB"]
}</source>

Then when bootstrapping your app (maybe in the index.php) do the following:

<source lang="php">
$config = json_decode(file_get_contents(JPATH_CONFIGURATION.'/config.json'),true);
$application = new \App\App(null,new \Joomla\Registry\Registry($config));
$application->execute();</source>

Then in the doExecute() method of your app create a reference to the database:

<source lang="php">
$dbFactory = new Database\DatabaseFactory;
$this->db = $dbFactory->getDriver(
$this->get('database.driver'),
array(
'host'=>$this->get('database.host'),
'user'=>$this->get('database.user'),
'password'=>$this->get('database.password'),
'port'=>$this->get('database.port'),
'socket'=>$this->get('database.socket'),
'database'=>$this->get('database.name'),
)
);</source>

In your controller the database can then be accessed using:

<source lang="php">
$app = $this->getApplication();
$db = $app->db;</source>

User:Purplebeanie

2014-01-29T22:53:29Z

Purplebeanie: Created page with "A Joomla user, component developer and recently started using Joomla Framework for standalone web apps."

A Joomla user, component developer and recently started using Joomla Framework for standalone web apps.

J1.5 talk:Creating a content plugin

2012-05-14T06:52:28Z

Purplebeanie:

I edited the part concerning installing ini files as it was confusing when the inis were placed in a language/xx-XX/ folder in the pack. It looked as if these files could be installed in the site language folder. Plugins in that regard are very different from components and modules.

== Updating to joomla 1.6/1.7/2.5 ==

this page needs to be updated to Joomla! 1.6, 1.7 & 2.5

== Loading languages in plugins ==

I added the section about using another component / plugins language. I needed to do this recently for an extension with a plugin and component and this was the only page I could find about loading languages. [[User:Purplebeanie|Purplebeanie]] 01:52, 14 May 2012 (CDT)

J1.5:Creating a content plugin

2012-05-14T06:50:31Z

Purplebeanie: /* INI file(s) */ mentioned that you can load an alternative component or plugin's language.

==Description==
There are lots of abilities of the use of a Content Plugin. They all have to do with the display of your content and so your articles. You will need at least two files for this Plugin. An XML file and a PHP file. Because there are so many differences between two Content Plugins in the PHP file, two examples of them will be explained in this document. Also a part about internationalization (with INI files) is added. And last but not least: the Joomla! Core Content Plugin coding examples and the quick tips.

==XML file==
The XML file is named the same as the PHP file, and is one of the two required files.
Always start off with the XML tag and define that it is written in a UTF-8 format.
<source lang="xml"><?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE install
PUBLIC "-//Joomla! 1.5//DTD plugin 1.0//EN" "http://www.joomla.org/xml/dtd/1.5/plugin-install.dtd">
To define that the plugin has to be a content plugin, add this line:
<source lang="xml"><install version="1.5" type="plugin" group="content"></source>
The type will define it is a Plugin, the group defines the Plugin is in the group of Content Plugins.

After that, add some information about yourself and the Plugin, like this:
<source lang="xml">
<name>Name of your Content Plugin</name>
<creationDate>Created Date</creationDate>
<author>Your name</author>
<authorEmail>Your e-mail address</authorEmail>
<authorUrl>Your website</authorUrl>
<copyright>Copyright</copyright>
<license>License, for example GNU/GPL</license>
<version>Version of the plugin</version>
<description>Description of the Plugin; showed with installation and when editing
the Plugin in the Plugin Manager</description></source>
And now include your PHP file to the Content Plugin. The name of this file should be the same as the name of this XML file. Put this name also behind the plugin="" part.

You could also add more files for your plugin, for example an image. Just add another row between <files> and </files>, and then place the file between <filename> tags.
<source lang="xml">
<files>
<filename plugin="nameofplugin">nameofplugin.php</filename>
</files></source>

Some files, like .js or .css, are not recognized and will cause an error when you try to install the plugin. For these, simply create a new folder in the plugin directory, then add the files to the folder. Then add a line for the folder in the <files> tags. Of course, .js and .css files might be better managed better as part of the template, but if these are plugin specific then they could go here.

<source lang="xml">
<files>
<folder>scripts</folder>
<folder>css</folder>
</files></source>

For the internationalization, we will use language files. This is not required, but people from other countries will love it if they can easily translate your plugin to their own language. Plugin language files are always installed in administrator/languages/xx-XX/ where xx-XX is the code for a language already installed in Joomla.
The language tags can be found here: [http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes] (use the ISO 639-1 column) and here: [http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements]
<source lang="xml">
<languages>
<language tag="en-GB">en-GB.plg_content_nameofplugin.ini</language>
</languages></source>
Optionally, you could add some parameters to the Plugin. These will look like this:
<source lang="xml">
<params>
<param name="paramname" type="typeofparameter" default="defaultsetting" label="title" description="description"/>
</params></source>
*'''Param name:''' The name of the parameter. You will need this when creating the PHP file.
*'''Param type:''' You could choose between several types of parameters. Look at this document to learn something about the different types: [[Using the core parameter types]]
*'''Param default:''' The default setting for this parameter.
*'''Param label:''' The name of this parameter displayed in the edit screen of this Plugin in the Plugin Manager.
*'''Param description:''' The text which appears as a tool tip for this parameter.
When you do not want to use parameters, add the following tag:
<source lang="xml"><params/></source>

And do not forget to end your XML file with the following tag:
<source lang="xml"></install></source>

==PHP file==
Start your PHP file with the general licensing and author information about your content plugin.

<source lang="PHP"><?php
/**
* @version $Id: nameofplugin.php revision date lasteditedby $
* @package Joomla
* @subpackage Content
* @copyright Copyright (C) 2005 - 2008 Open Source Matters. All rights reserved.
* @license GNU/GPL, see LICENSE.php
* Joomla! is free software. This version may have been modified pursuant
* to the GNU General Public License, and as distributed it includes or
* is derivative of works licensed under the GNU General Public License or
* other free or open source software licenses.
* See COPYRIGHT.php for copyright notices and details.
*/ </source>

Next, always put the following code in any PHP file:
<source lang="PHP">
// no direct access
defined( '_JEXEC' ) or die( 'Restricted access' );</source>
This prevents people from directly accessing this PHP file.

After that, you should import the general plugin file of Joomla!'s library
<source lang="PHP">jimport( 'joomla.plugin.plugin' );</source>

To indicate that you're writing a Content plugin, add the following code.
<source lang="PHP">class plgContentNameofplugin extends JPlugin {</source>
Please note the use of capital letters. You should replace Nameofplugin by the name of your own plugin.

Now, it's time to construct the plugin:
<source lang="PHP">/**
* Constructor
*
* For php4 compatability we must not use the __constructor as a constructor for plugins
* because func_get_args ( void ) returns a copy of all passed arguments NOT references.
* This causes problems with cross-referencing necessary for the observer design pattern.
*
* @param object $subject The object to observe
* @param object $params The object that holds the plugin parameters
* @since 1.5
*/
function plgContentNameofplugin( &$subject, $params )
{
parent::__construct( $subject, $params );
}</source>

You should choose now at which moment the plugin should be rendered. You can choose from the following:

* onBeforeContentSave : This is an event that is called right before the content is saved into the database.
* onAfterContentSave : This is an event that is called after the content is saved into the database.
* onPrepareContent : This is the first stage in preparing content for output and is the most common point for content orientated plugins to do their work.
* onAfterDisplayTitle : This is a request for information that should be placed between the content title and the content body.
* onBeforeDisplayContent : This is a request for information that should be placed immediately before the generated content.
* onAfterDisplayContent : This is a request for information that should be placed immediately after the generated content.

More information on which type you should use for your plugin, including several examples, can be found here: [[Plugin events/Content]]

===onBeforeContentSave===
Use the following code:
<source lang="PHP"> function onBeforeContentSave( &$article, $isNew )
{
global $mainframe;
//add your plugin codes here
return true;
}</source>
The parameters article and isNew should contain the following:
* article : A reference to the JTableContent object that is being saved which holds the article data.
* isNew : A boolean which is set to true if the content is about to be created.

===onAfterContentSave===
Use the following code:
<source lang="PHP"> function onAfterContentSave( &$article, $isNew )
{
global $mainframe;
//add your plugin codes here
return true;
}</source>
The parameters article and isNew should contain the following:
* article : A reference to the JTableContent object that was saved which holds the article data.
* isNew : A boolean which is set to true if the content was created.

===onPrepareContent===
Use the following code:
<source lang="PHP"> function onPrepareContent( &$article, &$params, $limitstart )
{
global $mainframe;
//add your plugin codes here
//no return value
}</source>
The parameters article, params and limitstart should contain the following:
* article : A reference to the article that is being rendered by the view.
* params : A reference to an associative array of relevant parameters. The view determines what it considers to be relevant and passes that information along.
* limitstart : An integer that determines the "page" of the content that is to be generated. Note that in the context of views that might not generate HTML output, a page is a reasonably abstract concept that depends on the context.

===onAfterDisplayTitle===
Use the following code:
<source lang="PHP"> function onAfterDisplayTitle( &$article, &$params, $limitstart )
{
global $mainframe;
//add your plugin codes here
return '';
//return a string value. Returned value from this event will be displayed in a placeholder.
// Most templates display this placeholder after the article separator.
}</source>
The parameters article, params and limitstart should contain the following:
* article : A reference to the article that is being rendered by the view.
* params : A reference to an associative array of relevant parameters. The view determines what it considers to be relevant and passes that information along.
* limitstart : An integer that determines the "page" of the content that is to be generated. Note that in the context of views that might not generate HTML output, a page is a reasonably abstract concept that depends on the context.

===onBeforeDisplayContent===
Use the following code:
<source lang="PHP"> function onBeforeDisplayContent( &$article, &$params, $limitstart )
{
global $mainframe;
//add your plugin codes here
return '';
//return a string value. Returned value from this event will be displayed in a placeholder.
// Most templates display this placeholder after the article separator.
}</source>

The parameters article, params and limitstart should contain the following:
* article : A reference to the article that is being rendered by the view.
* params : A reference to an associative array of relevant parameters. The view determines what it considers to be relevant and passes that information along.
* limitstart : An integer that determines the "page" of the content that is to be generated. Note that in the context of views that might not generate HTML output, a page is a reasonably abstract concept that depends on the context.

===onAfterDisplayContent===
Use the following code:
<source lang="PHP"> function onAfterDisplayContent( &$article, &$params, $limitstart )
{
global $mainframe;
//add your plugin codes here
return '';
//return a string value. Returned value from this event will be displayed in a placeholder.
// Most templates display this placeholder after the article separator.
}</source>

The parameters article, params and limitstart should contain the following:
* article : A reference to the article that is being rendered by the view.
* params : A reference to an associative array of relevant parameters. The view determines what it considers to be relevant and passes that information along.
* limitstart : An integer that determines the "page" of the content that is to be generated. Note that in the context of views that might not generate HTML output, a page is a reasonably abstract concept that depends on the context.

==PHP file - Example==
This example PHP file is about the Content Plugin load module. It is a plugin made for displaying modules within the articles.
The commented PHP file used in this example is the file which will be included in Joomla! 1.6. This has been done because the content plugin files in Joomla! 1.5 are not refactored yet to the new standards.
<source lang="PHP">
<?php
// The general information at the top of each file
/**
* @version $Id$
* @package Joomla
* @copyright Copyright (C) 2005 - 2009 Open Source Matters, Inc. All rights reserved.
* @license GNU General Public License, see LICENSE.php
*/

// No direct access allowed to this file
defined( '_JEXEC' ) or die( 'Restricted access' );

// Import Joomla! Plugin library file
jimport('joomla.plugin.plugin');

//The Content plugin Loadmodule
class plgContentLoadmodule extends JPlugin
{
/**
* Plugin that loads module positions within content
*/
// onPrepareContent, meaning the plugin is rendered at the first stage in preparing content for output
public function onPrepareContent( &$row, &$params, $page=0 )
{
// A database connection is created
$db = JFactory::getDBO();
// simple performance check to determine whether bot should process further
if ( JString::strpos( $row->text, 'loadposition' ) === false ) {
return true;
}

// expression to search for
$regex = '/{loadposition\s*.*?}/i';

// check whether plugin has been unpublished
if ( !$this->params->get( 'enabled', 1 ) ) {
$row->text = preg_replace( $regex, '', $row->text );
return true;
}

// find all instances of plugin and put in $matches
preg_match_all( $regex, $row->text, $matches );

// Number of plugins
$count = count( $matches[0] );

// plugin only processes if there are any instances of the plugin in the text
if ( $count ) {
// Get plugin parameters
$style = $this->params->def( 'style', -2 );
$this->_process( $row, $matches, $count, $regex, $style );
}
// No return value
}
// The proccessing function
protected function _process( &$row, &$matches, $count, $regex, $style )
{
for ( $i=0; $i < $count; $i++ )
{
$load = str_replace( 'loadposition', '', $matches[0][$i] );
$load = str_replace( '{', '', $load );
$load = str_replace( '}', '', $load );
$load = trim( $load );

$modules = $this->_load( $load, $style );
$row->text = preg_replace( '{'. $matches[0][$i] .'}', $modules, $row->text );
}

// removes tags without matching module positions
$row->text = preg_replace( $regex, '', $row->text );
}
// The function who takes care for the 'completing' of the plugins' actions : loading the module(s)
protected function _load( $position, $style=-2 )
{
$document = &JFactory::getDocument();
$renderer = $document->loadRenderer('module');
$params = array('style'=>$style);

$contents = '';
foreach (JModuleHelper::getModules($position) as $mod) {
$contents .= $renderer->render($mod, $params);
}
return $contents;
}
}
</source>

==INI file(s)==
For internationalization it is good to use the INI files. You can add to the language file everything which outputs text to the user, in this order:
*XML description tag
*XML label and description attributes from parameters
*JText::_( 'string' ) used by the plugin

You should create two files: One for the backend and one for the front end. The naming should match the path of the extension. For example, if we were creating a content plugin named 'example' and it is installed at plugins/content/example, then our files should be named:
*en-US.plg_content_example.ini (Frontend)
*en-US.plg_content_example.sys.ini (Backend)

Start your INI file with something like this:
<source lang="INI"># $Id: en-GB.plg_content_nameofplugin.ini
# Joomla! Project
# Copyright (C) 2005 - 2007 Open Source Matters. All rights reserved.
# License http://www.gnu.org/licenses/gpl-2.0.html GNU/GPL, see LICENSE.php
# Note : All ini files need to be saved as UTF-8 - No BOM</source>
Of course, you could also add other information, like the author.

Joomla 1.6+ uses the ; at the start of the line, rather than the #.

Backend Example:
<source lang="XML">
<param name="mode" type="list" default="1" label="PLG_CONTENT_EXAMPLE_MODE" description="PLG_CONTENT_EXAMPLE_EMAILS_DISPLAYED">
<option value="0">PLG_CONTENT_EXAMPLE_NONLINKABLE_TEXT</option>
<option value="1">PLG_CONTENT_EXAMPLE_LINKABLE_TEXT</option>
</param></source>

The localized strings are translated in the ini file:
<source lang="INI">
PLG_CONTENT_EXAMPLE_MODE=Mode
PLG_CONTENT_EXAMPLE_EMAILS_DISPLAYED=Select how the e-mails will be displayed
PLG_CONTENT_EXAMPLE_NONLINKABLE_TEXT=Nonlinkable text
PLG_CONTENT_EXAMPLE_LINKABLE_TEXT=As linkable mailto address
</source>

Best practice dictates that LOCALIZED_TAGS are all upper case, no spaces, and begin with the same name as the extension - to avoid interfering with other strings.

The localized tags can then be translated into multiple languages.When you want to make your Content Plugin available in more languages, first add them to the <languages> tag in the XML file. Then create the same INI file, and change the part after the =, for example the dutch version would be:
<source lang="INI">
PLG_CONTENT_EXAMPLE_MODE=Modus
PLG_CONTENT_EXAMPLE_EMAILS_DISPLAYED=Selecteer hoe de e-mails worden weergegeven
PLG_CONTENT_EXAMPLE_NONLINKABLE_TEXT=Niet-linkbare tekst
PLG_CONTENT_EXAMPLE_LINKABLE_TEXT=Als een linkbaar mailto adres
</source>

Frontend Example:
On Joomla 1.6+ you must create a separate file for the front end - as described above. For example:

<source lang="INI">
PLG_CONTENT_EXAMPLE_LINKNAME="The Name of the Link Goes Here!"
</source>

In the plugin's php file, you must load the language file:
<source lang="PHP">
// Load user_profile plugin language
$lang = JFactory::getLanguage();
$lang->load('plg_content_simpleattachment', JPATH_ADMINISTRATOR);
echo JText::_('PLG_CONTENT_EXAMPLE_LINKNAME');
</source>

You could also use another component or plugin's language file. This is useful for maintaining consistent strings between a component, module, and plugin, that are part of the same package.

To load another component or plugin's language files specify it's name in the load statement and specify whether to use the site or administrator language. For example:

<source lang="PHP">
$lang->load('com_someothercomponent',JPATH_ADMINISTRATOR);
</source>

==Coding examples==
There are seven Joomla! Core Content Plugins. These are all not yet refactored to the new standards. For learning how to write good plugins, its better to look at the (refactored) files of Joomla! 1.6.
You can see them 'working' when you go to the Back-end of your Joomla! 1.5 installation, then go to the menu 'Extensions' and select the 'Plugin Manager'. Click on the name of the Plugin to edit it; and see it working. Also watch the content and see what happens when you insert a pagebreak for example.

==Quick tips==
*In the PHP file you often forget to place an semicolon (;) at the end of a row, which causes errors. Check this before you test your Plugin and you will eliminate many errors.
*Take care of the fact that the parameters in the XML file are closed correctly. When you add options for example, you need to close it with </param>.
*It is easy to test on a localhost when you are still busy with editing your Plugin.
*A typical zip will contain the following:
**nameofplugin.XML
**nameofplugin.PHP
**en-GB.plg_content_nameofplugin.ini

[[Category:Articles that require a review]]
[[Category:Tutorials]]
[[Category:Plugin Development]]

J1.5:Creating a content plugin

2012-05-14T06:38:08Z

Purplebeanie: just changed the example of loading a plugin

==Description==
There are lots of abilities of the use of a Content Plugin. They all have to do with the display of your content and so your articles. You will need at least two files for this Plugin. An XML file and a PHP file. Because there are so many differences between two Content Plugins in the PHP file, two examples of them will be explained in this document. Also a part about internationalization (with INI files) is added. And last but not least: the Joomla! Core Content Plugin coding examples and the quick tips.

==XML file==
The XML file is named the same as the PHP file, and is one of the two required files.
Always start off with the XML tag and define that it is written in a UTF-8 format.
<source lang="xml"><?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE install
PUBLIC "-//Joomla! 1.5//DTD plugin 1.0//EN" "http://www.joomla.org/xml/dtd/1.5/plugin-install.dtd">
To define that the plugin has to be a content plugin, add this line:
<source lang="xml"><install version="1.5" type="plugin" group="content"></source>
The type will define it is a Plugin, the group defines the Plugin is in the group of Content Plugins.

After that, add some information about yourself and the Plugin, like this:
<source lang="xml">
<name>Name of your Content Plugin</name>
<creationDate>Created Date</creationDate>
<author>Your name</author>
<authorEmail>Your e-mail address</authorEmail>
<authorUrl>Your website</authorUrl>
<copyright>Copyright</copyright>
<license>License, for example GNU/GPL</license>
<version>Version of the plugin</version>
<description>Description of the Plugin; showed with installation and when editing
the Plugin in the Plugin Manager</description></source>
And now include your PHP file to the Content Plugin. The name of this file should be the same as the name of this XML file. Put this name also behind the plugin="" part.

You could also add more files for your plugin, for example an image. Just add another row between <files> and </files>, and then place the file between <filename> tags.
<source lang="xml">
<files>
<filename plugin="nameofplugin">nameofplugin.php</filename>
</files></source>

Some files, like .js or .css, are not recognized and will cause an error when you try to install the plugin. For these, simply create a new folder in the plugin directory, then add the files to the folder. Then add a line for the folder in the <files> tags. Of course, .js and .css files might be better managed better as part of the template, but if these are plugin specific then they could go here.

<source lang="xml">
<files>
<folder>scripts</folder>
<folder>css</folder>
</files></source>

For the internationalization, we will use language files. This is not required, but people from other countries will love it if they can easily translate your plugin to their own language. Plugin language files are always installed in administrator/languages/xx-XX/ where xx-XX is the code for a language already installed in Joomla.
The language tags can be found here: [http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes] (use the ISO 639-1 column) and here: [http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements]
<source lang="xml">
<languages>
<language tag="en-GB">en-GB.plg_content_nameofplugin.ini</language>
</languages></source>
Optionally, you could add some parameters to the Plugin. These will look like this:
<source lang="xml">
<params>
<param name="paramname" type="typeofparameter" default="defaultsetting" label="title" description="description"/>
</params></source>
*'''Param name:''' The name of the parameter. You will need this when creating the PHP file.
*'''Param type:''' You could choose between several types of parameters. Look at this document to learn something about the different types: [[Using the core parameter types]]
*'''Param default:''' The default setting for this parameter.
*'''Param label:''' The name of this parameter displayed in the edit screen of this Plugin in the Plugin Manager.
*'''Param description:''' The text which appears as a tool tip for this parameter.
When you do not want to use parameters, add the following tag:
<source lang="xml"><params/></source>

And do not forget to end your XML file with the following tag:
<source lang="xml"></install></source>

==PHP file==
Start your PHP file with the general licensing and author information about your content plugin.

<source lang="PHP"><?php
/**
* @version $Id: nameofplugin.php revision date lasteditedby $
* @package Joomla
* @subpackage Content
* @copyright Copyright (C) 2005 - 2008 Open Source Matters. All rights reserved.
* @license GNU/GPL, see LICENSE.php
* Joomla! is free software. This version may have been modified pursuant
* to the GNU General Public License, and as distributed it includes or
* is derivative of works licensed under the GNU General Public License or
* other free or open source software licenses.
* See COPYRIGHT.php for copyright notices and details.
*/ </source>

Next, always put the following code in any PHP file:
<source lang="PHP">
// no direct access
defined( '_JEXEC' ) or die( 'Restricted access' );</source>
This prevents people from directly accessing this PHP file.

After that, you should import the general plugin file of Joomla!'s library
<source lang="PHP">jimport( 'joomla.plugin.plugin' );</source>

To indicate that you're writing a Content plugin, add the following code.
<source lang="PHP">class plgContentNameofplugin extends JPlugin {</source>
Please note the use of capital letters. You should replace Nameofplugin by the name of your own plugin.

Now, it's time to construct the plugin:
<source lang="PHP">/**
* Constructor
*
* For php4 compatability we must not use the __constructor as a constructor for plugins
* because func_get_args ( void ) returns a copy of all passed arguments NOT references.
* This causes problems with cross-referencing necessary for the observer design pattern.
*
* @param object $subject The object to observe
* @param object $params The object that holds the plugin parameters
* @since 1.5
*/
function plgContentNameofplugin( &$subject, $params )
{
parent::__construct( $subject, $params );
}</source>

You should choose now at which moment the plugin should be rendered. You can choose from the following:

* onBeforeContentSave : This is an event that is called right before the content is saved into the database.
* onAfterContentSave : This is an event that is called after the content is saved into the database.
* onPrepareContent : This is the first stage in preparing content for output and is the most common point for content orientated plugins to do their work.
* onAfterDisplayTitle : This is a request for information that should be placed between the content title and the content body.
* onBeforeDisplayContent : This is a request for information that should be placed immediately before the generated content.
* onAfterDisplayContent : This is a request for information that should be placed immediately after the generated content.

More information on which type you should use for your plugin, including several examples, can be found here: [[Plugin events/Content]]

===onBeforeContentSave===
Use the following code:
<source lang="PHP"> function onBeforeContentSave( &$article, $isNew )
{
global $mainframe;
//add your plugin codes here
return true;
}</source>
The parameters article and isNew should contain the following:
* article : A reference to the JTableContent object that is being saved which holds the article data.
* isNew : A boolean which is set to true if the content is about to be created.

===onAfterContentSave===
Use the following code:
<source lang="PHP"> function onAfterContentSave( &$article, $isNew )
{
global $mainframe;
//add your plugin codes here
return true;
}</source>
The parameters article and isNew should contain the following:
* article : A reference to the JTableContent object that was saved which holds the article data.
* isNew : A boolean which is set to true if the content was created.

===onPrepareContent===
Use the following code:
<source lang="PHP"> function onPrepareContent( &$article, &$params, $limitstart )
{
global $mainframe;
//add your plugin codes here
//no return value
}</source>
The parameters article, params and limitstart should contain the following:
* article : A reference to the article that is being rendered by the view.
* params : A reference to an associative array of relevant parameters. The view determines what it considers to be relevant and passes that information along.
* limitstart : An integer that determines the "page" of the content that is to be generated. Note that in the context of views that might not generate HTML output, a page is a reasonably abstract concept that depends on the context.

===onAfterDisplayTitle===
Use the following code:
<source lang="PHP"> function onAfterDisplayTitle( &$article, &$params, $limitstart )
{
global $mainframe;
//add your plugin codes here
return '';
//return a string value. Returned value from this event will be displayed in a placeholder.
// Most templates display this placeholder after the article separator.
}</source>
The parameters article, params and limitstart should contain the following:
* article : A reference to the article that is being rendered by the view.
* params : A reference to an associative array of relevant parameters. The view determines what it considers to be relevant and passes that information along.
* limitstart : An integer that determines the "page" of the content that is to be generated. Note that in the context of views that might not generate HTML output, a page is a reasonably abstract concept that depends on the context.

===onBeforeDisplayContent===
Use the following code:
<source lang="PHP"> function onBeforeDisplayContent( &$article, &$params, $limitstart )
{
global $mainframe;
//add your plugin codes here
return '';
//return a string value. Returned value from this event will be displayed in a placeholder.
// Most templates display this placeholder after the article separator.
}</source>

The parameters article, params and limitstart should contain the following:
* article : A reference to the article that is being rendered by the view.
* params : A reference to an associative array of relevant parameters. The view determines what it considers to be relevant and passes that information along.
* limitstart : An integer that determines the "page" of the content that is to be generated. Note that in the context of views that might not generate HTML output, a page is a reasonably abstract concept that depends on the context.

===onAfterDisplayContent===
Use the following code:
<source lang="PHP"> function onAfterDisplayContent( &$article, &$params, $limitstart )
{
global $mainframe;
//add your plugin codes here
return '';
//return a string value. Returned value from this event will be displayed in a placeholder.
// Most templates display this placeholder after the article separator.
}</source>

The parameters article, params and limitstart should contain the following:
* article : A reference to the article that is being rendered by the view.
* params : A reference to an associative array of relevant parameters. The view determines what it considers to be relevant and passes that information along.
* limitstart : An integer that determines the "page" of the content that is to be generated. Note that in the context of views that might not generate HTML output, a page is a reasonably abstract concept that depends on the context.

==PHP file - Example==
This example PHP file is about the Content Plugin load module. It is a plugin made for displaying modules within the articles.
The commented PHP file used in this example is the file which will be included in Joomla! 1.6. This has been done because the content plugin files in Joomla! 1.5 are not refactored yet to the new standards.
<source lang="PHP">
<?php
// The general information at the top of each file
/**
* @version $Id$
* @package Joomla
* @copyright Copyright (C) 2005 - 2009 Open Source Matters, Inc. All rights reserved.
* @license GNU General Public License, see LICENSE.php
*/

// No direct access allowed to this file
defined( '_JEXEC' ) or die( 'Restricted access' );

// Import Joomla! Plugin library file
jimport('joomla.plugin.plugin');

//The Content plugin Loadmodule
class plgContentLoadmodule extends JPlugin
{
/**
* Plugin that loads module positions within content
*/
// onPrepareContent, meaning the plugin is rendered at the first stage in preparing content for output
public function onPrepareContent( &$row, &$params, $page=0 )
{
// A database connection is created
$db = JFactory::getDBO();
// simple performance check to determine whether bot should process further
if ( JString::strpos( $row->text, 'loadposition' ) === false ) {
return true;
}

// expression to search for
$regex = '/{loadposition\s*.*?}/i';

// check whether plugin has been unpublished
if ( !$this->params->get( 'enabled', 1 ) ) {
$row->text = preg_replace( $regex, '', $row->text );
return true;
}

// find all instances of plugin and put in $matches
preg_match_all( $regex, $row->text, $matches );

// Number of plugins
$count = count( $matches[0] );

// plugin only processes if there are any instances of the plugin in the text
if ( $count ) {
// Get plugin parameters
$style = $this->params->def( 'style', -2 );
$this->_process( $row, $matches, $count, $regex, $style );
}
// No return value
}
// The proccessing function
protected function _process( &$row, &$matches, $count, $regex, $style )
{
for ( $i=0; $i < $count; $i++ )
{
$load = str_replace( 'loadposition', '', $matches[0][$i] );
$load = str_replace( '{', '', $load );
$load = str_replace( '}', '', $load );
$load = trim( $load );

$modules = $this->_load( $load, $style );
$row->text = preg_replace( '{'. $matches[0][$i] .'}', $modules, $row->text );
}

// removes tags without matching module positions
$row->text = preg_replace( $regex, '', $row->text );
}
// The function who takes care for the 'completing' of the plugins' actions : loading the module(s)
protected function _load( $position, $style=-2 )
{
$document = &JFactory::getDocument();
$renderer = $document->loadRenderer('module');
$params = array('style'=>$style);

$contents = '';
foreach (JModuleHelper::getModules($position) as $mod) {
$contents .= $renderer->render($mod, $params);
}
return $contents;
}
}
</source>

==INI file(s)==
For internationalization it is good to use the INI files. You can add to the language file everything which outputs text to the user, in this order:
*XML description tag
*XML label and description attributes from parameters
*JText::_( 'string' ) used by the plugin

You should create two files: One for the backend and one for the front end. The naming should match the path of the extension. For example, if we were creating a content plugin named 'example' and it is installed at plugins/content/example, then our files should be named:
*en-US.plg_content_example.ini (Frontend)
*en-US.plg_content_example.sys.ini (Backend)

Start your INI file with something like this:
<source lang="INI"># $Id: en-GB.plg_content_nameofplugin.ini
# Joomla! Project
# Copyright (C) 2005 - 2007 Open Source Matters. All rights reserved.
# License http://www.gnu.org/licenses/gpl-2.0.html GNU/GPL, see LICENSE.php
# Note : All ini files need to be saved as UTF-8 - No BOM</source>
Of course, you could also add other information, like the author.

Joomla 1.6+ uses the ; at the start of the line, rather than the #.

Backend Example:
<source lang="XML">
<param name="mode" type="list" default="1" label="PLG_CONTENT_EXAMPLE_MODE" description="PLG_CONTENT_EXAMPLE_EMAILS_DISPLAYED">
<option value="0">PLG_CONTENT_EXAMPLE_NONLINKABLE_TEXT</option>
<option value="1">PLG_CONTENT_EXAMPLE_LINKABLE_TEXT</option>
</param></source>

The localized strings are translated in the ini file:
<source lang="INI">
PLG_CONTENT_EXAMPLE_MODE=Mode
PLG_CONTENT_EXAMPLE_EMAILS_DISPLAYED=Select how the e-mails will be displayed
PLG_CONTENT_EXAMPLE_NONLINKABLE_TEXT=Nonlinkable text
PLG_CONTENT_EXAMPLE_LINKABLE_TEXT=As linkable mailto address
</source>

Best practice dictates that LOCALIZED_TAGS are all upper case, no spaces, and begin with the same name as the extension - to avoid interfering with other strings.

The localized tags can then be translated into multiple languages.When you want to make your Content Plugin available in more languages, first add them to the <languages> tag in the XML file. Then create the same INI file, and change the part after the =, for example the dutch version would be:
<source lang="INI">
PLG_CONTENT_EXAMPLE_MODE=Modus
PLG_CONTENT_EXAMPLE_EMAILS_DISPLAYED=Selecteer hoe de e-mails worden weergegeven
PLG_CONTENT_EXAMPLE_NONLINKABLE_TEXT=Niet-linkbare tekst
PLG_CONTENT_EXAMPLE_LINKABLE_TEXT=Als een linkbaar mailto adres
</source>

Frontend Example:
On Joomla 1.6+ you must create a separate file for the front end - as described above. For example:

<source lang="INI">
PLG_CONTENT_EXAMPLE_LINKNAME="The Name of the Link Goes Here!"
</source>

In the plugin's php file, you must load the language file:
<source lang="PHP">
// Load user_profile plugin language
$lang = JFactory::getLanguage();
$lang->load('plg_content_simpleattachment', JPATH_ADMINISTRATOR);
echo JText::_('PLG_CONTENT_EXAMPLE_LINKNAME');
</source>

==Coding examples==
There are seven Joomla! Core Content Plugins. These are all not yet refactored to the new standards. For learning how to write good plugins, its better to look at the (refactored) files of Joomla! 1.6.
You can see them 'working' when you go to the Back-end of your Joomla! 1.5 installation, then go to the menu 'Extensions' and select the 'Plugin Manager'. Click on the name of the Plugin to edit it; and see it working. Also watch the content and see what happens when you insert a pagebreak for example.

==Quick tips==
*In the PHP file you often forget to place an semicolon (;) at the end of a row, which causes errors. Check this before you test your Plugin and you will eliminate many errors.
*Take care of the fact that the parameters in the XML file are closed correctly. When you add options for example, you need to close it with </param>.
*It is easy to test on a localhost when you are still busy with editing your Plugin.
*A typical zip will contain the following:
**nameofplugin.XML
**nameofplugin.PHP
**en-GB.plg_content_nameofplugin.ini

[[Category:Articles that require a review]]
[[Category:Tutorials]]
[[Category:Plugin Development]]

Talk:Administrator goals

2012-04-30T02:47:58Z

Purplebeanie:

I've added a few more points that I had to scratch around for a bit when I first started using Joomla. Some of them may be a bit basic for what we are trying to achieve here but I've also seen some of these come out quite often in the forums. [[User:Purplebeanie|Purplebeanie]] 00:46, 29 April 2012 (CDT)

Is it also adding a section for how to do simple tasks that the admin might normally have used jQuery for in Mootools?? [[User:Purplebeanie|Purplebeanie]] 21:47, 29 April 2012 (CDT)

Administrator goals

2012-04-29T05:49:38Z

Purplebeanie:

Think about your day as a Joomla site administrator and the tasks you had to perform. Think about the goals you were trying to achieve then break those goals down into a set a of short titles that can be added to this page. This is a temporary page that will be transformed into something else at a later stage.

* Add a new page to the website
* Remove a menu item
* Change menu items to different content
* Change the logo
* Change article display settings (show dates/ email icons / authors) based on article, category, and global options
* Add a new module
* Find out what module positions would show where on the page
* Set cache settings, and once set remember to purge cache to see changes
* How Metadata settings affect things like mod_relateditems
* Accessing page statistics (might be a bit basic)
* How to implement Google Analytics / Piwik / xxxxx tracking scripts
* How to backup my site - SQL databases and files and maybe cover backup to something like Amazon S3?
* How to enable remote authoring tools XML/RPC etc. etc.

Talk:Administrator goals

2012-04-29T05:46:36Z

Purplebeanie:

Administrator goals

2012-04-29T05:46:10Z

Purplebeanie:

Talk:Administrator goals

2012-04-29T03:04:19Z

Purplebeanie: Created page with "I've added a few more points that I had to scratch around for a bit when I first started using Joomla. Some of them may be a bit basic for what we are trying to achieve here but..."

Administrator goals

2012-04-29T03:02:56Z

Purplebeanie:

Administrator goals

2012-04-29T02:26:03Z

Purplebeanie:

Administrator goals

2012-04-29T02:22:59Z

Purplebeanie: added a few mote items to the list.