Joomla! Documentation - User contributions [en]

Where are the web pages?

2014-06-19T10:53:01Z

Elin: Take our specific reference to MySql

If you are coming from a traditional website made up of separate HTML pages, you may well wonder where the pages are.

In Joomla! almost everything that you would normally think of as a web page is actually stored in a database. When you create a new page, your content is stored in a database record, not in a separate file.

Then when your site is viewed, Joomla! calls up different items from your database and puts them together to make what is displayed to the user.

One exception is that your images are usually stored in the images directory and not the database.

Your MySQL database usually is created by you during the installation process (unless you use a Fantastico or a similar installer that will create the database automatically). If you have a control panel on a linux host, you can usually access you database through a program called [http://www.phpmyadmin.net/ phpMyAdmin]. This will allow you to view your database.

For a short tutorial on converting a static HTML web site to Joomla!, see [[Converting an existing website to a Joomla! website]].

<noinclude>[[Category:FAQ]]
[[Category:Administration FAQ]]
[[Category:Getting Started FAQ]]
[[Category:Version 1.5 FAQ]]</noinclude>

Plugin/Events/Content

2014-02-05T11:28:54Z

Elin: /* Description */ grammar

{{version/tutor|2.5,3.x|alt=1.5|altlink=J1.5:Plugin/Events/Content|alttitle=this guide for old event names}}
Content events are triggered during the content creation process. The majority of these events are called in many views many components and modules - they are generally not specific for the com_content component. This list gives a brief description of each event, what their parameters are, and some examples of their use in core plugins.

==onContentPrepare==
===Description===
This is the first stage in preparing content for output and is the most common point for content orientated plugins to do their work. Since the article and related parameters are passed by reference, event handlers can modify them prior to display.

===Parameters===
*<code>context</code> The context of the content being passed to the plugin - this is the component name and view - or name of module (e.g. com_content.article). Use this to check whether you are in the desired context for the plugin.
*<code>&article</code> A reference to the article that is being rendered by the view (For example: the text of a com_content article can be found with $article->text).
*<code>&params</code> A reference to an associative array of relevant parameters. The view determines what it considers to be relevant and passes that information along.
*<code>page</code> 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.

===Return Value===
None. Results are returned by modifying the referenced arguments. Sometimes a boolean might be returned to check for success or failure of the event.

===Example===
*<tt>[https://github.com/joomla/joomla-cms/blob/master/plugins/content/emailcloak/emailcloak.php#L31 plugins/content/emailcloak/emailcloak.php]</tt>

==onContentAfterTitle==
===Description===
This event only exists in Joomla {{JVer|3.x}}. This is a request for information that should be placed between the content title and the content body. Although parameters are passed by reference, this is not the event to modify article data. Use onPrepareContent for that purpose. Note this event has special purpose in com_content for use in handling the introtext.

===Parameters===
See the onPrepareContent event for additional discussion of these parameters.
*<code>context</code> The context of the content being passed to the plugin - this is the component name and view - or name of module (e.g. com_content.article). Use this to check whether you are in the desired context for the plugin.
*<code>&article</code> The article that is being rendered by the view.
*<code>&params</code> An associative array of relevant parameters.
*<code>limitstart</code> An integer that determines the "page" of the content that is to be generated.

===Return Value===
String. Returned value from this event will be displayed in a placeholder. Most templates display this placeholder after the article separator.

==onContentBeforeDisplay==
===Description===
This is a request for information that should be placed immediately before the generated content. For views that generate HTML, this might include the use of styles that are specified as part of the content or related parameters. Although parameters are passed by reference, this is not the event to modify article data. Use onPrepareContent for that purpose.

===Parameters===
See the onPrepareContent event for additional discussion of these parameters. Note that unlike onPrepareContent, these parameters are passed by value.
*<code>context</code> The context of the content being passed to the plugin - this is the component name and view - or name of module (e.g. com_content.article). Use this to check whether you are in the desired context for the plugin.
*<code>&article</code> The article that is being rendered by the view.
*<code>&params</code> An associative array of relevant parameters.
*<code>limitstart</code> An integer that determines the "page" of the content that is to be generated.

===Return Value===
String. Returned value from this event will be displayed in a placeholder. Most templates display this placeholder after the article separator.

===Example===
*<tt>[https://github.com/joomla/joomla-cms/blob/master/plugins/content/vote/vote.php#L29 plugins/content/vote/vote.php]</tt>

==onContentAfterDisplay==
===Description===
This is a request for information that should be placed immediately after the generated content. For views that generate HTML, this might include the closure of styles that are specified as part of the content or related parameters. Although parameters are passed by reference, this is not the event to modify article data. Use onPrepareContent for that purpose.

===Parameters===
See the onPrepareContent event for additional discussion of these parameters. Note that unlike onPrepareContent, these parameters are passed by value.
*<code>context</code> The context of the content being passed to the plugin - this is the component name and view - or name of module (e.g. com_content.article). Use this to check whether you are in the desired context for the plugin.
*<code>&article</code> The article that is being rendered by the view.
*<code>&params</code> A JRegistry object of merged article and menu item params.
*<code>limitstart</code> An integer that determines the "page" of the content that is to be generated.

===Return Value===
String. Returned value from this event will be displayed in a placeholder. Most templates display this placeholder after the article separator.

==onContentBeforeSave==
===Description===
This is an event that is called right before the content is saved into the database. You can abort the save by returning false. In the case of <code>JModelLegacy</code> for example the error will then be set by calling <code>$this->setError($table->getError);</code> to be displayed to user.

===Parameters===
*<code>context</code> The context of the content being passed to the plugin - this is the component name and view - or name of module (e.g. com_content.article). Use this to check whether you are in the desired context for the plugin.
*<code>article</code> A reference to the JTableContent object that is being saved which holds the article data.
*<code>isNew</code> A boolean which is set to true if the content is about to be created.

===Return Value===
Boolean. Result will affect the saving process. See description for details.

==onContentAfterSave==
===Description===
This is an event that is called after the content is saved into the database. Even though article object is passed by reference, changes will not be saved since storing data into database phase is past. An example use case would be redirecting user to the appropriate place after saving.

===Parameters===
*<code>context</code> The context of the content being passed to the plugin - this is the component name and view - or name of module (e.g. com_content.article). Use this to check whether you are in the desired context for the plugin.
*<code>article</code> A reference to the JTableContent object that is being saved which holds the article data.
*<code>isNew</code> A boolean which is set to true if the content is about to be created.

===Return Value===
None. Result will be omitted.

==onContentPrepareForm==
===Description===
Called before a JForm is rendered. It can be used to modify the JForm object in memory before rendering. For example, use JForm->loadFile() to add fields or JForm->removeField() to remove fields. Or use JForm->setFieldAttribute() or other JForm methods to modify fields for the form.

===Parameters===
*<code>form</code> The JForm object to be displayed. Use the $form->getName() method to check whether this is the form you want to work with.
*<code>data</code> An object containing the data for the form.

===Return Value===
*<code>boolean</code> True if method succeeds.

===Example===
*[https://www.github.com/joomla/joomla-cms/tree/master/plugins/user/profile/profile.php#L168 plugins/user/profile/profile.php]

==onContentPrepareData==
===Description===
Called after the data for a JForm has been retrieved. It can be used to modify the data for a JForm object in memory before rendering. This is usually used in tandem with the onContentPrepareForm method - this event adds the data to the already altered JForm.

===Parameters===
*<code>context</code> The context of the content being passed to the plugin - this is the component name and view - or name of module (e.g. com_content.article). Use this to check whether you are in the desired context for the plugin.
*<code>data</code> An object containing the data for the form.

===Return Value===
*<code>boolean</code> True if method succeeds.

===Example===
*[https://www.github.com/joomla/joomla-cms/tree/master/plugins/user/profile/profile.php#L51 plugins/user/profile/profile.php]

==onContentBeforeDelete==
===Description===
This is an event that is called right before the content is deleted from the database. You can abort the delete by returning false. In the case of <code>JModelLegacy</code> for example the error will then be set by calling <code>$this->setError($table->getError);</code> to be displayed to user.

===Parameters===
*<code>context</code> The context of the content being passed to the plugin - this is the component name and view - or name of module (e.g. com_content.article). Use this to check whether you are in the desired context for the plugin.
*<code>data</code> A reference to the JTableContent object that is being deleted which holds the article data.

===Return Value===
Boolean. Result will affect the saving process. See description for details.

===Example===
*[https://www.github.com/joomla/joomla-cms/tree/master/plugins/content/joomla/joomla.php#L89 plugins/content/joomla/joomla.php]

==onContentAfterDelete==
===Description===
This is an event that is called after the content is deleted from the database. An example use case would be redirecting user to the appropriate place after deleting.

===Parameters===
*<code>context</code> The context of the content being passed to the plugin - this is the component name and view - or name of module (e.g. com_content.article). Use this to check whether you are in the desired context for the plugin.
*<code>article</code> A reference to the JTableContent object that has been deleted which holds the article data.

===Return Value===
None. Result will be omitted.

===Example===
[https://www.github.com/joomla/joomla-cms/tree/master/plugins/content/finder/finder.php#L61 content/finder/finder.php]

==onContentChangeState==
===Description===
This is an event that is called after content has its state change (e.g. Published to Unpublished).

===Parameters===
*<code>context</code> The context of the content being passed to the plugin - this is the component name and view - or name of module (e.g. com_content.article). Use this to check whether you are in the desired context for the plugin.
*<code>$pks</code> An array of primary key ids of the content that has changed state.
*<code>$value</code> The value of the state that the content has been changed to.

===Return Value===
None. Result will be omitted.

===Example===
[https://www.github.com/joomla/joomla-cms/tree/master/plugins/content/finder/finder.php#L80 content/finder/finder.php]

==onContentSearch==

==onContentSearchAreas==

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

Create sample data

2013-11-04T20:24:17Z

Elin: /* Warnings */

{{version|1.5,2.5,3.1}}
This document will summarize the steps of creating a sample data file.

First, create your new version of the data either by modifying an existing file or by adding to joomla.sql.

Next you need to prepare the data for distribution.

Some important steps for core distributions:
<source lang="sql">
UPDATE `#__content`
SET `created`='2011-01-01 00:00:01',
`created_by`=42,
`created_by_alias`='Joomla',
`modified`=null,
`modified_by`=null,
`checked_out`=null,
`checked_out_time`=null,
`version`=1,
`hits`=0;
UPDATE `#__contact_details`
SET `created`='2011-01-01 00:00:01',
`created_by`=42,
`created_by_alias`='Joomla',
`modified`=null,
`modified_by`=null,
`checked_out`=null,
`checked_out_time`=null,
`version`=1,
`hits`=0;
UPDATE `#__weblinks`
SET `created`='2011-01-01 00:00:01',
`created_by`=42,
`created_by_alias`='Joomla',
`modified`=null,
`modified_by`=null,
`checked_out`=null,
`checked_out_time`=null,
`version`=1,
`hits`=0;
UPDATE `#__newsfeeds`
SET `created`='2011-01-01 00:00:01',
`created_by`=42,
`created_by_alias`='Joomla',
`modified`=null,
`modified_by`=null,
`checked_out`=null,
`checked_out_time`=null,
`version`=1,
`hits`=0;
UPDATE `#__banners`
SET `created`='2011-01-01 00:00:01',
`created_by`=42,
`created_by_alias`='Joomla',
`modified`=null,
`modified_by`=null,
`checked_out`=null,
`checked_out_time`=null,
`version`=1,
`impmade`=0,
`clicks`=0;
UPDATE `#__categories`
SET `created_time`='2011-01-01 00:00:01',
`created_user_id`=42,
`modified_time`=null,
`modified_user_id`=null,
`checked_out`=null,
`checked_out_time`=null,
`version`=1,
`hits`=0;
</source>

Then drop any tables that are not changed by sample data. Here is a typical example, but you must adjust based on your circumstances.

<source lang="sql">
DROP TABLE `#__associations`, `#__banner_tracks`, `#__core_log_searches`, `#__extensions`,
`#__finder_filters`, `#__finder_links`, `#__finder_links_terms0`, `#__finder_links_terms1`,
`#__finder_links_terms2`, `#__finder_links_terms3`, `#__finder_links_terms4`,
`#__finder_links_terms5`, `#__finder_links_terms6`, `#__finder_links_terms7`,
`#__finder_links_terms8`, `#__finder_links_terms9`, `#__finder_links_termsa`,
`#__finder_links_termsb`, `#__finder_links_termsc`, `#__finder_links_termsd`,
`#__finder_links_termse`, `#__finder_links_termsf`, `#__finder_taxonomy`,
`#__finder_taxonomy_map`, `#__finder_terms`, `#__finder_terms_common`, `#__finder_tokens`,
`#__finder_tokens_aggregate`, `#__finder_types`, `#__languages`, `#__messages`,
`#__messages_cfg`, `#__overrider`, `#__redirect_links`, `#__schemas`, `#__session`,
`#__updates`, `#__update_categories`, `#__update_sites`, `#__update_sites_extensions`,
`#__users`, `#__user_notes`, `#__user_profiles`, `#__user_usergroup_map`;
</source>

At this point you should dump out your file. It's good to do this with
* No comments
* Foreign keys disabled
* INSERT IGNORE
* CREATE TABLE IF NOT EXISTS
* Back ticks around names

At the top of your file you will want to add truncation for the tables you are modifying. It is safer to replace the whole table than to try to do it piecemeal.

<source lang="sql">
TRUNCATE `#__assets`;
TRUNCATE `#__categories`;
TRUNCATE `#__menu`;
TRUNCATE `#__menu_types`;
TRUNCATE `#__modules`;
TRUNCATE `#__modules_menu`;
TRUNCATE `#__usergroups`;
</source>

At this point ... you will want to change your table prefixes from "jos_" to "#__" (substituting your prefix).

==Testing==
Before testing with the Joomla installation, simply try importing the joomla.sql file and then your file into a blank data base. This will quickly highlight any obvious problems in table structure and similar items.

If you call your file sample_something.sql and put it in the appropriate folder it will automatically appear in the list of installable files when the Joomla installer runs. Test you file there.

==Warnings==
In Joomla 2.5 and later the data structures are complex and interdependent. Make sure in particular that you include necessary changes in the assets table and the categories table if you create content items. Also in 3.2 and later pay attention to the assets for modules.

Make sure that you use a UTF-8 safe editor if you edit your sample data file directly.

Make sure not to include your session data, redirect data (unless it is deliberate), user data and similar items.

Most likely you do not want to include indexed data from Smart Search.

Creating a profile plugin

2013-10-31T14:29:47Z

Elin:

{{version/tutor|2.5,3.x}}
Profile plugin is a new extension in Joomla! 2.5. It allows the addition of supplemental fields in the registration and profile forms of the com_user front end and in the user create/edit form in the back end.

A simple example plugin with the name '''User - Profile''' is included in the basic Joomla! installation as a proof of concept. Much more complex plugins are possible.

The example plugin takes advantage of on the onContentPrepareForm and onUserAfterSave events.

Multiple profile plugins may be included and will be rendered in sequence.

There are four separate places where profiles forms are used in core extensions, and each of these four can be manipulated separately if that is desired. The two locations in the front end are the user registration form and the user profile edit form. In the back end the locations are the edit screen for users in the user manager and the My Profile view found in the Admin menu.

This page shows an example of a second plugin, named profile5. It adds a single field called something.

This is the file structure

profile5.php
profile5.xml
en-GB.plg_user_profile5.ini
en-GB.plg_user_profile5.sys.ini
/profiles/profile.xml

The supplemental fields are created within the profile.xml file in the profiles folder. Note that this file name is "profile.xml" NOT "profile5.xml", but inside the file the fields and fieldset names ARE "profile5". Note also that the first character in the must be the "<" from the xml tag. Just drop the profile5.xml in a browser tab and if shows you the structure the file is formatted correctly.

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>

<form>
<fields name="profile5">
<fieldset name="profile5"
label="PLG_USER_PROFILE5_SLIDER_LABEL"
>
<field
name="something"
type="text"
id="something"
description="PLG_USER_PROFILE5_FIELD_SOMETHING_DESC"
filter="string"
label="PLG_USER_PROFILE5_FIELD_SOMETHING_LABEL"
message="PLG_USER_PROFILE5_FIELD_SOMETHING_MESSAGE"
size="30"
/>

</fieldset>
</fields>
</form>
</source>

profile5.php

<source lang="PHP">
<?php
/**
* @version
* @copyright Copyright (C) 2005 - 2010 Open Source Matters, Inc. All rights reserved.
* @license GNU General Public License version 2 or later; see LICENSE.txt
*/

defined('JPATH_BASE') or die;

/**
* An example custom profile plugin.
*
* @package Joomla.Plugins
* @subpackage user.profile
* @version 1.6
*/
class plgUserProfile5 extends JPlugin
{
/**
* @param string The context for the data
* @param int The user id
* @param object
* @return boolean
* @since 1.6
*/
function onContentPrepareData($context, $data)
{
// Check we are manipulating a valid form.
if (!in_array($context, array('com_users.profile','com_users.registration','com_users.user','com_admin.profile'))){
return true;
}

$userId = isset($data->id) ? $data->id : 0;

// Load the profile data from the database.
$db = JFactory::getDbo();
$db->setQuery(
'SELECT profile_key, profile_value FROM #__user_profiles' .
' WHERE user_id = '.(int) $userId .
' AND profile_key LIKE \'profile5.%\'' .
' ORDER BY ordering'
);
$results = $db->loadRowList();

// Check for a database error.
if ($db->getErrorNum()) {
$this->_subject->setError($db->getErrorMsg());
return false;
}

// Merge the profile data.
$data->profile5 = array();
foreach ($results as $v) {
$k = str_replace('profile5.', '', $v[0]);
$data->profile5[$k] = json_decode($v[1], true);
}

return true;
}

/**
* @param JForm The form to be altered.
* @param array The associated data for the form.
* @return boolean
* @since 1.6
*/
function onContentPrepareForm($form, $data)
{
// Load user_profile plugin language
$lang = JFactory::getLanguage();
$lang->load('plg_user_profile5', JPATH_ADMINISTRATOR);

if (!($form instanceof JForm)) {
$this->_subject->setError('JERROR_NOT_A_FORM');
return false;
}
// Check we are manipulating a valid form.
if (!in_array($form->getName(), array('com_users.profile', 'com_users.registration','com_users.user','com_admin.profile'))) {
return true;
}
if ($form->getName()=='com_users.profile')
{
// Add the profile fields to the form.
JForm::addFormPath(dirname(__FILE__).'/profiles');
$form->loadFile('profile', false);

// Toggle whether the something field is required.
if ($this->params->get('profile-require_something', 1) > 0) {
$form->setFieldAttribute('something', 'required', $this->params->get('profile-require_something') == 2, 'profile5');
} else {
$form->removeField('something', 'profile5');
}
}

//In this example, we treat the frontend registration and the back end user create or edit as the same.
elseif ($form->getName()=='com_users.registration' || $form->getName()=='com_users.user' )
{
// Add the registration fields to the form.
JForm::addFormPath(dirname(__FILE__).'/profiles');
$form->loadFile('profile', false);

// Toggle whether the something field is required.
if ($this->params->get('register-require_something', 1) > 0) {
$form->setFieldAttribute('something', 'required', $this->params->get('register-require_something') == 2, 'profile5');
} else {
$form->removeField('something', 'profile5');
}
}
}

function onUserAfterSave($data, $isNew, $result, $error)
{
$userId = JArrayHelper::getValue($data, 'id', 0, 'int');

if ($userId && $result && isset($data['profile5']) && (count($data['profile5'])))
{
try
{
$db = JFactory::getDbo();
$db->setQuery('DELETE FROM #__user_profiles WHERE user_id = '.$userId.' AND profile_key LIKE \'profile5.%\'');
if (!$db->query()) {
throw new Exception($db->getErrorMsg());
}

$tuples = array();
$order = 1;
foreach ($data['profile5'] as $k => $v) {
$tuples[] = '('.$userId.', '.$db->quote('profile5.'.$k).', '.$db->quote(json_encode($v)).', '.$order++.')';
}

$db->setQuery('INSERT INTO #__user_profiles VALUES '.implode(', ', $tuples));
if (!$db->query()) {
throw new Exception($db->getErrorMsg());
}
}
catch (JException $e) {
$this->_subject->setError($e->getMessage());
return false;
}
}

return true;
}

/**
* Remove all user profile information for the given user ID
*
* Method is called after user data is deleted from the database
*
* @param array $user Holds the user data
* @param boolean $success True if user was succesfully stored in the database
* @param string $msg Message
*/
function onUserAfterDelete($user, $success, $msg)
{
if (!$success) {
return false;
}

$userId = JArrayHelper::getValue($user, 'id', 0, 'int');

if ($userId)
{
try
{
$db = JFactory::getDbo();
$db->setQuery(
'DELETE FROM #__user_profiles WHERE user_id = '.$userId .
" AND profile_key LIKE 'profile5.%'"
);

if (!$db->query()) {
throw new Exception($db->getErrorMsg());
}
}
catch (JException $e)
{
$this->_subject->setError($e->getMessage());
return false;
}
}

return true;
}

}

</source>

profile5.xml controls whether the field is required, disabled or optional in the forms. Since profile5.php says to treat backend create/edit the same as registration only two sets of options are required, register and profile. Note: First character of the file must be "<". Just drop the profile5.xml in a browser tab and if shows you the structure the file is formatted correctly.

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>

<extension version="3.1" type="plugin" group="user">
<name>plg_user_profile5</name>
<author>Joomla! Project</author>
<creationDate>January 2008</creationDate>
<copyright>(C) 2005 - 2013 Open Source Matters. All rights reserved.</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<authorEmail>admin@joomla.org</authorEmail>
<authorUrl>www.joomla.org</authorUrl>
<version>3.0.0</version>
<description>PLG_USER_PROFILE5_XML_DESCRIPTION</description>

<files>
<filename plugin="profile5">profile5.php</filename>
<filename>index.html</filename>
<folder>profiles</folder>
</files>

<languages>
<language tag="en-GB">en-GB.plg_user_profile5.ini</language>
<language tag="en-GB">en-GB.plg_user_profile5.sys.ini</language>
</languages>

<config>
<fields name="params">

<fieldset name="basic">
<field name="register-require-user" type="spacer"
label="PLG_USER_PROFILE5_FIELD_NAME_REGISTER_REQUIRE_USER"
/>

<field name="register-something" type="list"
description="PLG_USER_PROFILE5_FIELD_SOMETHING_DESC"
label="PLG_USER_PROFILE5_FIELD_SOMETHING_LABEL"
>
<option value="2">JOPTION_REQUIRED</option>
<option value="1">JOPTION_OPTIONAL</option>
<option value="0">JDISABLED</option>
</field>

<field name="profile-require-user" type="spacer"
label="PLG_USER_PROFILE5_FIELD_NAME_PROFILE_REQUIRE_USER"
/>

<field name="profile-require_something" type="list"
description="PLG_USER_PROFILE5_FIELD_SOMETHING_DESC"
label="PLG_USER_PROFILE5_FIELD_SOMETHING_LABEL"
>
<option value="2">JOPTION_REQUIRED</option>
<option value="1">JOPTION_OPTIONAL</option>
<option value="0">JDISABLED</option>
</field>

</fieldset>

</fields>
</config>
</extension>
</source>

en-GB.plg_user_profile5.ini

;
; Joomla! Project
; Copyright (C) 2005 - 2010 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

PLG_USER_PROFILE5_XML_DESCRIPTION="User Profile 5 Plug-in"
PLG_USER_PROFILE5="User - Profile 5"
PLG_USER_PROFILE5_SLIDER_LABEL="User Profile 5"
PLG_USER_PROFILE5_FIELD_NAME_REGISTER_REQUIRE_USER="User profile fields for registration and administrator user profile 5 forms"
PLG_USER_PROFILE5_FIELD_NAME_PROFILE_REQUIRE_USER="User profile fields for profile 5 edit form"
PLG_USER_PROFILE5_FIELD_SOMETHING_DESC="Choose an option for the something filed"
PLG_USER_PROFILE5_FIELD_SOMETHING_LABEL="Something!"
PLG_USER_PROFILE5_FIELD_SOMETHING_MESSAGE="A Message for something!"
PLG_USER_PROFILE5_XML_DESCRIPTION="User Profile 5 Plug-in"

en-GB.plg_user_profile5.sys.ini

; $Id: en-GB.plg_user_profile.sys.ini 17052 2010-05-14 14:05:58Z infograf768 $
; Joomla! Project
; Copyright (C) 2005 - 2010 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

PLG_USER_PROFILE5="User - Profile 5 "
PLG_USER_PROFILE5_XML_DESCRIPTION="User Profile 5 Plug-in"

By installing profile5 you can add new fields in addition to the ones in profile. You can also control which view levels see those fields.
Alternatively, you can write a more complex common plugin with varying controls for different groups.

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

Using com config for frontend template style editing

2013-10-13T09:19:31Z

Elin: Created page with "Here is the page"

Here is the page

Security hotfixes for Joomla EOL versions

2013-09-03T22:17:16Z

Elin:

{{Warning|'''Do not rely on all security issues being patched or reported for EOL(end of life) versions.'''}}

This page is for Joomla! versions which have reached EOL('''end of life''') and are no longer being developed or supported by the Joomla! project. Issues and items are only listed on this page as a benefit to the users of EOL versions who have not migrated to a supported version yet.

It is '''strongly recommended you update your websites''' to a supported Joomla! version ASAP.

== Joomla! 1.5 ==
Although Joomla 1.5 has reached EOL(end of life), if there is a critical security issue with a fix it may be reported here.

===File Upload Security Patch===
There is a security issue in all versions of Joomla related to unauthorized file uploads.
* Read the [http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemEdit&tracker_item_id=31626 Issue Tracker Item] for details.
* Download the [http://joomlacode.org/gf/download/trackeritem/31626/83528/UploadFix15v3.zip File Upload Security Patch] and manually apply per instructions.
:'''File Upload Security Patch Update Instructions:'''
:#Download & Unpack the security patch
:#Upload patch files via ftp directly to the root of your Joomla! installation, overwriting existing files.

===Flash Uploader==
The flash uploader has been removed from Joomla! 2.5 and Joomla! 3 for security reasons. 1.5 users should do the same and can do so first by removing the file and then by setting the option for it to off.

==See also==
===Joomla! 1.5===
* The unofficial, [https://github.com/PhilETaylor/Joomla1.5.999 Joomla! 1.5.999 GitHub] project.

[[Category:Security]]
[[Category:Joomla! 1.5]]

J2.5:Updating from an existing version

2013-08-08T18:49:45Z

Elin: /* Update the #__extensions Table */

{{RightTOC}}
=Overview=
The recommended way to update installations of Joomla! is to use the Joomla Updater component '''(Method A)''' found in the Components menu of your site Administrator.

Always back up your site before updating.

==Browse to Components, Joomla Update==

*If an update is available there will be a message indicating this and a button to press.
[[File:Updatewaiting.PNG|670px]]

==Click on the "Install the Update" button and allow the update to run.==

[[File:Updatecompleted25.PNG]]

==When updating has completed you may need to refresh your screen or empty your browser cache to adjust for template CSS changes.==

Note: Joomla! will notify on your administrator home page (control panel) when an update is needed, but it will not do the update for you. You need to press the button to start the update.

==Trouble Shooting and Advanced Techniques==
Starting with version 1.6, there are three ways to update your Joomla Website to versions 1.6, 1.7 or 2.5.
If you are in an older version that did not support one click updates or are on a server that does not allow such updates you should use one of these options.

* Extension Manager: Update
* Extension Manager: Install
* Manually Copy Program Files

Each of these is discussed below.

==Upgrade from version earlier than 1.6.x to Joomla 1.7? ==
This page does not contain the instructions for migrating a Website from Joomla versions earlier than 1.6. See the [[J2.5:Migrating from Joomla 1.5 to Joomla 2.5|Migrating from Joomla 1.5 to Joomla 2.5]] page.

==Upgrade from version 1.6.x to Joomla 1.7? ==
Note: To upgrade from version 1.6.x to Joomla 1.7 please follow the [[Upgrade 1.6.5 to 1.7|Upgrade 1.6.5 to 1.7 guide]] before you upgrade to Joomla 2.5.

==Upgrade to Joomla 2.5 on shared hosts==
{{notice|<small>'''Important note as of 28 January 2012:''' ''On some shared host environments (GoDaddy.com and perhaps others), the normal Joomla update from 1.7 to 2.5 can intermittently fail with the error "Internal Server Error". In some cases, this can happen in the middle of the file transfer process and cause errors on the site. On GoDaddy.com, this appears to happen when the server is under a heavy load and the update takes longer than 2 minutes to complete.''
''Based on recent testing, sites on these slower shared hosts can safely be updated using a free third-party extension called [http://tinyurl.com/7d9odse Admin Tools]. If you are updating a site on a shared host, please consider using Admin Tools or else use the Manually Copy Program Files method outlined below.''
''If you have experienced an error during the update, there is a process for repairing the site.''</small>}}

'''Steps and actions:'''
It is recommended that you follow these steps when updating a production site:
# Back up your site before upgrading to a new version. That way, if something goes wrong during the upgrade process, you can easily restore your site to the earlier version.
# Review the release notes for the new version to be familiar with what was changed.
# Update using one of the recommended methods outlined in this document. These methods install the new program files, delete unneeded old program files, and update the database as needed for the new Joomla version.
# Clear your browser cache and check that the update was successful, using the steps outlined in the '''Checking Site''' tab.

=Method A - Update Method (Recommended)=
This is the easier way, also called ''One click update''

==Step 1: Make sure you have a current backup of your site==
In many cases, your host will make periodic site backups.

==Step 2a: Find and install updates==
# '''If your site is prior to 2.5.4, see Step 2b instead'''
# In the back end of your Joomla site, navigate to Components → Joomla Update.
# Click on Install the Update [[Image:Update-screenshot-20120618-01.png|frame|center]]
# '''IMPORTANT:''' This process will take a few minutes. Wait until the process completes and it tells you that you are already on the current release, similar to the screen shown below. [[Image:Update-screenshot-20120618-02.png|frame|center]]
# Congratulations! At this point, your site is updated.
'''Important:''' Clear your browser cache and check that your site is working correctly. See below Checking Your Site

==Step 2b: Find and install updates (Prior to updating 2.5.4)==
# In the back end of your Joomla site, navigate to Extensions → Extension Manager and open the Update tab.
# Click on the Purge Cache icon to clear out the cache.
# Click on the Find Updates icon in the toolbar. If there is an available update, the screen will list it, similar to the screen shown below. [[Image:Update-screenshot-20120124-01.png|frame|center]] Note that available upgrades for extensions used in the site will also show in the list.
# Select the update (using the checkbox) and click on the Update icon in the toolbar.
# '''IMPORTANT:''' This process will take a few minutes. Wait until the process completes and the success message shows, similar to the screen shown below. [[Image:Update-screenshot-20120124-02.png|frame|center]]
# Congratulations! At this point, your site is updated.
'''Important:''' Clear your browser cache and check that your site is working correctly. See below Checking Your Site

=Method B - Install Method=
In some cases it may not be possible to use the Extension Manager: Update method to update your site. One reason for this might be that you are using a non-standard distribution (for example, a distribution with a different default language installed). Another reason might be that your don't have a reliable enough internet connection to support automatic installation.

In this case, you can still do an easy installation using the Extension Manager: Install screen. Like the Update screen, this method will do the database updates automatically and will completely update your system without any further steps.

==Step 1: Make sure you have a current backup of your site==
In many cases, your host will make periodic site backups.

==Step 2: Locate the update file==
Locate the required archive file (for example, .zip, .tag.gz, or tar.bz2 archive) for your version. If you are updating to an x.x.0 release (for example, from 1.7.3 to 2.5.0), this will normally be a file like Joomla_2.5.0-Stable-Update_Package.zip. If you are updating within the same release series (for example, 2.5.0 to 2.5.1), then the file will be named something like Joomla_2.5.0_to_2.5.1-Stable-Patch_Package.zip.

At this point, you have three options:
# Install from URL
# Install from Directory
# Upload Package File

Install from URL is the easiest to do. With this option, the upgrade archive is loaded directly by the server, so it works well even if your local computer has a slow or unreliable internet connection.

Install from Directory is the safest method if the server itself has a slow internet connection. With this method, you use FTP to load the unpacked update files into a temporary folder on the server. Then you point to that directory on the server for the installation.

Upload Package File is fairly simple, but it requires that you have a good connection between your local computer and the server.

The screen below shows the Extension Manager: Install screen with the three options labeled.
[[Image:Update-screenshot-20120124-03.png|frame|center]]

===Install from URL===
This option is the easiest, if the archive file is available on a website.
# In the Extension Manager: Install screen, enter the URL for the archive file in the Install URL field.
# Press the Install button.
The system will work for a period of time, up to two minutes or more for a full version update. Then a message indicating a successful installation will display.

===Install from Directory===
This option requires that you unpack the archive file in a directory on your server. This is the best method if you have a slow internet connection or you are experiencing timeouts during the update process.
# Unpack the archive file in a temporary directory on your local machine.
# Upload all the files in this directory (for example, using FTP) to a temporary directory that is visible to the web server. For example, you can create a sub-directory under the tmp directory in your Joomla root. For this example, let's say the directory on the server is <code>/home/myuser/myjoomla/tmp/upgrade250</code>).
# In the Extension Manager: Install screen, enter the full path of the temporary directory (on the server) from step 2 (for example, <code>/home/myuser/myjoomla/tmp/upgrade250</code>).
# Press the Install button.
The system will work for a short time (perhaps a minute or less, depending on your server). Then a message indicating a successful installation will display.

===Upload Package File===
This option requires that you first download the archive file to your local machine.
# Download the file to your local computer.
# In the Extension Manager: Install screen, click the Browse button next to the Package File field and browse to the archive file.
# Press the Install button.
The system will work for a period of time, up to two minutes or more for a full version update. Then a message indicating a successful installation will display.

# Congratulations! At this point, your site is updated.
'''Important:''' Clear your browser cache and check that your site is working correctly. See below Checking Your Site

=Method C - Manual Upgrade=
This method is similar to the old method for updating Joomla versions. Here we want to replace the existing program files with the files from the update archive. The advantage of this method is that it will work on slower shared hosts. The disadvantage is that it requires more work by the system administrator.

''Important: This method can also be used to repair a site where the automatic update failed due to a server timeout.''

==Copy the New Program Files to Your Site==
There are two ways you can do this.
# Copy the archive file to the root directory of your site and unpack the archive. The update archive will be named something like <code>Joomla_2.5.0-Stable-Update_Package.zip</code>. Note that you need to tell the system to replace any existing files. For example, in GoDaddy.com, use the FTP File Manager to upload the update file and then use "Unarchive" to unpack it. Check the box "Overwrite existing files".
# If you don't have the ability to unpack the archive on the server, create a temporary directory on your local machine and unpack the archive file there. Then FTP these files to the root directory of your site, overwriting the existing files.

==Update the Database==
At this point, you should be able to log into the back end of your site with the new version installed. However, you are not done. Navigate to Extension Manager: Database. You will initially have Database problems when you check the Database, similar to the screen below.
[[Image:Update-screenshot-20120124-08.png|frame|center|Database Screen Before Fix]]
This is expected. Click on the Fix icon to correct the problems. Now the screen should show that the database is up to date.

==Install New Extensions==
Navigate to Extension Manager: Discover and click on the Discover icon in the toolbar. If the updated version has new core extensions, new extensions will be listed, as shown below.
[[Image:Update-screenshot-20120124-09.png|frame|center|Discover Screen Before Install]]
Select all the extensions and click on the Install icon in the toolbar. The system should display a success message similar to the screen below.
[[Image:Update-screenshot-20120124-10.png|frame|center|Discover Screen After Install]]

==Delete removed files ==
Look at the list of removed files in administrator/components/com_admin/script.php.
Delete each of the files.

==Update the #__extensions Table==
At this point, your site is updated. However, there is one more thing to do. The site will think it needs to be updated because a value in the #__extensions table is wrong. To fix this:
* Using phpMyAdmin or a similar tool, edit the row of the #__extensions table where the id column is '700'. (Note that the table prefix will be different in your site. For example, if your table prefix is "jos_", then the table will be called "jos_extensions".
* In the manifest_cache column, you will see the old version in the text (for example, <code>"version":"1.7.3"</code>). Change this to the new version (for example, <code>"version":"2.5.0"</code>). Be careful to not change anything else in this column.
* To check that this was successful, navigate to Extension Manager: Update and click Check for Updates. You should '''not''' see the current Joomla version in the list.

At this point, your site should be updated correctly.

=Checking Site=
'''This is required for method A and B!'''
After an update, it is a good idea to clear your browser cache snd check your site to make sure the update was successful. There are two quick checks you can do from the Extension Manager.
==Extension Manager: Check Database==
{{JVer|2.5}} This feature was added in version 2.5.0. It checks that your database is up to date with your Joomla programs.

Navigate to Extension Manager: Database. If your database is up to date, you should see a screen similar to the one below:
[[Image:Update-screenshot-20120124-04.png|frame|center|Database Screen With No Problems]]

If your database is not up to date, you will see a screen listing the problems found, similar to the one below:
[[Image:Update-screenshot-20120124-05.png|frame|center|Database Screen With 3 Database Problems]]
In this case, press the Fix button in the upper right corner. Joomla will update your database to correct the issues listed and then it will re-display the screen. If the fix was successful, the display will indicate that the database is up to date.

'''N.B.''' If any errors fail to fix then make sure all the database Tables are checked in.

==Extension Manager: Discover==
In some cases, when you update to a new Joomla version, new core extensions are added. If there were problems with the database update, these extensions may not have been correctly installed. To check this, navigate to Extension Manager: Discover. Then click on the Discover icon in the toolbar. The screen should show as follows:
[[Image:Update-screenshot-20120124-06.png|frame|center|Discover Screen With No Extensions To Install]]
If so, you know that any new extensions added during the udpate were correctly installed in the database.

If there are uninstalled extensions, they will show similar to the following screen:
[[Image:Update-screenshot-20120124-07.png|frame|center|Discover Screen With Two Extensions To Install]]
In this case, check the check boxes and click on the Install icon in the toolbar. Joomla will install the extension(s) and then display the screen showing no extensions discovered. At this point, the new extensions have been installed in the database.

=Troubleshooting=
If you have any questions before, during, or after the upgrade then please ask them on the [http://forum.joomla.org/viewforum.php?f=625&sid=259a29d8e21242b6770f86026f6c9c3a Joomla! 1.6 Migrating and Upgrading Forum].

If you have problems or errors during the update process, here are some tips.
* Clear your browser cache as there may have been changes to the css or javascript that will need to be reloaded by your web browser.
* If any database error messages show after the update, be sure to check the Extension Manager: Database tab followed by the Extension Manager: Discover tab. In some cases, if a database error occurs it will prevent all the database updates from running. In this case, you can run them from the Database tab and then use the Discover→Install method to check and install any new extensions.
* If you encounter any errors or problems during or after the update, be sure to check the FAQ for the version you updated to. For example, for version 2.5.0, this will be an article entitled [http://docs.joomla.org/Category:Version_2.5.0_FAQ http://docs.joomla.org/Category:Version_2.5.0_FAQ].

<headertabs/>
[[Category:Upgrading]]
[[Category:Joomla! 2.5]]

Archived:Upgrade Instructions

2013-08-08T18:39:25Z

Elin:

{{JVer/multi|3}}: [[J3.1:Upgrading_from_an_existing_version|Upgrading Joomla 3]]

{{JVer/multi|1.6,1.7, 2.5}}: [[J2.5:Upgrading_from_an_existing_version|Upgrading in 1.6 to 2.5]]

{{JVer/multi|1.0,1.5}}:

Upgrading a live website is not something to be undertaken lightly so please read the Upgrade Instructions carefully. The instructions may appear complicated because there are many different configurations that need to be considered, but we have tried to write them so that you need only select a single path from the many available depending on your particular circumstances.

The overall procedure is:
# Download the correct patch package.
# Make a copy of your live site.
# Install the patch package on the copy site.
# Make any database changes required on your copy site.
# Test it thoroughly.
# Backup your live site.
# Install the patch package on your live site.
# Make any database changes required on your live site.
# Make any other changes required
# Check your live site to make sure it is working correctly.

Please read the full upgrade instructions, listed below, carefully. If you have any questions before, during, or after the upgrade then please ask them on the appropriate upgrade forum.

==Joomla! 1.0.x Series==
If you have any questions before, during, or after the upgrade then please ask them on the [http://forum.joomla.org/index.php/board,36.0.html Joomla! 1.0 Upgrading 1.0.x Forum].
{{Ambox|type=notice|image=notice|style=width:500px|text=[http://dev.joomla.org/content/blogcategory/21/86/ Current status], [http://www.joomla.org/content/blogcategory/32/66/ Version info], [http://www.joomla.org/content/category/5/34/78/ Changelogs], [http://www.joomla.org/content/category/5/39/95/ MD5 Checksums]}}
====Latest release====
* '''[[Upgrading to 1.0.15]]'''
====Earlier releases====
* '''[[Upgrading to 1.0.14]]'''
* '''[[Upgrading to 1.0.14 RC1]]'''

==Joomla! 1.5.x Series==
If you have any questions before, during, or after the upgrade then please ask them on the [http://forum.joomla.org/index.php/board,430.0.html Joomla! 1.5 Migrating and Upgrading Forum].
{{Ambox|type=notice|image=notice|style=width:500px|text=[http://dev.joomla.org/content/blogcategory/27/103/ Current status], [http://www.joomla.org/content/blogcategory/57/111/ Version info], [http://www.joomla.org/content/category/5/59/116/ Changelogs], [http://www.joomla.org/content/category/5/60/117/ MD5 Checksums]}}

====Latest release====
* '''[[Upgrading 1.5 from an existing 1.5x version]]'''

====Earlier releases====
* '''[[Upgrading to 1.5 Stable]]''' (from a 1.5 Release Candidate)
====Migration from 1.0.x series====
* '''[[Migrating from 1.0.x to 1.5 Stable]]'''

[[Category:Landing Pages]][[Category:Upgrading]]

Archived:Upgrade Instructions

2013-08-08T18:38:03Z

Elin:

[[J3.1:Upgrading_from_an_existing_version|Upgrading Joomla 3]]

[[J2.5:Upgrading_from_an_existing_version|Upgrading in 1.6 to 2.5]]
{{JVer/multi|1.0,1.5}}:

Upgrading a live website is not something to be undertaken lightly so please read the Upgrade Instructions carefully. The instructions may appear complicated because there are many different configurations that need to be considered, but we have tried to write them so that you need only select a single path from the many available depending on your particular circumstances.

The overall procedure is:
# Download the correct patch package.
# Make a copy of your live site.
# Install the patch package on the copy site.
# Make any database changes required on your copy site.
# Test it thoroughly.
# Backup your live site.
# Install the patch package on your live site.
# Make any database changes required on your live site.
# Make any other changes required
# Check your live site to make sure it is working correctly.

Please read the full upgrade instructions, listed below, carefully. If you have any questions before, during, or after the upgrade then please ask them on the appropriate upgrade forum.

==Joomla! 1.0.x Series==
If you have any questions before, during, or after the upgrade then please ask them on the [http://forum.joomla.org/index.php/board,36.0.html Joomla! 1.0 Upgrading 1.0.x Forum].
{{Ambox|type=notice|image=notice|style=width:500px|text=[http://dev.joomla.org/content/blogcategory/21/86/ Current status], [http://www.joomla.org/content/blogcategory/32/66/ Version info], [http://www.joomla.org/content/category/5/34/78/ Changelogs], [http://www.joomla.org/content/category/5/39/95/ MD5 Checksums]}}
====Latest release====
* '''[[Upgrading to 1.0.15]]'''
====Earlier releases====
* '''[[Upgrading to 1.0.14]]'''
* '''[[Upgrading to 1.0.14 RC1]]'''

==Joomla! 1.5.x Series==
If you have any questions before, during, or after the upgrade then please ask them on the [http://forum.joomla.org/index.php/board,430.0.html Joomla! 1.5 Migrating and Upgrading Forum].
{{Ambox|type=notice|image=notice|style=width:500px|text=[http://dev.joomla.org/content/blogcategory/27/103/ Current status], [http://www.joomla.org/content/blogcategory/57/111/ Version info], [http://www.joomla.org/content/category/5/59/116/ Changelogs], [http://www.joomla.org/content/category/5/60/117/ MD5 Checksums]}}

====Latest release====
* '''[[Upgrading 1.5 from an existing 1.5x version]]'''

====Earlier releases====
* '''[[Upgrading to 1.5 Stable]]''' (from a 1.5 Release Candidate)
====Migration from 1.0.x series====
* '''[[Migrating from 1.0.x to 1.5 Stable]]'''

[[Category:Landing Pages]][[Category:Upgrading]]

Archived:Upgrade Instructions

2013-08-08T18:33:15Z

Elin:

{{JVer/multi|1.0,1.5}}:

Upgrading a live website is not something to be undertaken lightly so please read the Upgrade Instructions carefully. The instructions may appear complicated because there are many different configurations that need to be considered, but we have tried to write them so that you need only select a single path from the many available depending on your particular circumstances.

The overall procedure is:
# Download the correct patch package.
# Make a copy of your live site.
# Install the patch package on the copy site.
# Make any database changes required on your copy site.
# Test it thoroughly.
# Backup your live site.
# Install the patch package on your live site.
# Make any database changes required on your live site.
# Make any other changes required
# Check your live site to make sure it is working correctly.

Please read the full upgrade instructions, listed below, carefully. If you have any questions before, during, or after the upgrade then please ask them on the appropriate upgrade forum.

==Joomla! 1.0.x Series==
If you have any questions before, during, or after the upgrade then please ask them on the [http://forum.joomla.org/index.php/board,36.0.html Joomla! 1.0 Upgrading 1.0.x Forum].
{{Ambox|type=notice|image=notice|style=width:500px|text=[http://dev.joomla.org/content/blogcategory/21/86/ Current status], [http://www.joomla.org/content/blogcategory/32/66/ Version info], [http://www.joomla.org/content/category/5/34/78/ Changelogs], [http://www.joomla.org/content/category/5/39/95/ MD5 Checksums]}}
====Latest release====
* '''[[Upgrading to 1.0.15]]'''
====Earlier releases====
* '''[[Upgrading to 1.0.14]]'''
* '''[[Upgrading to 1.0.14 RC1]]'''

==Joomla! 1.5.x Series==
If you have any questions before, during, or after the upgrade then please ask them on the [http://forum.joomla.org/index.php/board,430.0.html Joomla! 1.5 Migrating and Upgrading Forum].
{{Ambox|type=notice|image=notice|style=width:500px|text=[http://dev.joomla.org/content/blogcategory/27/103/ Current status], [http://www.joomla.org/content/blogcategory/57/111/ Version info], [http://www.joomla.org/content/category/5/59/116/ Changelogs], [http://www.joomla.org/content/category/5/60/117/ MD5 Checksums]}}

====Latest release====
* '''[[Upgrading 1.5 from an existing 1.5x version]]'''

====Earlier releases====
* '''[[Upgrading to 1.5 Stable]]''' (from a 1.5 Release Candidate)
====Migration from 1.0.x series====
* '''[[Migrating from 1.0.x to 1.5 Stable]]'''

[[Category:Landing Pages]][[Category:Upgrading]]

J3.x:CLI Applications Broken

2013-08-04T15:54:44Z

Elin:

Because of changes made to JTable, CLI and other stand alone applications that use JTable break in Joomla 3.1.3 and later.
This is because you now must also load the legacy and cms libraries in order to work with JTable.

Adding this code to your application should fix the issue.

<source lang="php">
jimport('joomla.observer.mapper');
jimport('cms.helper.tags');
jimport('cms.table.corecontent');
// Categories is in legacy for CMS 3 so we have to check there.
JLoader::registerPrefix('J', JPATH_PLATFORM . '/legacy');
JLoader::Register('J', JPATH_PLATFORM . '/cms');

</source>
You may also need to load some other classes [http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemEdit&tracker_item_id=31663 Hot fix].

The hotfix at this location can also be applied if you do not want to or cannot modify your application.

[[Category:Version 3.1.4 FAQ]]
[[Category:Version 3.1.5 FAQ]]

J3.x:CLI Applications Broken

2013-08-02T20:50:33Z

Elin:

Because of changes made to JTable, CLI and some other applications that use JTable break in Joomla 3.1.3 and later.

Adding this code to your application should fix the issue.

<source lang="php">
jimport('joomla.observer.mapper');
jimport('cms.helper.tags');
jimport('cms.table.corecontent');
// Categories is in legacy for CMS 3 so we have to check there.
JLoader::registerPrefix('J', JPATH_PLATFORM . '/legacy');
JLoader::Register('J', JPATH_PLATFORM . '/cms');

</source>

[[Category:Version 3.1.4 FAQ]]
[[Category:Version 3.1.5 FAQ]]

J2.5:SQLSRV Problems in 2.5.13

2013-08-02T14:35:31Z

Elin:

The main article and category list queries are broken for SqlSrv based sites.

To fix please apply the [hotfix that is available on
http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemEdit&tracker_item_id=31634].

[[Category:Version 2.5.13 FAQ]]

J2.5:SQLSRV Problems in 2.5.13

2013-08-02T14:34:29Z

Elin: Created page with " The main article and category list queries are broken for SqlSrv based sites. To fix please apply the [hotfix that is available on http://joomlacode.org/gf/project/joomla/..."

J3.x:Problems for Sqlsrv

2013-08-02T14:32:52Z

J3.x:Cannot log in to Joomla frontend

2013-08-02T14:21:06Z

Elin:

A small number of users have reported not being able to login to the front end in Joomla 3.1.4.

This seems to only occur when the users have a corrupt asset table.

This is usually due to a faulty migration from Joomla 1.5.

As a first step, click the rebuild icon in any categories view and see if this solves the problem.

If this does not solve, look at your asset table in your database. If there is more than one parent_id with a value of 0 this indicates a corrupt table.
'''Only the root asset is allowed to have parent_id=0.'''

TO fix you can manually or with an sql theory change the parent ids.
If the broken assets are categories the parent should be set to the id number for that component (for example usually the id for com_content is 8). (They can also be set to have a parent of another category in the same component.)

For something besides a category (for articles for example), set the parent either to a category id or to the id for the extension if the extension does not use categories.

[[Category:Version 3.1.4 FAQ]][[Category:Version 3.1.5 FAQ]]

J3.x:CLI Applications Broken

2013-08-02T14:18:10Z

Elin:

Because of changes made to JTable, CLI and some other applications that use JTable break in Joomla 3.1.3 and later.

Adding this code to your application should fix the issue.

<source lang="php">
jimport('cms.helper.tags');
jimport('cms.table.corecontent');
// Categories is in legacy for CMS 3 so we have to check there.
JLoader::registerPrefix('J', JPATH_PLATFORM . '/legacy');
JLoader::Register('J', JPATH_PLATFORM . '/cms');

</source>

[[Category:Version 3.1.4 FAQ]]
[[Category:Version 3.1.5 FAQ]]

J3.x:CLI Applications Broken

2013-08-02T14:17:38Z

Elin: Created page with "CLI and some other applications that use JTable break in Joomla 3.1.3 and later. Adding this code to your application should fix the issue. <source lang="php"> jimport('cms...."

CLI and some other applications that use JTable break in Joomla 3.1.3 and later.

Adding this code to your application should fix the issue.

<source lang="php">
jimport('cms.helper.tags');
jimport('cms.table.corecontent');
// Categories is in legacy for CMS 3 so we have to check there.
JLoader::registerPrefix('J', JPATH_PLATFORM . '/legacy');
JLoader::Register('J', JPATH_PLATFORM . '/cms');

</source>

[[Category:Version 3.1.4 FAQ]]
[[Category:Version 3.1.5 FAQ]]

J3.x:Toolbar buttons missing after upgrade

2013-08-02T14:00:22Z

Elin:

{{notice|This issue only affects Joomla! versions 3.1.4 and 3.1.5 or any version where there are CSS changes}}
After performing an update it is '''ESSENTIAL''' to clear your web browser cache to reload the admin template css.

If you do not do this then the user will not see the toolbar buttons.

Refreshing the browser cache solves this immediately.

{{ambox|text='''*Note - some browser especially chrome can have very sticky browser cache and it is not enough to do a ctrl+f5'''}}

If the problem persists you may want to check to see if your server has google_pagespeed enables. If it does, and you want to keep using mod_pagespeed you'll need to flush the server side cache on upgrading to 3.1.x. You do this by logging into the server and then executing

typical command and location:

sudo touch /var/cache/mod_pagespeed/cache.flush

[[Category:Version 3.1.4 FAQ]]
[[Category:Version 3.1.5 FAQ]]

Security hotfixes for Joomla EOL versions

2013-08-02T02:20:06Z

Elin: Created page with "Although Joomla 1.5 has reached end of life, there is a security patch available at this link: http://joomlacode.org/gf/download/trackeritem/31626/83528/UploadFix15v3.zip h..."

Although Joomla 1.5 has reached end of life, there is a security patch available at this link:

http://joomlacode.org/gf/download/trackeritem/31626/83528/UploadFix15v3.zip

http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemEdit&tracker_item_id=31626 is the tracker item and currently there are 3 zips, us the top one.

J3.x:Toolbar buttons missing after upgrade

2013-07-31T21:54:02Z

Elin:

After performing an update it is '''ESSENTIAL''' to clear your web browser cache to reload the admin template css.

If you do not do this then the user will not see the toolbar buttons.

Refreshing the browser cache solves this immediately.

[Note : some browser especially chrome can have very sticky browser cache and its not enough to do a ctrl+f5]

If the problem persists you may want to check to see if your server has google_pagespeed enables. If it does, and you want to keep using mod_pagespeed you'll need to flush the server side cache on upgrading to 3.1.4. You do this by logging into the server and then executing

typical command and location:

sudo touch /var/cache/mod_pagespeed/cache.flush

[[Category:Version 3.1.4 FAQ]]

J3.x:Cannot log in to Joomla frontend

2013-07-30T14:34:41Z

Elin:

Portal:Bug Squad/Intro

2013-07-29T13:24:10Z

Elin:

[[Image:workgroups_bugsquad.jpg|right]]
'''<big>This is where you will find all the information you need as a Joomal! Bug Squad member.</big>'''

The Joomla! Bug Squad (JBS) is a team within the [[Production Working Groups]]. Their job is to identify and fix bugs in Joomla. This includes the following:

* Scan the [http://forum.joomla.org/viewforum.php?f=199 Joomla! Bug Reporting Forum] and [http://forum.joomla.org/viewforum.php?f=579 Joomla! 2.5 Bug Reporting Forum] for reported issues and help community members with solving these issues.
* [[http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemBrowse&tracker_id=8103 CMS Issue Tracker]] .
* Fix reported bugs and resolve reported issues according to the [[Bug Tracking Process]].<noinclude>[[Category:Landing subpages|{{PAGENAME}}]]</noinclude>

J3.x:Cannot create new content 3.1.4

2013-07-28T17:00:05Z

Elin:

Some users report that they receive the following error when attempting to create new content (of any type):

HTTP Error 500 (Internal Server Error): An unexpected condition was
encountered while the server was attempting to fulfill the request.

or with maximum reporting on

Fatal error: Invalid opcode 153/1/8. in
/var/.../libraries/joomla/table/observer/tags.php on line 159

This appears to be caused by a bug in eAccelerator. Either update to the current version or change your caching method to a different option.

[[Category:Version 3.1.4 FAQ]]

J3.x:Cannot create new content 3.1.4

2013-07-28T16:59:23Z

Elin: Created page with "Some users report that they receive the following error when attempting to create new content (of any type): HTTP Error 500 (Internal Server Error): An unexpected condition ..."

Some users report that they receive the following error when attempting to create new content (of any type):

HTTP Error 500 (Internal Server Error): An unexpected condition was encountered while the server was attempting to fulfill the request.

or with maximum reporting on

Fatal error: Invalid opcode 153/1/8. in /var/.../libraries/joomla/table/observer/tags.php on line 159

This appears to be caused by a bug in eAccelerator. Either update to the current version or change your caching method to a different option.

[[Category:Version 3.1.4 FAQ]]

J3.x:Cannot log in to Joomla frontend

2013-07-28T16:32:36Z

Elin:

A small number of users have reported not being able to login to the front end in Joomla 3.1.4.

This seems to only occur when the users have a corrupt asset table.

This is usually due to a faulty migration from Joomla 1.5.

To check this, look at your asset table in your database. If there is more than one parent_id with a value of 0 this indicates a corrupt table.
'''Only the root asset is allowed to have parent_id=0.'''

TO fix you can manually or with an sql theory change the parent ids.
If the broken assets are categories the parent should be set to the id number for that component (for example usually the id for com_content is 8). (They can also be set to have a parent of another category in the same component.)

For something besides a category, set the parent either to a category id or to the id for the extension if the extension does not use categories.

[[Category:Version 3.1.4 FAQ]]

J3.x:Cannot log in to Joomla frontend

2013-07-28T16:29:53Z

Elin: Created page with "A small number of users have reported not being able to login to the front end in Joomla 3.1.4. This seems to only occur when the users have a corrupt asset table. This is..."

A small number of users have reported not being able to login to the front end in Joomla 3.1.4.

This seems to only occur when the users have a corrupt asset table.

This is usually due to a faulty migration from Joomla 1.5.

To check this, look at your asset table in your database. If there is more than one parent_id with a value of 0 this indicates a corrupt table.
'''Only the root asset is allowed to have parent_id=0.'''

TO fix you can manually or with an sql theory change the parent ids.
If the broken assets are categories the parent should be set to the id number for that component (for example usually the id for com_content is 8. (They can also be set to have a parent of another category in the same component).

For something besides a category, set the parent either to a category id or to the id for the extension if the extension does not use categories.

[[Category:Version 3.1.4 FAQ]]

J3.x:Using Tags in an Extension

2013-07-27T18:44:46Z

Elin: /* Modify your component's table class (or classes if you have multiple tables) */

Joomla's tagging system is used in all core content extensions and is designed to be be easy to integrate into other extensions that use standard Joomla design patterns.

Using tags in an extension is relatively straightforward but it requires small changes in a number of specific places.

== Create a content type for each view ==
Note: Types can be added using either sql or postflight by creating a JTableContenttype instance and adding a row.

First identify which tables contain data that will be tagged and what the name of the single item view displaying each of these tables. For example:
* #__contact_details is the table displayed in the view contact of component com_contact with table class ContactTableContact.
* #__weblinks is the table displayed in the view weblink of com_weblinks so WeblinksTableWeblink.

<source lang="sql">
CREATE TABLE IF NOT EXISTS `#__content_types` (
`type_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`type_title` varchar(255) NOT NULL DEFAULT '',
`type_alias` varchar(255) NOT NULL DEFAULT '',
`table` varchar(255) NOT NULL DEFAULT '',
`rules` text NOT NULL,
`field_mappings` text NOT NULL,
`router` varchar(255) NOT NULL DEFAULT '',

</source>

For each table/option/view you will need to make an entry in #__content_types. You can do this either using sql or postflight by creating an instance of JTableContenttype. Don't forget a category type if you use the Joomla categories API.

A string giving component.view (that would be in the page request, typically matching the model name) goes in the **type_alias** field.

'''table''' gives the complete table class information for the table class stored as a JSON object in which the first element represents your "special" table and the second an optional common table (otherwise it will default the JTableCorecontent. This includes the name of the database table, the name of the primary key, the prefix, the name, an option array as used in your constructor and getInstance() methods. This enables the tagging system (and other APIs) to access your table easily.

If you are using Joomla categories make sure to create a category type so that they can be tagged. In Joomla 3.1 and 3.1.1 there is an error where the tag field will show even if there is not a type, but this is corrected in 3.1.4.

'''Important note''' : Please note that the table name for the common table is #__ucm_content. This is INCORRECT in 3.1 and 3.1.1 data but is not currently used. The data was updated in 3.1.4.

<source lang="php">
{"special":{"dbtable":"#__content","key":"id","type":"Content","prefix":"JTable","config":"array()"},"common":{"dbtable":"#__ucm_content","key":"ucm_id","type":"Corecontent","prefix":"JTable","config":"array()"}}
</source>

The '''type_title''' field would potentially be used for display although this is not implemented currently except in the contentttype field. Usually it should begin with an upper case letter if it is in English. See note about how to make this translatable.

note:
To make your type names translatable add
<source lang="php">
COM_TAGS_CONTENT_TYPE_ + the type_title
</source>
in both the ini and sys.ini files.

'''Rules''' is currently not used. It will likely be removed in favor of an asset_id for each type, but currently you can ignore this field which will be managed by JTable.

'''field_mappings''' maps the names of specific fields in your table to a set of standard names. This mapping is stored as a JSON array with the first element mapping to the common fields and the second one mapping the other fields from the table.

'''Important note''' The JHelperTags and JUcm APIS at 3.1.1 supported arrays for this field, but as of 3.1.4 either arrays or objects with a default of objects are supported.

<source lang="php">
'{"common":[{"core_content_item_id":"id","core_title":"title","core_state":"published","core_alias":"alias","core_created_time":"created_time","core_modified_time":"modified_time","core_body":"description", "core_hits":"hits","core_publish_up":"null","core_publish_down":"null","core_access":"access", "core_params":"params", "core_featured":"null", "core_metadata":"metadata", "core_language":"language", "core_images":"null", "core_urls":"null", "core_version":"version", "core_ordering":"null", "core_metakey":"metakey", "core_metadesc":"metadesc", "core_catid":"parent_id", "core_xreference":"null", "asset_id":"asset_id"}], "special": [{"parent_id":"parent_id","lft":"lft","rgt":"rgt","level":"level","path":"path","extension":"extension","note":"note"}]}'
</source>

is the field mapping for the Article type. Note that article uses the name attribs for the core field called params. If your table does not contain a field, put “null” instead. Leaving it blank may cause SQL issues. The special fields are optional. At a minimum for common fields you need to map: content_item_id, alias and title in order to successfully create urls in the tagged items list. You also will probably want: access, status, and language.

'''Router''' is an optional name of a static helper router method for this type found in its front end helpers folder.
If you only store data in #__ucm_content you will eventually be able to leave the router field blank although this option is not currently implemented. If you do not have a custom router tags falls back to the rules found in JHelperRoute.

== Modify your component's table class (or classes if you have multiple tables) ==
Add the following to your JTable constructor:

$this->_observers = new JObserverUpdater($this);
JObserverMapper::attachAllObservers($this);

'''The addition material formerly located here is no longer needed after 3.1.4''' Please read the document history for this page if you are required to support 3.1.0 or 3.1.1.

== Add tags to the getItem() method of the model ==

'''Note: this was only required in 3.1.0 and 3.1.1. It should not be used in 3.1.4 or later.''' Please read the history of this page if you need instructions for older versions.

== Add a tag field to edit screens ==
In any edit layouts where you want to allow tagging, you need to add the field to the xml and the appropriate layouts if necessary. The core layouts us a JLayout to manage this and the same layout by any extension.

Update: Note that in '''3.1.1 only''' there is special handling of this in the core. Tags in the edit screen '''MUST''' be part of a metadata <fields></fields> group. The core provides two JLayouts to help you manage standard layouts, one (details) for the metadata and one for the sidebar that includes the tabs. In update an extension to 3.1.4 you may need to fix adjust your edit views.

In 3.1.4 or later this special handling is not necessary. Best practice is to use the standard JLayouts since this provides a consistent experience for users.

<source lang="xml">
<field name="tags" type="tag"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field></source>

The field loads all the Javascript libraries required. You don't need to worry about that.

The field supports two modes:
* '''Nested tags mode.''' Hierarchical tag list. Doesn't support on the fly tag creation.
* '''AJAX mode.''' Tags are searched while user types (3 min. chars required to launch the AJAX search). Custom tags are added by pressing ENTER or COMMA keys. Tags show the global route/path. Example: <code>grandpa/parent/tag</code>

The field mode can be forced or use the com_tags setting <code>Tag field mode</code> to determine its mode. To set/force the field mode we have to add '''mode="ajax"''' or '''mode="nested"''' to the tag field definition.

Example of forced AJAX mode:

<source lang="xml">
<field name="tags" type="tag" mode="ajax"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>
</source>
The field also includes an attribute to allow/deny the user to enter custom values. Currently this only works in AJAX mode. The attribute has to be added to the field definition like **custom="allow"** or **custom="deny"**

Example field definition with custom tags denied:

<source lang="xml">
<field name="tags" type="tag" mode="ajax" custom="denied"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>

</source>
if it is not already there. Usually multiple should be true unless you have a specific reason for it not to be.
In the core components in administrator, the field is in the group shown on the right, below the language field.

Note: As of 3.1.2 if you wish to use the field to designate parent tags you must add parent="parent" to the xml definition of the field.

== Prepare the view ==
Add an appropriate version of this to your view.html.php file before loading the layout:

<source lang="php">
$item->tags = new JHelperTags;
$item->tags->getItemTags('com_newsfeeds.newsfeed.' , $this->item->id);
</source>

The first parameter should match a type in the types table. The second parameter is the primary key under which this record is stored in your table. This would be used in any display in any view where you want the tags associated with the item to display.

== Set up the display ==

In any layout where you want to display the tags associated with an item add:
<source lang="php">
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>

</source>
Changing the object and property names as appropriate.

You will most likely want to add the show_tags parameter to the item parameters, the menu item parameters and component configuration as appropriate for your use case.

<source lang="php">
<?php if ($this->params->get('show_tags', 1) && !empty($this->item->tags)) : ?>
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>
<?php endif; ?></source>

== Batch processing ==
If you want to add the ability to do batch tagging to a backend list view do the following.

Add tag to the default_batch layout

<source lang="php">
<div class="control-group">
<div class="controls">
<?php echo JHtml::_('batch.tag');?>
</div>
</div></source>

And add tag to the button class in the modal footer (Not totally necessary at this point, but good for potential future changes e.g. if unTag is added.)

<source lang="php">
<button class="btn" type="button" onclick="document.id('batch-category-id').value='';document.id('batch-access').value='';document.id('batch-language-id').value='';document.id('batch-user-id').value='';document.id('batch-tag-id)').value=''" data-dismiss="modal">
</source>

=== Add a batch method to your model if you are not extending JModelAdmin or overriding the batch method. ===

<source lang="php">
/**
* Batch tag a list of item.
*
* @param integer $value The value of the new tag.
* @param array $pks An array of row IDs.
* @param array $contexts An array of item contexts.
*
* @return void.
*
* @since 3.1
*/
protected function batchTag($value, $pks, $contexts)
{
$tagsHelper = new JHelperTags();
$tagsHelper->tagItems($value, $pks, $contexts);

return true;
}
</source>

And modify your batch method by adding
<source lang="php">
if (!empty($commands['tag']))
{
if (!$this->batchTag($commands['tag'], $pks, $contexts))
{
return false;
}

$done = true;
}

</source>

Pay attention to any JSON encoded strings that you need special handling for in batch processing -- remember that you are saving a copy of the core fields and you need save to work as expected.

That’s it, now create some tags, tag some items and you are set.

[[Category:Development]][[Category:Content Tags]]
[[Category:Tutorials]]

J3.x:Using Tags in an Extension

2013-07-27T18:32:10Z

Elin:

Joomla's tagging system is used in all core content extensions and is designed to be be easy to integrate into other extensions that use standard Joomla design patterns.

Using tags in an extension is relatively straightforward but it requires small changes in a number of specific places.

== Create a content type for each view ==
Note: Types can be added using either sql or postflight by creating a JTableContenttype instance and adding a row.

First identify which tables contain data that will be tagged and what the name of the single item view displaying each of these tables. For example:
* #__contact_details is the table displayed in the view contact of component com_contact with table class ContactTableContact.
* #__weblinks is the table displayed in the view weblink of com_weblinks so WeblinksTableWeblink.

<source lang="sql">
CREATE TABLE IF NOT EXISTS `#__content_types` (
`type_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`type_title` varchar(255) NOT NULL DEFAULT '',
`type_alias` varchar(255) NOT NULL DEFAULT '',
`table` varchar(255) NOT NULL DEFAULT '',
`rules` text NOT NULL,
`field_mappings` text NOT NULL,
`router` varchar(255) NOT NULL DEFAULT '',

</source>

For each table/option/view you will need to make an entry in #__content_types. You can do this either using sql or postflight by creating an instance of JTableContenttype. Don't forget a category type if you use the Joomla categories API.

A string giving component.view (that would be in the page request, typically matching the model name) goes in the **type_alias** field.

'''table''' gives the complete table class information for the table class stored as a JSON object in which the first element represents your "special" table and the second an optional common table (otherwise it will default the JTableCorecontent. This includes the name of the database table, the name of the primary key, the prefix, the name, an option array as used in your constructor and getInstance() methods. This enables the tagging system (and other APIs) to access your table easily.

If you are using Joomla categories make sure to create a category type so that they can be tagged. In Joomla 3.1 and 3.1.1 there is an error where the tag field will show even if there is not a type, but this is corrected in 3.1.4.

'''Important note''' : Please note that the table name for the common table is #__ucm_content. This is INCORRECT in 3.1 and 3.1.1 data but is not currently used. The data was updated in 3.1.4.

<source lang="php">
{"special":{"dbtable":"#__content","key":"id","type":"Content","prefix":"JTable","config":"array()"},"common":{"dbtable":"#__ucm_content","key":"ucm_id","type":"Corecontent","prefix":"JTable","config":"array()"}}
</source>

The '''type_title''' field would potentially be used for display although this is not implemented currently except in the contentttype field. Usually it should begin with an upper case letter if it is in English. See note about how to make this translatable.

note:
To make your type names translatable add
<source lang="php">
COM_TAGS_CONTENT_TYPE_ + the type_title
</source>
in both the ini and sys.ini files.

'''Rules''' is currently not used. It will likely be removed in favor of an asset_id for each type, but currently you can ignore this field which will be managed by JTable.

'''field_mappings''' maps the names of specific fields in your table to a set of standard names. This mapping is stored as a JSON array with the first element mapping to the common fields and the second one mapping the other fields from the table.

'''Important note''' The JHelperTags and JUcm APIS at 3.1.1 supported arrays for this field, but as of 3.1.4 either arrays or objects with a default of objects are supported.

<source lang="php">
'{"common":[{"core_content_item_id":"id","core_title":"title","core_state":"published","core_alias":"alias","core_created_time":"created_time","core_modified_time":"modified_time","core_body":"description", "core_hits":"hits","core_publish_up":"null","core_publish_down":"null","core_access":"access", "core_params":"params", "core_featured":"null", "core_metadata":"metadata", "core_language":"language", "core_images":"null", "core_urls":"null", "core_version":"version", "core_ordering":"null", "core_metakey":"metakey", "core_metadesc":"metadesc", "core_catid":"parent_id", "core_xreference":"null", "asset_id":"asset_id"}], "special": [{"parent_id":"parent_id","lft":"lft","rgt":"rgt","level":"level","path":"path","extension":"extension","note":"note"}]}'
</source>

is the field mapping for the Article type. Note that article uses the name attribs for the core field called params. If your table does not contain a field, put “null” instead. Leaving it blank may cause SQL issues. The special fields are optional. At a minimum for common fields you need to map: content_item_id, alias and title in order to successfully create urls in the tagged items list. You also will probably want: access, status, and language.

'''Router''' is an optional name of a static helper router method for this type found in its front end helpers folder.
If you only store data in #__ucm_content you will eventually be able to leave the router field blank although this option is not currently implemented. If you do not have a custom router tags falls back to the rules found in JHelperRoute.

== Modify your component's table class (or classes if you have multiple tables) ==

'''This is no longer needed after 3.1.4''' Please read the document history for this page if you are required to support 3.1.0 or 3.1.1.

== Add tags to the getItem() method of the model ==

'''Note: this was only required in 3.1.0 and 3.1.1. It should not be used in 3.1.4 or later.''' Please read the history of this page if you need instructions for older versions.

== Add a tag field to edit screens ==
In any edit layouts where you want to allow tagging, you need to add the field to the xml and the appropriate layouts if necessary. The core layouts us a JLayout to manage this and the same layout by any extension.

Update: Note that in '''3.1.1 only''' there is special handling of this in the core. Tags in the edit screen '''MUST''' be part of a metadata <fields></fields> group. The core provides two JLayouts to help you manage standard layouts, one (details) for the metadata and one for the sidebar that includes the tabs. In update an extension to 3.1.4 you may need to fix adjust your edit views.

In 3.1.4 or later this special handling is not necessary. Best practice is to use the standard JLayouts since this provides a consistent experience for users.

<source lang="xml">
<field name="tags" type="tag"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field></source>

The field loads all the Javascript libraries required. You don't need to worry about that.

The field supports two modes:
* '''Nested tags mode.''' Hierarchical tag list. Doesn't support on the fly tag creation.
* '''AJAX mode.''' Tags are searched while user types (3 min. chars required to launch the AJAX search). Custom tags are added by pressing ENTER or COMMA keys. Tags show the global route/path. Example: <code>grandpa/parent/tag</code>

The field mode can be forced or use the com_tags setting <code>Tag field mode</code> to determine its mode. To set/force the field mode we have to add '''mode="ajax"''' or '''mode="nested"''' to the tag field definition.

Example of forced AJAX mode:

<source lang="xml">
<field name="tags" type="tag" mode="ajax"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>
</source>
The field also includes an attribute to allow/deny the user to enter custom values. Currently this only works in AJAX mode. The attribute has to be added to the field definition like **custom="allow"** or **custom="deny"**

Example field definition with custom tags denied:

<source lang="xml">
<field name="tags" type="tag" mode="ajax" custom="denied"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>

</source>
if it is not already there. Usually multiple should be true unless you have a specific reason for it not to be.
In the core components in administrator, the field is in the group shown on the right, below the language field.

Note: As of 3.1.2 if you wish to use the field to designate parent tags you must add parent="parent" to the xml definition of the field.

== Prepare the view ==
Add an appropriate version of this to your view.html.php file before loading the layout:

<source lang="php">
$item->tags = new JHelperTags;
$item->tags->getItemTags('com_newsfeeds.newsfeed.' , $this->item->id);
</source>

The first parameter should match a type in the types table. The second parameter is the primary key under which this record is stored in your table. This would be used in any display in any view where you want the tags associated with the item to display.

== Set up the display ==

In any layout where you want to display the tags associated with an item add:
<source lang="php">
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>

</source>
Changing the object and property names as appropriate.

You will most likely want to add the show_tags parameter to the item parameters, the menu item parameters and component configuration as appropriate for your use case.

<source lang="php">
<?php if ($this->params->get('show_tags', 1) && !empty($this->item->tags)) : ?>
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>
<?php endif; ?></source>

== Batch processing ==
If you want to add the ability to do batch tagging to a backend list view do the following.

Add tag to the default_batch layout

<source lang="php">
<div class="control-group">
<div class="controls">
<?php echo JHtml::_('batch.tag');?>
</div>
</div></source>

And add tag to the button class in the modal footer (Not totally necessary at this point, but good for potential future changes e.g. if unTag is added.)

<source lang="php">
<button class="btn" type="button" onclick="document.id('batch-category-id').value='';document.id('batch-access').value='';document.id('batch-language-id').value='';document.id('batch-user-id').value='';document.id('batch-tag-id)').value=''" data-dismiss="modal">
</source>

=== Add a batch method to your model if you are not extending JModelAdmin or overriding the batch method. ===

<source lang="php">
/**
* Batch tag a list of item.
*
* @param integer $value The value of the new tag.
* @param array $pks An array of row IDs.
* @param array $contexts An array of item contexts.
*
* @return void.
*
* @since 3.1
*/
protected function batchTag($value, $pks, $contexts)
{
$tagsHelper = new JHelperTags();
$tagsHelper->tagItems($value, $pks, $contexts);

return true;
}
</source>

And modify your batch method by adding
<source lang="php">
if (!empty($commands['tag']))
{
if (!$this->batchTag($commands['tag'], $pks, $contexts))
{
return false;
}

$done = true;
}

</source>

Pay attention to any JSON encoded strings that you need special handling for in batch processing -- remember that you are saving a copy of the core fields and you need save to work as expected.

That’s it, now create some tags, tag some items and you are set.

[[Category:Development]][[Category:Content Tags]]
[[Category:Tutorials]]

J3.x:Using Tags in an Extension

2013-07-27T18:18:21Z

Elin: /* Add or modify a delete() method */

Joomla's tagging system is used in all core content extensions and is designed to be be easy to integrate into other extensions that use standard Joomla design patterns.

Using tags in an extension is relatively straightforward but it requires small changes in a number of specific places.

== Create a content type for each view ==
Note: Types can be added using either sql or postflight by creating a JTableContenttype instance and adding a row.

First identify which tables contain data that will be tagged and what the name of the single item view displaying each of these tables. For example:
* #__contact_details is the table displayed in the view contact of component com_contact with table class ContactTableContact.
* #__weblinks is the table displayed in the view weblink of com_weblinks so WeblinksTableWeblink.

<source lang="sql">
CREATE TABLE IF NOT EXISTS `#__content_types` (
`type_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`type_title` varchar(255) NOT NULL DEFAULT '',
`type_alias` varchar(255) NOT NULL DEFAULT '',
`table` varchar(255) NOT NULL DEFAULT '',
`rules` text NOT NULL,
`field_mappings` text NOT NULL,
`router` varchar(255) NOT NULL DEFAULT '',

</source>

For each table/option/view you will need to make an entry in #__content_types. You can do this either using sql or postflight by creating an instance of JTableContenttype. Don't forget a category type if you use the Joomla categories API.

A string giving component.view (that would be in the page request, typically matching the model name) goes in the **type_alias** field.

'''table''' gives the complete table class information for the table class stored as a JSON object in which the first element represents your "special" table and the second an optional common table (otherwise it will default the JTableCorecontent. This includes the name of the database table, the name of the primary key, the prefix, the name, an option array as used in your constructor and getInstance() methods. This enables the tagging system (and other APIs) to access your table easily.

If you are using Joomla categories make sure to create a category type so that they can be tagged. In Joomla 3.1 and 3.1.1 there is an error where the tag field will show even if there is not a type, but this is corrected in 3.1.4.

'''Important note''' : Please note that the table name for the common table is #__ucm_content. This is INCORRECT in 3.1 and 3.1.1 data but is not currently used. The data was updated in 3.1.4.

<source lang="php">
{"special":{"dbtable":"#__content","key":"id","type":"Content","prefix":"JTable","config":"array()"},"common":{"dbtable":"#__ucm_content","key":"ucm_id","type":"Corecontent","prefix":"JTable","config":"array()"}}
</source>

The '''type_title''' field would potentially be used for display although this is not implemented currently except in the contentttype field. Usually it should begin with an upper case letter if it is in English. See note about how to make this translatable.

note:
To make your type names translatable add
<source lang="php">
COM_TAGS_CONTENT_TYPE_ + the type_title
</source>
in both the ini and sys.ini files.

'''Rules''' is currently not used. It will likely be removed in favor of an asset_id for each type, but currently you can ignore this field which will be managed by JTable.

'''field_mappings''' maps the names of specific fields in your table to a set of standard names. This mapping is stored as a JSON array with the first element mapping to the common fields and the second one mapping the other fields from the table.

'''Important note''' The JHelperTags and JUcm APIS at 3.1.1 supported arrays for this field, but as of 3.1.4 either arrays or objects with a default of objects are supported.

<source lang="php">
'{"common":[{"core_content_item_id":"id","core_title":"title","core_state":"published","core_alias":"alias","core_created_time":"created_time","core_modified_time":"modified_time","core_body":"description", "core_hits":"hits","core_publish_up":"null","core_publish_down":"null","core_access":"access", "core_params":"params", "core_featured":"null", "core_metadata":"metadata", "core_language":"language", "core_images":"null", "core_urls":"null", "core_version":"version", "core_ordering":"null", "core_metakey":"metakey", "core_metadesc":"metadesc", "core_catid":"parent_id", "core_xreference":"null", "asset_id":"asset_id"}], "special": [{"parent_id":"parent_id","lft":"lft","rgt":"rgt","level":"level","path":"path","extension":"extension","note":"note"}]}'
</source>

is the field mapping for the Article type. Note that article uses the name attribs for the core field called params. If your table does not contain a field, put “null” instead. Leaving it blank may cause SQL issues. The special fields are optional. At a minimum for common fields you need to map: content_item_id, alias and title in order to successfully create urls in the tagged items list. You also will probably want: access, status, and language.

'''Router''' is an optional name of a static helper router method for this type found in its front end helpers folder.
If you only store data in #__ucm_content you will eventually be able to leave the router field blank although this option is not currently implemented. If you do not have a custom router tags falls back to the rules found in JHelperRoute.

== Modify your component's table class (or classes if you have multiple tables) ==

This has several parts.

=== Add a property ===

<source lang="php">
/**
* Indicator that the tags have been changed
*
* @var JHelperTags
* @since 3.1
*/
protected $tagsHelper = null;
</source>
This property helps to manage change in tags.

=== Modify your constructor ===

Follow this example to modify your consructor which provides substantial reduction in duplicate code.
<source lang="php">
$this->tagsHelper = new JHelperTags();
$this->tagsHelper->typeAlias = 'com_contact.contact';
</source>

=== Modify your store() method ===
Note that this applies only to 3.1.0 and 3.1.1. This is not needed in 3.1.4 or later if other changes are followed. It is not necessary to remove this code from 3.1.0/3.1.1 style implementations.

Management of tagging and associated data is largely handled through the store() method. This provides maximum flexibility for the handling of tags across many extensions.

If you don't have a store() method you will need to add one. The assumption is that tables will inherit from JTable.

The handling involves preStoreProcess(), a call to the parent store() method, and then a postStoreProcess().

<source lang="php">
$this->tagsHelper->preStoreProcess($this);
$result = parent::store($updateNulls);

return $result && $this->tagsHelper->postStoreProcess($this);
</source>

It is important that this be in the correct order since completion of tag processing depends on having primary key data from the parent store() method.

Note that much of this code is designed to prevent storage in in #__ucm_content when items are not tagged. If you want to always store in #__ucm_content you should modify the handling appropriately.

=== Add or modify a delete() method ===

Note this is only needed in 3.1.0 and 3.1.1. It is no longer required in 3.1.4 or later.
The basic structure:

<source lang="php">
/**
* Method to delete a row from the database table by primary key value.
*
* @param integer $pk Primary key to delete.
*
* @return boolean True on success.
*
* @since 3.1
* @throws UnexpectedValueException
*/
public function delete($pk = null)
{
$result = parent::delete($pk);
return $result && $this->tagsHelper->deleteTagData($this, $pk);
}

</source>

This manages the deletion of all related data if a content item is deleted.

===Backward Compatibility for later than 3.1.4 ===

If you implemented tags prior to 3.1.4 you may need to add the following method to your class if you do not wish to redo all of tagging in your extension.

<source lang="php">
/**
* Method to validate the form data.
*
* @param JForm $form The form to validate against.
* @param array $data The data to validate.
* @param string $group The name of the field group to validate.
*
* @return mixed Array of filtered data if valid, false otherwise.
*
* @see JFormRule
* @see JFilterInput
* @since 2.1
*/
public function validate($form, $data, $group = null)
{
$data = parent::validate($form, $data, $group);

// Tags B/C break at 3.1.2
if (version_compare(JVERSION, '3.1.2', 'ge'))
{
if (isset($data['metadata']['tags']))
{
$data['tags'] = $data['metadata']['tags'];
}
}

return $data;
}
</source>

== Add tags to the getItem() method of the model ==

'''Note: this was only required in 3.1.0 and 3.1.1. It should not be used in 3.1.4 or later.'''

In the getItem() (or similar) method of your model add
<source lang="php">
// Load item tags
if (!empty($item->id))
{
$item->tags = new JHelperTags;
$item->tags->getTagIds($item->id, 'com_contact.contact');
$item->metadata['tags'] = $item->tags;
}
</source>
changing to your component and alias name, matching what is in the type table.and changing the name of id property to the name of your primary key.

== Add a tag field to edit screens ==
In any edit layouts where you want to allow tagging, you need to add the field to the xml and the appropriate layouts if necessary. The core layouts us a JLayout to manage this and the same layout by any extension.

Update: Note that in '''3.1.1 only''' there is special handling of this in the core. Tags in the edit screen '''MUST''' be part of a metadata <fields></fields> group. The core provides two JLayouts to help you manage standard layouts, one (details) for the metadata and one for the sidebar that includes the tabs.

In 3.1.4 or later this special handling is not necessary. Best practice is to use the standard JLayouts since this provides a consistent experience for users.

<source lang="xml">
<field name="tags" type="tag"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field></source>

The field loads all the Javascript libraries required. You don't need to worry about that.

The field supports two modes:
* '''Nested tags mode.''' Hierarchical tag list. Doesn't support on the fly tag creation.
* '''AJAX mode.''' Tags are searched while user types (3 min. chars required to launch the AJAX search). Custom tags are added by pressing ENTER or COMMA keys. Tags show the global route/path. Example: <code>grandpa/parent/tag</code>

The field mode can be forced or use the com_tags setting <code>Tag field mode</code> to determine its mode. To set/force the field mode we have to add '''mode="ajax"''' or '''mode="nested"''' to the tag field definition.

Example of forced AJAX mode:

<source lang="xml">
<field name="tags" type="tag" mode="ajax"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>
</source>
The field also includes an attribute to allow/deny the user to enter custom values. Currently this only works in AJAX mode. The attribute has to be added to the field definition like **custom="allow"** or **custom="deny"**

Example field definition with custom tags denied:

<source lang="xml">
<field name="tags" type="tag" mode="ajax" custom="denied"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>

</source>
if it is not already there. Usually multiple should be true unless you have a specific reason for it not to be.
In the core components in administrator, the field is in the group shown on the right, below the language field.

Note: As of 3.1.2 if you wish to use the field to designate parent tags you must add parent="parent" to the xml definition of the field.

== Prepare the view ==
Add an appropriate version of this to your view.html.php file before loading the layout:

<source lang="php">
$item->tags = new JHelperTags;
$item->tags->getItemTags('com_newsfeeds.newsfeed.' , $this->item->id);
</source>

The first parameter should match a type in the types table. The second parameter is the primary key under which this record is stored in your table. This would be used in any display in any view where you want the tags associated with the item to display.

== Set up the display ==

In any layout where you want to display the tags associated with an item add:
<source lang="php">
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>

</source>
Changing the object and property names as appropriate.

You will most likely want to add the show_tags parameter to the item parameters, the menu item parameters and component configuration as appropriate for your use case.

<source lang="php">
<?php if ($this->params->get('show_tags', 1) && !empty($this->item->tags)) : ?>
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>
<?php endif; ?></source>

== Batch processing ==
If you want to add the ability to do batch tagging to a backend list view do the following.

Add tag to the default_batch layout

<source lang="php">
<div class="control-group">
<div class="controls">
<?php echo JHtml::_('batch.tag');?>
</div>
</div></source>

And add tag to the button class in the modal footer (Not totally necessary at this point, but good for potential future changes e.g. if unTag is added.)

<source lang="php">
<button class="btn" type="button" onclick="document.id('batch-category-id').value='';document.id('batch-access').value='';document.id('batch-language-id').value='';document.id('batch-user-id').value='';document.id('batch-tag-id)').value=''" data-dismiss="modal">
</source>

=== Add a batch method to your model if you are not extending JModelAdmin or overriding the batch method. ===

<source lang="php">
/**
* Batch tag a list of item.
*
* @param integer $value The value of the new tag.
* @param array $pks An array of row IDs.
* @param array $contexts An array of item contexts.
*
* @return void.
*
* @since 3.1
*/
protected function batchTag($value, $pks, $contexts)
{
$tagsHelper = new JHelperTags();
$tagsHelper->tagItems($value, $pks, $contexts);

return true;
}
</source>

And modify your batch method by adding
<source lang="php">
if (!empty($commands['tag']))
{
if (!$this->batchTag($commands['tag'], $pks, $contexts))
{
return false;
}

$done = true;
}

</source>

Pay attention to any JSON encoded strings that you need special handling for in batch processing -- remember that you are saving a copy of the core fields and you need save to work as expected.

That’s it, now create some tags, tag some items and you are set.

[[Category:Development]][[Category:Content Tags]]
[[Category:Tutorials]]

J3.x:Extensions Broken in 3.1.4

2013-07-27T17:14:37Z

Elin:

Some extensions that worked in 3.1.1 give a 500 error in version 3.1.4 . If you have this problem you can install this [http://joomlacode.org/gf/download/trackeritem/31565/83397/legacy.zip hotfix] just as you would a normal extension.

Extension Manager => Install

This will be fixed in 3.1.5.

For any other extension related issues, please contact the extension developer for information.
[[Category:Version 3.1.4 FAQ]]

J3.x:Extensions Broken in 3.1.4

2013-07-27T17:03:41Z

Elin:

Some extensions that worked in 3.1.1 give a 500 error in version 3.1.4 . If you have this problem you can install this [http://joomlacode.org/gf/download/trackeritem/31565/83397/legacy.zip hotfix] just as you would a normal extension.

For any other extension related issues, please contact the extension developer for information.
[[Category:Version 3.1.4 FAQ]]

J3.x:Extensions Broken in 3.1.4

2013-07-27T16:59:01Z

Elin: Created page with "Some extensions break in version 3.1.4. If you have this problem you can install this [http://joomlacode.org/gf/download/trackeritem/31565/83397/legacy.zip hotfix] just as you..."

Some extensions break in version 3.1.4. If you have this problem you can install this [http://joomlacode.org/gf/download/trackeritem/31565/83397/legacy.zip hotfix] just as you would a normal extension.

[[Category:Version 3.1.4 FAQ]]

J3.x:Using Tags in an Extension

2013-07-27T16:47:44Z

Elin: /* Add a tag field to edit screens */

Joomla's tagging system is used in all core content extensions and is designed to be be easy to integrate into other extensions that use standard Joomla design patterns.

Using tags in an extension is relatively straightforward but it requires small changes in a number of specific places.

== Create a content type for each view ==
Note: Types can be added using either sql or postflight by creating a JTableContenttype instance and adding a row.

First identify which tables contain data that will be tagged and what the name of the single item view displaying each of these tables. For example:
* #__contact_details is the table displayed in the view contact of component com_contact with table class ContactTableContact.
* #__weblinks is the table displayed in the view weblink of com_weblinks so WeblinksTableWeblink.

<source lang="sql">
CREATE TABLE IF NOT EXISTS `#__content_types` (
`type_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`type_title` varchar(255) NOT NULL DEFAULT '',
`type_alias` varchar(255) NOT NULL DEFAULT '',
`table` varchar(255) NOT NULL DEFAULT '',
`rules` text NOT NULL,
`field_mappings` text NOT NULL,
`router` varchar(255) NOT NULL DEFAULT '',

</source>

For each table/option/view you will need to make an entry in #__content_types. You can do this either using sql or postflight by creating an instance of JTableContenttype. Don't forget a category type if you use the Joomla categories API.

A string giving component.view (that would be in the page request, typically matching the model name) goes in the **type_alias** field.

'''table''' gives the complete table class information for the table class stored as a JSON object in which the first element represents your "special" table and the second an optional common table (otherwise it will default the JTableCorecontent. This includes the name of the database table, the name of the primary key, the prefix, the name, an option array as used in your constructor and getInstance() methods. This enables the tagging system (and other APIs) to access your table easily.

If you are using Joomla categories make sure to create a category type so that they can be tagged. In Joomla 3.1 and 3.1.1 there is an error where the tag field will show even if there is not a type, but this is corrected in 3.1.4.

'''Important note''' : Please note that the table name for the common table is #__ucm_content. This is INCORRECT in 3.1 and 3.1.1 data but is not currently used. The data was updated in 3.1.4.

<source lang="php">
{"special":{"dbtable":"#__content","key":"id","type":"Content","prefix":"JTable","config":"array()"},"common":{"dbtable":"#__ucm_content","key":"ucm_id","type":"Corecontent","prefix":"JTable","config":"array()"}}
</source>

The '''type_title''' field would potentially be used for display although this is not implemented currently except in the contentttype field. Usually it should begin with an upper case letter if it is in English. See note about how to make this translatable.

note:
To make your type names translatable add
<source lang="php">
COM_TAGS_CONTENT_TYPE_ + the type_title
</source>
in both the ini and sys.ini files.

'''Rules''' is currently not used. It will likely be removed in favor of an asset_id for each type, but currently you can ignore this field which will be managed by JTable.

'''field_mappings''' maps the names of specific fields in your table to a set of standard names. This mapping is stored as a JSON array with the first element mapping to the common fields and the second one mapping the other fields from the table.

'''Important note''' The JHelperTags and JUcm APIS at 3.1.1 supported arrays for this field, but as of 3.1.4 either arrays or objects with a default of objects are supported.

<source lang="php">
'{"common":[{"core_content_item_id":"id","core_title":"title","core_state":"published","core_alias":"alias","core_created_time":"created_time","core_modified_time":"modified_time","core_body":"description", "core_hits":"hits","core_publish_up":"null","core_publish_down":"null","core_access":"access", "core_params":"params", "core_featured":"null", "core_metadata":"metadata", "core_language":"language", "core_images":"null", "core_urls":"null", "core_version":"version", "core_ordering":"null", "core_metakey":"metakey", "core_metadesc":"metadesc", "core_catid":"parent_id", "core_xreference":"null", "asset_id":"asset_id"}], "special": [{"parent_id":"parent_id","lft":"lft","rgt":"rgt","level":"level","path":"path","extension":"extension","note":"note"}]}'
</source>

is the field mapping for the Article type. Note that article uses the name attribs for the core field called params. If your table does not contain a field, put “null” instead. Leaving it blank may cause SQL issues. The special fields are optional. At a minimum for common fields you need to map: content_item_id, alias and title in order to successfully create urls in the tagged items list. You also will probably want: access, status, and language.

'''Router''' is an optional name of a static helper router method for this type found in its front end helpers folder.
If you only store data in #__ucm_content you will eventually be able to leave the router field blank although this option is not currently implemented. If you do not have a custom router tags falls back to the rules found in JHelperRoute.

== Modify your component's table class (or classes if you have multiple tables) ==

This has several parts.

=== Add a property ===

<source lang="php">
/**
* Indicator that the tags have been changed
*
* @var JHelperTags
* @since 3.1
*/
protected $tagsHelper = null;
</source>
This property helps to manage change in tags.

=== Modify your constructor ===

Follow this example to modify your consructor which provides substantial reduction in duplicate code.
<source lang="php">
$this->tagsHelper = new JHelperTags();
$this->tagsHelper->typeAlias = 'com_contact.contact';
</source>

=== Modify your store() method ===
Note that this applies only to 3.1.0 and 3.1.1. This is not needed in 3.1.4 or later if other changes are followed. It is not necessary to remove this code from 3.1.0/3.1.1 style implementations.

Management of tagging and associated data is largely handled through the store() method. This provides maximum flexibility for the handling of tags across many extensions.

If you don't have a store() method you will need to add one. The assumption is that tables will inherit from JTable.

The handling involves preStoreProcess(), a call to the parent store() method, and then a postStoreProcess().

<source lang="php">
$this->tagsHelper->preStoreProcess($this);
$result = parent::store($updateNulls);

return $result && $this->tagsHelper->postStoreProcess($this);
</source>

It is important that this be in the correct order since completion of tag processing depends on having primary key data from the parent store() method.

Note that much of this code is designed to prevent storage in in #__ucm_content when items are not tagged. If you want to always store in #__ucm_content you should modify the handling appropriately.

=== Add or modify a delete() method ===

Note this is only needed in 3.1.0 and 3.1.1. It is no longer required in 3.1.4 or later.
The basic structure:

<source lang="php">
/**
* Method to delete a row from the database table by primary key value.
*
* @param integer $pk Primary key to delete.
*
* @return boolean True on success.
*
* @since 3.1
* @throws UnexpectedValueException
*/
public function delete($pk = null)
{
$result = parent::delete($pk);
return $result && $this->tagsHelper->deleteTagData($this, $pk);
}

</source>

This manages the deletion of all related data if a content item is deleted.

== Add tags to the getItem() method of the model ==

'''Note: this was only required in 3.1.0 and 3.1.1. It should not be used in 3.1.4 or later.'''

In the getItem() (or similar) method of your model add
<source lang="php">
// Load item tags
if (!empty($item->id))
{
$item->tags = new JHelperTags;
$item->tags->getTagIds($item->id, 'com_contact.contact');
$item->metadata['tags'] = $item->tags;
}
</source>
changing to your component and alias name, matching what is in the type table.and changing the name of id property to the name of your primary key.

== Add a tag field to edit screens ==
In any edit layouts where you want to allow tagging, you need to add the field to the xml and the appropriate layouts if necessary. The core layouts us a JLayout to manage this and the same layout by any extension.

Update: Note that in '''3.1.1 only''' there is special handling of this in the core. Tags in the edit screen '''MUST''' be part of a metadata <fields></fields> group. The core provides two JLayouts to help you manage standard layouts, one (details) for the metadata and one for the sidebar that includes the tabs.

In 3.1.4 or later this special handling is not necessary. Best practice is to use the standard JLayouts since this provides a consistent experience for users.

<source lang="xml">
<field name="tags" type="tag"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field></source>

The field loads all the Javascript libraries required. You don't need to worry about that.

The field supports two modes:
* '''Nested tags mode.''' Hierarchical tag list. Doesn't support on the fly tag creation.
* '''AJAX mode.''' Tags are searched while user types (3 min. chars required to launch the AJAX search). Custom tags are added by pressing ENTER or COMMA keys. Tags show the global route/path. Example: <code>grandpa/parent/tag</code>

The field mode can be forced or use the com_tags setting <code>Tag field mode</code> to determine its mode. To set/force the field mode we have to add '''mode="ajax"''' or '''mode="nested"''' to the tag field definition.

Example of forced AJAX mode:

<source lang="xml">
<field name="tags" type="tag" mode="ajax"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>
</source>
The field also includes an attribute to allow/deny the user to enter custom values. Currently this only works in AJAX mode. The attribute has to be added to the field definition like **custom="allow"** or **custom="deny"**

Example field definition with custom tags denied:

<source lang="xml">
<field name="tags" type="tag" mode="ajax" custom="denied"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>

</source>
if it is not already there. Usually multiple should be true unless you have a specific reason for it not to be.
In the core components in administrator, the field is in the group shown on the right, below the language field.

Note: As of 3.1.2 if you wish to use the field to designate parent tags you must add parent="parent" to the xml definition of the field.

== Prepare the view ==
Add an appropriate version of this to your view.html.php file before loading the layout:

<source lang="php">
$item->tags = new JHelperTags;
$item->tags->getItemTags('com_newsfeeds.newsfeed.' , $this->item->id);
</source>

The first parameter should match a type in the types table. The second parameter is the primary key under which this record is stored in your table. This would be used in any display in any view where you want the tags associated with the item to display.

== Set up the display ==

In any layout where you want to display the tags associated with an item add:
<source lang="php">
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>

</source>
Changing the object and property names as appropriate.

You will most likely want to add the show_tags parameter to the item parameters, the menu item parameters and component configuration as appropriate for your use case.

<source lang="php">
<?php if ($this->params->get('show_tags', 1) && !empty($this->item->tags)) : ?>
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>
<?php endif; ?></source>

== Batch processing ==
If you want to add the ability to do batch tagging to a backend list view do the following.

Add tag to the default_batch layout

<source lang="php">
<div class="control-group">
<div class="controls">
<?php echo JHtml::_('batch.tag');?>
</div>
</div></source>

And add tag to the button class in the modal footer (Not totally necessary at this point, but good for potential future changes e.g. if unTag is added.)

<source lang="php">
<button class="btn" type="button" onclick="document.id('batch-category-id').value='';document.id('batch-access').value='';document.id('batch-language-id').value='';document.id('batch-user-id').value='';document.id('batch-tag-id)').value=''" data-dismiss="modal">
</source>

=== Add a batch method to your model if you are not extending JModelAdmin or overriding the batch method. ===

<source lang="php">
/**
* Batch tag a list of item.
*
* @param integer $value The value of the new tag.
* @param array $pks An array of row IDs.
* @param array $contexts An array of item contexts.
*
* @return void.
*
* @since 3.1
*/
protected function batchTag($value, $pks, $contexts)
{
$tagsHelper = new JHelperTags();
$tagsHelper->tagItems($value, $pks, $contexts);

return true;
}
</source>

And modify your batch method by adding
<source lang="php">
if (!empty($commands['tag']))
{
if (!$this->batchTag($commands['tag'], $pks, $contexts))
{
return false;
}

$done = true;
}

</source>

Pay attention to any JSON encoded strings that you need special handling for in batch processing -- remember that you are saving a copy of the core fields and you need save to work as expected.

That’s it, now create some tags, tag some items and you are set.

[[Category:Development]][[Category:Content Tags]]
[[Category:Tutorials]]

J3.x:Using Tags in an Extension

2013-07-27T16:46:08Z

Elin: /* Add tags to the getItem() method of the model */

Joomla's tagging system is used in all core content extensions and is designed to be be easy to integrate into other extensions that use standard Joomla design patterns.

Using tags in an extension is relatively straightforward but it requires small changes in a number of specific places.

== Create a content type for each view ==
Note: Types can be added using either sql or postflight by creating a JTableContenttype instance and adding a row.

First identify which tables contain data that will be tagged and what the name of the single item view displaying each of these tables. For example:
* #__contact_details is the table displayed in the view contact of component com_contact with table class ContactTableContact.
* #__weblinks is the table displayed in the view weblink of com_weblinks so WeblinksTableWeblink.

<source lang="sql">
CREATE TABLE IF NOT EXISTS `#__content_types` (
`type_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`type_title` varchar(255) NOT NULL DEFAULT '',
`type_alias` varchar(255) NOT NULL DEFAULT '',
`table` varchar(255) NOT NULL DEFAULT '',
`rules` text NOT NULL,
`field_mappings` text NOT NULL,
`router` varchar(255) NOT NULL DEFAULT '',

</source>

For each table/option/view you will need to make an entry in #__content_types. You can do this either using sql or postflight by creating an instance of JTableContenttype. Don't forget a category type if you use the Joomla categories API.

A string giving component.view (that would be in the page request, typically matching the model name) goes in the **type_alias** field.

'''table''' gives the complete table class information for the table class stored as a JSON object in which the first element represents your "special" table and the second an optional common table (otherwise it will default the JTableCorecontent. This includes the name of the database table, the name of the primary key, the prefix, the name, an option array as used in your constructor and getInstance() methods. This enables the tagging system (and other APIs) to access your table easily.

If you are using Joomla categories make sure to create a category type so that they can be tagged. In Joomla 3.1 and 3.1.1 there is an error where the tag field will show even if there is not a type, but this is corrected in 3.1.4.

'''Important note''' : Please note that the table name for the common table is #__ucm_content. This is INCORRECT in 3.1 and 3.1.1 data but is not currently used. The data was updated in 3.1.4.

<source lang="php">
{"special":{"dbtable":"#__content","key":"id","type":"Content","prefix":"JTable","config":"array()"},"common":{"dbtable":"#__ucm_content","key":"ucm_id","type":"Corecontent","prefix":"JTable","config":"array()"}}
</source>

The '''type_title''' field would potentially be used for display although this is not implemented currently except in the contentttype field. Usually it should begin with an upper case letter if it is in English. See note about how to make this translatable.

note:
To make your type names translatable add
<source lang="php">
COM_TAGS_CONTENT_TYPE_ + the type_title
</source>
in both the ini and sys.ini files.

'''Rules''' is currently not used. It will likely be removed in favor of an asset_id for each type, but currently you can ignore this field which will be managed by JTable.

'''field_mappings''' maps the names of specific fields in your table to a set of standard names. This mapping is stored as a JSON array with the first element mapping to the common fields and the second one mapping the other fields from the table.

'''Important note''' The JHelperTags and JUcm APIS at 3.1.1 supported arrays for this field, but as of 3.1.4 either arrays or objects with a default of objects are supported.

<source lang="php">
'{"common":[{"core_content_item_id":"id","core_title":"title","core_state":"published","core_alias":"alias","core_created_time":"created_time","core_modified_time":"modified_time","core_body":"description", "core_hits":"hits","core_publish_up":"null","core_publish_down":"null","core_access":"access", "core_params":"params", "core_featured":"null", "core_metadata":"metadata", "core_language":"language", "core_images":"null", "core_urls":"null", "core_version":"version", "core_ordering":"null", "core_metakey":"metakey", "core_metadesc":"metadesc", "core_catid":"parent_id", "core_xreference":"null", "asset_id":"asset_id"}], "special": [{"parent_id":"parent_id","lft":"lft","rgt":"rgt","level":"level","path":"path","extension":"extension","note":"note"}]}'
</source>

is the field mapping for the Article type. Note that article uses the name attribs for the core field called params. If your table does not contain a field, put “null” instead. Leaving it blank may cause SQL issues. The special fields are optional. At a minimum for common fields you need to map: content_item_id, alias and title in order to successfully create urls in the tagged items list. You also will probably want: access, status, and language.

'''Router''' is an optional name of a static helper router method for this type found in its front end helpers folder.
If you only store data in #__ucm_content you will eventually be able to leave the router field blank although this option is not currently implemented. If you do not have a custom router tags falls back to the rules found in JHelperRoute.

== Modify your component's table class (or classes if you have multiple tables) ==

This has several parts.

=== Add a property ===

<source lang="php">
/**
* Indicator that the tags have been changed
*
* @var JHelperTags
* @since 3.1
*/
protected $tagsHelper = null;
</source>
This property helps to manage change in tags.

=== Modify your constructor ===

Follow this example to modify your consructor which provides substantial reduction in duplicate code.
<source lang="php">
$this->tagsHelper = new JHelperTags();
$this->tagsHelper->typeAlias = 'com_contact.contact';
</source>

=== Modify your store() method ===
Note that this applies only to 3.1.0 and 3.1.1. This is not needed in 3.1.4 or later if other changes are followed. It is not necessary to remove this code from 3.1.0/3.1.1 style implementations.

Management of tagging and associated data is largely handled through the store() method. This provides maximum flexibility for the handling of tags across many extensions.

If you don't have a store() method you will need to add one. The assumption is that tables will inherit from JTable.

The handling involves preStoreProcess(), a call to the parent store() method, and then a postStoreProcess().

<source lang="php">
$this->tagsHelper->preStoreProcess($this);
$result = parent::store($updateNulls);

return $result && $this->tagsHelper->postStoreProcess($this);
</source>

It is important that this be in the correct order since completion of tag processing depends on having primary key data from the parent store() method.

Note that much of this code is designed to prevent storage in in #__ucm_content when items are not tagged. If you want to always store in #__ucm_content you should modify the handling appropriately.

=== Add or modify a delete() method ===

Note this is only needed in 3.1.0 and 3.1.1. It is no longer required in 3.1.4 or later.
The basic structure:

<source lang="php">
/**
* Method to delete a row from the database table by primary key value.
*
* @param integer $pk Primary key to delete.
*
* @return boolean True on success.
*
* @since 3.1
* @throws UnexpectedValueException
*/
public function delete($pk = null)
{
$result = parent::delete($pk);
return $result && $this->tagsHelper->deleteTagData($this, $pk);
}

</source>

This manages the deletion of all related data if a content item is deleted.

== Add tags to the getItem() method of the model ==

'''Note: this was only required in 3.1.0 and 3.1.1. It should not be used in 3.1.4 or later.'''

In the getItem() (or similar) method of your model add
<source lang="php">
// Load item tags
if (!empty($item->id))
{
$item->tags = new JHelperTags;
$item->tags->getTagIds($item->id, 'com_contact.contact');
$item->metadata['tags'] = $item->tags;
}
</source>
changing to your component and alias name, matching what is in the type table.and changing the name of id property to the name of your primary key.

== Add a tag field to edit screens ==
In any edit layouts where you want to allow tagging, you need to add the field to the xml and the appropriate layouts if necessary. The core layouts us a JLayout to manage this and the same layout by any extension.

Update: Note that in '''3.1.1 only''' there is special handling of this in the core. Tags in the edit screen '''MUST''' be part of a metadata <fields></fields> group. The core provides two JLayouts to help you manage standard layouts, one (details) for the metadata and one for the sidebar that includes the tabs.

<source lang="xml">
<field name="tags" type="tag"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field></source>

The field loads all the Javascript libraries required. You don't need to worry about that.

The field supports two modes:
* '''Nested tags mode.''' Hierarchical tag list. Doesn't support on the fly tag creation.
* '''AJAX mode.''' Tags are searched while user types (3 min. chars required to launch the AJAX search). Custom tags are added by pressing ENTER or COMMA keys. Tags show the global route/path. Example: <code>grandpa/parent/tag</code>

The field mode can be forced or use the com_tags setting <code>Tag field mode</code> to determine its mode. To set/force the field mode we have to add '''mode="ajax"''' or '''mode="nested"''' to the tag field definition.

Example of forced AJAX mode:

<source lang="xml">
<field name="tags" type="tag" mode="ajax"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>
</source>
The field also includes an attribute to allow/deny the user to enter custom values. Currently this only works in AJAX mode. The attribute has to be added to the field definition like **custom="allow"** or **custom="deny"**

Example field definition with custom tags denied:

<source lang="xml">
<field name="tags" type="tag" mode="ajax" custom="denied"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>

</source>
if it is not already there. Usually multiple should be true unless you have a specific reason for it not to be.
In the core components in administrator, the field is in the group shown on the right, below the language field.

Note: As of 3.1.2 if you wish to use the field to designate parent tags you must add parent="parent" to the xml definition of the field.

== Prepare the view ==
Add an appropriate version of this to your view.html.php file before loading the layout:

<source lang="php">
$item->tags = new JHelperTags;
$item->tags->getItemTags('com_newsfeeds.newsfeed.' , $this->item->id);
</source>

The first parameter should match a type in the types table. The second parameter is the primary key under which this record is stored in your table. This would be used in any display in any view where you want the tags associated with the item to display.

== Set up the display ==

In any layout where you want to display the tags associated with an item add:
<source lang="php">
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>

</source>
Changing the object and property names as appropriate.

You will most likely want to add the show_tags parameter to the item parameters, the menu item parameters and component configuration as appropriate for your use case.

<source lang="php">
<?php if ($this->params->get('show_tags', 1) && !empty($this->item->tags)) : ?>
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>
<?php endif; ?></source>

== Batch processing ==
If you want to add the ability to do batch tagging to a backend list view do the following.

Add tag to the default_batch layout

<source lang="php">
<div class="control-group">
<div class="controls">
<?php echo JHtml::_('batch.tag');?>
</div>
</div></source>

And add tag to the button class in the modal footer (Not totally necessary at this point, but good for potential future changes e.g. if unTag is added.)

<source lang="php">
<button class="btn" type="button" onclick="document.id('batch-category-id').value='';document.id('batch-access').value='';document.id('batch-language-id').value='';document.id('batch-user-id').value='';document.id('batch-tag-id)').value=''" data-dismiss="modal">
</source>

=== Add a batch method to your model if you are not extending JModelAdmin or overriding the batch method. ===

<source lang="php">
/**
* Batch tag a list of item.
*
* @param integer $value The value of the new tag.
* @param array $pks An array of row IDs.
* @param array $contexts An array of item contexts.
*
* @return void.
*
* @since 3.1
*/
protected function batchTag($value, $pks, $contexts)
{
$tagsHelper = new JHelperTags();
$tagsHelper->tagItems($value, $pks, $contexts);

return true;
}
</source>

And modify your batch method by adding
<source lang="php">
if (!empty($commands['tag']))
{
if (!$this->batchTag($commands['tag'], $pks, $contexts))
{
return false;
}

$done = true;
}

</source>

Pay attention to any JSON encoded strings that you need special handling for in batch processing -- remember that you are saving a copy of the core fields and you need save to work as expected.

That’s it, now create some tags, tag some items and you are set.

[[Category:Development]][[Category:Content Tags]]
[[Category:Tutorials]]

J3.x:Using Tags in an Extension

2013-07-27T16:41:46Z

Elin: /* Modify your store() method */

Joomla's tagging system is used in all core content extensions and is designed to be be easy to integrate into other extensions that use standard Joomla design patterns.

Using tags in an extension is relatively straightforward but it requires small changes in a number of specific places.

== Create a content type for each view ==
Note: Types can be added using either sql or postflight by creating a JTableContenttype instance and adding a row.

First identify which tables contain data that will be tagged and what the name of the single item view displaying each of these tables. For example:
* #__contact_details is the table displayed in the view contact of component com_contact with table class ContactTableContact.
* #__weblinks is the table displayed in the view weblink of com_weblinks so WeblinksTableWeblink.

<source lang="sql">
CREATE TABLE IF NOT EXISTS `#__content_types` (
`type_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`type_title` varchar(255) NOT NULL DEFAULT '',
`type_alias` varchar(255) NOT NULL DEFAULT '',
`table` varchar(255) NOT NULL DEFAULT '',
`rules` text NOT NULL,
`field_mappings` text NOT NULL,
`router` varchar(255) NOT NULL DEFAULT '',

</source>

For each table/option/view you will need to make an entry in #__content_types. You can do this either using sql or postflight by creating an instance of JTableContenttype. Don't forget a category type if you use the Joomla categories API.

A string giving component.view (that would be in the page request, typically matching the model name) goes in the **type_alias** field.

'''table''' gives the complete table class information for the table class stored as a JSON object in which the first element represents your "special" table and the second an optional common table (otherwise it will default the JTableCorecontent. This includes the name of the database table, the name of the primary key, the prefix, the name, an option array as used in your constructor and getInstance() methods. This enables the tagging system (and other APIs) to access your table easily.

If you are using Joomla categories make sure to create a category type so that they can be tagged. In Joomla 3.1 and 3.1.1 there is an error where the tag field will show even if there is not a type, but this is corrected in 3.1.4.

'''Important note''' : Please note that the table name for the common table is #__ucm_content. This is INCORRECT in 3.1 and 3.1.1 data but is not currently used. The data was updated in 3.1.4.

<source lang="php">
{"special":{"dbtable":"#__content","key":"id","type":"Content","prefix":"JTable","config":"array()"},"common":{"dbtable":"#__ucm_content","key":"ucm_id","type":"Corecontent","prefix":"JTable","config":"array()"}}
</source>

The '''type_title''' field would potentially be used for display although this is not implemented currently except in the contentttype field. Usually it should begin with an upper case letter if it is in English. See note about how to make this translatable.

note:
To make your type names translatable add
<source lang="php">
COM_TAGS_CONTENT_TYPE_ + the type_title
</source>
in both the ini and sys.ini files.

'''Rules''' is currently not used. It will likely be removed in favor of an asset_id for each type, but currently you can ignore this field which will be managed by JTable.

'''field_mappings''' maps the names of specific fields in your table to a set of standard names. This mapping is stored as a JSON array with the first element mapping to the common fields and the second one mapping the other fields from the table.

'''Important note''' The JHelperTags and JUcm APIS at 3.1.1 supported arrays for this field, but as of 3.1.4 either arrays or objects with a default of objects are supported.

<source lang="php">
'{"common":[{"core_content_item_id":"id","core_title":"title","core_state":"published","core_alias":"alias","core_created_time":"created_time","core_modified_time":"modified_time","core_body":"description", "core_hits":"hits","core_publish_up":"null","core_publish_down":"null","core_access":"access", "core_params":"params", "core_featured":"null", "core_metadata":"metadata", "core_language":"language", "core_images":"null", "core_urls":"null", "core_version":"version", "core_ordering":"null", "core_metakey":"metakey", "core_metadesc":"metadesc", "core_catid":"parent_id", "core_xreference":"null", "asset_id":"asset_id"}], "special": [{"parent_id":"parent_id","lft":"lft","rgt":"rgt","level":"level","path":"path","extension":"extension","note":"note"}]}'
</source>

is the field mapping for the Article type. Note that article uses the name attribs for the core field called params. If your table does not contain a field, put “null” instead. Leaving it blank may cause SQL issues. The special fields are optional. At a minimum for common fields you need to map: content_item_id, alias and title in order to successfully create urls in the tagged items list. You also will probably want: access, status, and language.

'''Router''' is an optional name of a static helper router method for this type found in its front end helpers folder.
If you only store data in #__ucm_content you will eventually be able to leave the router field blank although this option is not currently implemented. If you do not have a custom router tags falls back to the rules found in JHelperRoute.

== Modify your component's table class (or classes if you have multiple tables) ==

This has several parts.

=== Add a property ===

<source lang="php">
/**
* Indicator that the tags have been changed
*
* @var JHelperTags
* @since 3.1
*/
protected $tagsHelper = null;
</source>
This property helps to manage change in tags.

=== Modify your constructor ===

Follow this example to modify your consructor which provides substantial reduction in duplicate code.
<source lang="php">
$this->tagsHelper = new JHelperTags();
$this->tagsHelper->typeAlias = 'com_contact.contact';
</source>

=== Modify your store() method ===
Note that this applies only to 3.1.0 and 3.1.1. This is not needed in 3.1.4 or later if other changes are followed. It is not necessary to remove this code from 3.1.0/3.1.1 style implementations.

Management of tagging and associated data is largely handled through the store() method. This provides maximum flexibility for the handling of tags across many extensions.

If you don't have a store() method you will need to add one. The assumption is that tables will inherit from JTable.

The handling involves preStoreProcess(), a call to the parent store() method, and then a postStoreProcess().

<source lang="php">
$this->tagsHelper->preStoreProcess($this);
$result = parent::store($updateNulls);

return $result && $this->tagsHelper->postStoreProcess($this);
</source>

It is important that this be in the correct order since completion of tag processing depends on having primary key data from the parent store() method.

Note that much of this code is designed to prevent storage in in #__ucm_content when items are not tagged. If you want to always store in #__ucm_content you should modify the handling appropriately.

=== Add or modify a delete() method ===

Note this is only needed in 3.1.0 and 3.1.1. It is no longer required in 3.1.4 or later.
The basic structure:

<source lang="php">
/**
* Method to delete a row from the database table by primary key value.
*
* @param integer $pk Primary key to delete.
*
* @return boolean True on success.
*
* @since 3.1
* @throws UnexpectedValueException
*/
public function delete($pk = null)
{
$result = parent::delete($pk);
return $result && $this->tagsHelper->deleteTagData($this, $pk);
}

</source>

This manages the deletion of all related data if a content item is deleted.

== Add tags to the getItem() method of the model ==

In the getItem() (or similar) method of your model add
<source lang="php">
// Load item tags
if (!empty($item->id))
{
$item->tags = new JHelperTags;
$item->tags->getTagIds($item->id, 'com_contact.contact');
$item->metadata['tags'] = $item->tags;
}
</source>
changing to your component and alias name, matching what is in the type table.and changing the name of id property to the name of your primary key.

Note: It is our intent to make the storage field a property so that alternative fields can be used.
Note: As of 3.1.2 use:
<source lang="php">
// Load item tags
if (!empty($item->id))
{
$item->tags = new JHelperTags;
$item->tags->getTagIds($item->id, 'com_contact.contact');
}
</source>

== Add a tag field to edit screens ==
In any edit layouts where you want to allow tagging, you need to add the field to the xml and the appropriate layouts if necessary. The core layouts us a JLayout to manage this and the same layout by any extension.

Update: Note that in '''3.1.1 only''' there is special handling of this in the core. Tags in the edit screen '''MUST''' be part of a metadata <fields></fields> group. The core provides two JLayouts to help you manage standard layouts, one (details) for the metadata and one for the sidebar that includes the tabs.

<source lang="xml">
<field name="tags" type="tag"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field></source>

The field loads all the Javascript libraries required. You don't need to worry about that.

The field supports two modes:
* '''Nested tags mode.''' Hierarchical tag list. Doesn't support on the fly tag creation.
* '''AJAX mode.''' Tags are searched while user types (3 min. chars required to launch the AJAX search). Custom tags are added by pressing ENTER or COMMA keys. Tags show the global route/path. Example: <code>grandpa/parent/tag</code>

The field mode can be forced or use the com_tags setting <code>Tag field mode</code> to determine its mode. To set/force the field mode we have to add '''mode="ajax"''' or '''mode="nested"''' to the tag field definition.

Example of forced AJAX mode:

<source lang="xml">
<field name="tags" type="tag" mode="ajax"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>
</source>
The field also includes an attribute to allow/deny the user to enter custom values. Currently this only works in AJAX mode. The attribute has to be added to the field definition like **custom="allow"** or **custom="deny"**

Example field definition with custom tags denied:

<source lang="xml">
<field name="tags" type="tag" mode="ajax" custom="denied"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>

</source>
if it is not already there. Usually multiple should be true unless you have a specific reason for it not to be.
In the core components in administrator, the field is in the group shown on the right, below the language field.

Note: As of 3.1.2 if you wish to use the field to designate parent tags you must add parent="parent" to the xml definition of the field.

== Prepare the view ==
Add an appropriate version of this to your view.html.php file before loading the layout:

<source lang="php">
$item->tags = new JHelperTags;
$item->tags->getItemTags('com_newsfeeds.newsfeed.' , $this->item->id);
</source>

The first parameter should match a type in the types table. The second parameter is the primary key under which this record is stored in your table. This would be used in any display in any view where you want the tags associated with the item to display.

== Set up the display ==

In any layout where you want to display the tags associated with an item add:
<source lang="php">
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>

</source>
Changing the object and property names as appropriate.

You will most likely want to add the show_tags parameter to the item parameters, the menu item parameters and component configuration as appropriate for your use case.

<source lang="php">
<?php if ($this->params->get('show_tags', 1) && !empty($this->item->tags)) : ?>
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>
<?php endif; ?></source>

== Batch processing ==
If you want to add the ability to do batch tagging to a backend list view do the following.

Add tag to the default_batch layout

<source lang="php">
<div class="control-group">
<div class="controls">
<?php echo JHtml::_('batch.tag');?>
</div>
</div></source>

And add tag to the button class in the modal footer (Not totally necessary at this point, but good for potential future changes e.g. if unTag is added.)

<source lang="php">
<button class="btn" type="button" onclick="document.id('batch-category-id').value='';document.id('batch-access').value='';document.id('batch-language-id').value='';document.id('batch-user-id').value='';document.id('batch-tag-id)').value=''" data-dismiss="modal">
</source>

=== Add a batch method to your model if you are not extending JModelAdmin or overriding the batch method. ===

<source lang="php">
/**
* Batch tag a list of item.
*
* @param integer $value The value of the new tag.
* @param array $pks An array of row IDs.
* @param array $contexts An array of item contexts.
*
* @return void.
*
* @since 3.1
*/
protected function batchTag($value, $pks, $contexts)
{
$tagsHelper = new JHelperTags();
$tagsHelper->tagItems($value, $pks, $contexts);

return true;
}
</source>

And modify your batch method by adding
<source lang="php">
if (!empty($commands['tag']))
{
if (!$this->batchTag($commands['tag'], $pks, $contexts))
{
return false;
}

$done = true;
}

</source>

Pay attention to any JSON encoded strings that you need special handling for in batch processing -- remember that you are saving a copy of the core fields and you need save to work as expected.

That’s it, now create some tags, tag some items and you are set.

[[Category:Development]][[Category:Content Tags]]
[[Category:Tutorials]]

J3.x:Using Tags in an Extension

2013-07-27T16:06:57Z

Elin: /* Add or modify a delete() method */

Joomla's tagging system is used in all core content extensions and is designed to be be easy to integrate into other extensions that use standard Joomla design patterns.

Using tags in an extension is relatively straightforward but it requires small changes in a number of specific places.

== Create a content type for each view ==
Note: Types can be added using either sql or postflight by creating a JTableContenttype instance and adding a row.

First identify which tables contain data that will be tagged and what the name of the single item view displaying each of these tables. For example:
* #__contact_details is the table displayed in the view contact of component com_contact with table class ContactTableContact.
* #__weblinks is the table displayed in the view weblink of com_weblinks so WeblinksTableWeblink.

<source lang="sql">
CREATE TABLE IF NOT EXISTS `#__content_types` (
`type_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`type_title` varchar(255) NOT NULL DEFAULT '',
`type_alias` varchar(255) NOT NULL DEFAULT '',
`table` varchar(255) NOT NULL DEFAULT '',
`rules` text NOT NULL,
`field_mappings` text NOT NULL,
`router` varchar(255) NOT NULL DEFAULT '',

</source>

For each table/option/view you will need to make an entry in #__content_types. You can do this either using sql or postflight by creating an instance of JTableContenttype. Don't forget a category type if you use the Joomla categories API.

A string giving component.view (that would be in the page request, typically matching the model name) goes in the **type_alias** field.

'''table''' gives the complete table class information for the table class stored as a JSON object in which the first element represents your "special" table and the second an optional common table (otherwise it will default the JTableCorecontent. This includes the name of the database table, the name of the primary key, the prefix, the name, an option array as used in your constructor and getInstance() methods. This enables the tagging system (and other APIs) to access your table easily.

If you are using Joomla categories make sure to create a category type so that they can be tagged. In Joomla 3.1 and 3.1.1 there is an error where the tag field will show even if there is not a type, but this is corrected in 3.1.4.

'''Important note''' : Please note that the table name for the common table is #__ucm_content. This is INCORRECT in 3.1 and 3.1.1 data but is not currently used. The data was updated in 3.1.4.

<source lang="php">
{"special":{"dbtable":"#__content","key":"id","type":"Content","prefix":"JTable","config":"array()"},"common":{"dbtable":"#__ucm_content","key":"ucm_id","type":"Corecontent","prefix":"JTable","config":"array()"}}
</source>

The '''type_title''' field would potentially be used for display although this is not implemented currently except in the contentttype field. Usually it should begin with an upper case letter if it is in English. See note about how to make this translatable.

note:
To make your type names translatable add
<source lang="php">
COM_TAGS_CONTENT_TYPE_ + the type_title
</source>
in both the ini and sys.ini files.

'''Rules''' is currently not used. It will likely be removed in favor of an asset_id for each type, but currently you can ignore this field which will be managed by JTable.

'''field_mappings''' maps the names of specific fields in your table to a set of standard names. This mapping is stored as a JSON array with the first element mapping to the common fields and the second one mapping the other fields from the table.

'''Important note''' The JHelperTags and JUcm APIS at 3.1.1 supported arrays for this field, but as of 3.1.4 either arrays or objects with a default of objects are supported.

<source lang="php">
'{"common":[{"core_content_item_id":"id","core_title":"title","core_state":"published","core_alias":"alias","core_created_time":"created_time","core_modified_time":"modified_time","core_body":"description", "core_hits":"hits","core_publish_up":"null","core_publish_down":"null","core_access":"access", "core_params":"params", "core_featured":"null", "core_metadata":"metadata", "core_language":"language", "core_images":"null", "core_urls":"null", "core_version":"version", "core_ordering":"null", "core_metakey":"metakey", "core_metadesc":"metadesc", "core_catid":"parent_id", "core_xreference":"null", "asset_id":"asset_id"}], "special": [{"parent_id":"parent_id","lft":"lft","rgt":"rgt","level":"level","path":"path","extension":"extension","note":"note"}]}'
</source>

is the field mapping for the Article type. Note that article uses the name attribs for the core field called params. If your table does not contain a field, put “null” instead. Leaving it blank may cause SQL issues. The special fields are optional. At a minimum for common fields you need to map: content_item_id, alias and title in order to successfully create urls in the tagged items list. You also will probably want: access, status, and language.

'''Router''' is an optional name of a static helper router method for this type found in its front end helpers folder.
If you only store data in #__ucm_content you will eventually be able to leave the router field blank although this option is not currently implemented. If you do not have a custom router tags falls back to the rules found in JHelperRoute.

== Modify your component's table class (or classes if you have multiple tables) ==

This has several parts.

=== Add a property ===

<source lang="php">
/**
* Indicator that the tags have been changed
*
* @var JHelperTags
* @since 3.1
*/
protected $tagsHelper = null;
</source>
This property helps to manage change in tags.

=== Modify your constructor ===

Follow this example to modify your consructor which provides substantial reduction in duplicate code.
<source lang="php">
$this->tagsHelper = new JHelperTags();
$this->tagsHelper->typeAlias = 'com_contact.contact';
</source>

=== Modify your store() method ===
Management of tagging and associated data is largely handled through the store() method. This provides maximum flexibility for the handling of tags across many extensions.

If you don't have a store() method you will need to add one. The assumption is that tables will inherit from JTable.

The handling involves preStoreProcess(), a call to the parent store() method, and then a postStoreProcess().

<source lang="php">
$this->tagsHelper->preStoreProcess($this);
$result = parent::store($updateNulls);

return $result && $this->tagsHelper->postStoreProcess($this);
</source>

It is important that this be in the correct order since completion of tag processing depends on having primary key data from the parent store() method.

Note that much of this code is designed to prevent storage in in #__ucm_content when items are not tagged. If you want to always store in #__ucm_content you should modify the handling appropriately.

=== Add or modify a delete() method ===

Note this is only needed in 3.1.0 and 3.1.1. It is no longer required in 3.1.4 or later.
The basic structure:

<source lang="php">
/**
* Method to delete a row from the database table by primary key value.
*
* @param integer $pk Primary key to delete.
*
* @return boolean True on success.
*
* @since 3.1
* @throws UnexpectedValueException
*/
public function delete($pk = null)
{
$result = parent::delete($pk);
return $result && $this->tagsHelper->deleteTagData($this, $pk);
}

</source>

This manages the deletion of all related data if a content item is deleted.

== Add tags to the getItem() method of the model ==

In the getItem() (or similar) method of your model add
<source lang="php">
// Load item tags
if (!empty($item->id))
{
$item->tags = new JHelperTags;
$item->tags->getTagIds($item->id, 'com_contact.contact');
$item->metadata['tags'] = $item->tags;
}
</source>
changing to your component and alias name, matching what is in the type table.and changing the name of id property to the name of your primary key.

Note: It is our intent to make the storage field a property so that alternative fields can be used.
Note: As of 3.1.2 use:
<source lang="php">
// Load item tags
if (!empty($item->id))
{
$item->tags = new JHelperTags;
$item->tags->getTagIds($item->id, 'com_contact.contact');
}
</source>

== Add a tag field to edit screens ==
In any edit layouts where you want to allow tagging, you need to add the field to the xml and the appropriate layouts if necessary. The core layouts us a JLayout to manage this and the same layout by any extension.

Update: Note that in '''3.1.1 only''' there is special handling of this in the core. Tags in the edit screen '''MUST''' be part of a metadata <fields></fields> group. The core provides two JLayouts to help you manage standard layouts, one (details) for the metadata and one for the sidebar that includes the tabs.

<source lang="xml">
<field name="tags" type="tag"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field></source>

The field loads all the Javascript libraries required. You don't need to worry about that.

The field supports two modes:
* '''Nested tags mode.''' Hierarchical tag list. Doesn't support on the fly tag creation.
* '''AJAX mode.''' Tags are searched while user types (3 min. chars required to launch the AJAX search). Custom tags are added by pressing ENTER or COMMA keys. Tags show the global route/path. Example: <code>grandpa/parent/tag</code>

The field mode can be forced or use the com_tags setting <code>Tag field mode</code> to determine its mode. To set/force the field mode we have to add '''mode="ajax"''' or '''mode="nested"''' to the tag field definition.

Example of forced AJAX mode:

<source lang="xml">
<field name="tags" type="tag" mode="ajax"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>
</source>
The field also includes an attribute to allow/deny the user to enter custom values. Currently this only works in AJAX mode. The attribute has to be added to the field definition like **custom="allow"** or **custom="deny"**

Example field definition with custom tags denied:

<source lang="xml">
<field name="tags" type="tag" mode="ajax" custom="denied"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>

</source>
if it is not already there. Usually multiple should be true unless you have a specific reason for it not to be.
In the core components in administrator, the field is in the group shown on the right, below the language field.

Note: As of 3.1.2 if you wish to use the field to designate parent tags you must add parent="parent" to the xml definition of the field.

== Prepare the view ==
Add an appropriate version of this to your view.html.php file before loading the layout:

<source lang="php">
$item->tags = new JHelperTags;
$item->tags->getItemTags('com_newsfeeds.newsfeed.' , $this->item->id);
</source>

The first parameter should match a type in the types table. The second parameter is the primary key under which this record is stored in your table. This would be used in any display in any view where you want the tags associated with the item to display.

== Set up the display ==

In any layout where you want to display the tags associated with an item add:
<source lang="php">
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>

</source>
Changing the object and property names as appropriate.

You will most likely want to add the show_tags parameter to the item parameters, the menu item parameters and component configuration as appropriate for your use case.

<source lang="php">
<?php if ($this->params->get('show_tags', 1) && !empty($this->item->tags)) : ?>
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>
<?php endif; ?></source>

== Batch processing ==
If you want to add the ability to do batch tagging to a backend list view do the following.

Add tag to the default_batch layout

<source lang="php">
<div class="control-group">
<div class="controls">
<?php echo JHtml::_('batch.tag');?>
</div>
</div></source>

And add tag to the button class in the modal footer (Not totally necessary at this point, but good for potential future changes e.g. if unTag is added.)

<source lang="php">
<button class="btn" type="button" onclick="document.id('batch-category-id').value='';document.id('batch-access').value='';document.id('batch-language-id').value='';document.id('batch-user-id').value='';document.id('batch-tag-id)').value=''" data-dismiss="modal">
</source>

=== Add a batch method to your model if you are not extending JModelAdmin or overriding the batch method. ===

<source lang="php">
/**
* Batch tag a list of item.
*
* @param integer $value The value of the new tag.
* @param array $pks An array of row IDs.
* @param array $contexts An array of item contexts.
*
* @return void.
*
* @since 3.1
*/
protected function batchTag($value, $pks, $contexts)
{
$tagsHelper = new JHelperTags();
$tagsHelper->tagItems($value, $pks, $contexts);

return true;
}
</source>

And modify your batch method by adding
<source lang="php">
if (!empty($commands['tag']))
{
if (!$this->batchTag($commands['tag'], $pks, $contexts))
{
return false;
}

$done = true;
}

</source>

Pay attention to any JSON encoded strings that you need special handling for in batch processing -- remember that you are saving a copy of the core fields and you need save to work as expected.

That’s it, now create some tags, tag some items and you are set.

[[Category:Development]][[Category:Content Tags]]
[[Category:Tutorials]]

J3.x:Using Tags in an Extension

2013-07-27T16:06:02Z

Elin:

Joomla's tagging system is used in all core content extensions and is designed to be be easy to integrate into other extensions that use standard Joomla design patterns.

Using tags in an extension is relatively straightforward but it requires small changes in a number of specific places.

== Create a content type for each view ==
Note: Types can be added using either sql or postflight by creating a JTableContenttype instance and adding a row.

First identify which tables contain data that will be tagged and what the name of the single item view displaying each of these tables. For example:
* #__contact_details is the table displayed in the view contact of component com_contact with table class ContactTableContact.
* #__weblinks is the table displayed in the view weblink of com_weblinks so WeblinksTableWeblink.

<source lang="sql">
CREATE TABLE IF NOT EXISTS `#__content_types` (
`type_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`type_title` varchar(255) NOT NULL DEFAULT '',
`type_alias` varchar(255) NOT NULL DEFAULT '',
`table` varchar(255) NOT NULL DEFAULT '',
`rules` text NOT NULL,
`field_mappings` text NOT NULL,
`router` varchar(255) NOT NULL DEFAULT '',

</source>

For each table/option/view you will need to make an entry in #__content_types. You can do this either using sql or postflight by creating an instance of JTableContenttype. Don't forget a category type if you use the Joomla categories API.

A string giving component.view (that would be in the page request, typically matching the model name) goes in the **type_alias** field.

'''table''' gives the complete table class information for the table class stored as a JSON object in which the first element represents your "special" table and the second an optional common table (otherwise it will default the JTableCorecontent. This includes the name of the database table, the name of the primary key, the prefix, the name, an option array as used in your constructor and getInstance() methods. This enables the tagging system (and other APIs) to access your table easily.

If you are using Joomla categories make sure to create a category type so that they can be tagged. In Joomla 3.1 and 3.1.1 there is an error where the tag field will show even if there is not a type, but this is corrected in 3.1.4.

'''Important note''' : Please note that the table name for the common table is #__ucm_content. This is INCORRECT in 3.1 and 3.1.1 data but is not currently used. The data was updated in 3.1.4.

<source lang="php">
{"special":{"dbtable":"#__content","key":"id","type":"Content","prefix":"JTable","config":"array()"},"common":{"dbtable":"#__ucm_content","key":"ucm_id","type":"Corecontent","prefix":"JTable","config":"array()"}}
</source>

The '''type_title''' field would potentially be used for display although this is not implemented currently except in the contentttype field. Usually it should begin with an upper case letter if it is in English. See note about how to make this translatable.

note:
To make your type names translatable add
<source lang="php">
COM_TAGS_CONTENT_TYPE_ + the type_title
</source>
in both the ini and sys.ini files.

'''Rules''' is currently not used. It will likely be removed in favor of an asset_id for each type, but currently you can ignore this field which will be managed by JTable.

'''field_mappings''' maps the names of specific fields in your table to a set of standard names. This mapping is stored as a JSON array with the first element mapping to the common fields and the second one mapping the other fields from the table.

'''Important note''' The JHelperTags and JUcm APIS at 3.1.1 supported arrays for this field, but as of 3.1.4 either arrays or objects with a default of objects are supported.

<source lang="php">
'{"common":[{"core_content_item_id":"id","core_title":"title","core_state":"published","core_alias":"alias","core_created_time":"created_time","core_modified_time":"modified_time","core_body":"description", "core_hits":"hits","core_publish_up":"null","core_publish_down":"null","core_access":"access", "core_params":"params", "core_featured":"null", "core_metadata":"metadata", "core_language":"language", "core_images":"null", "core_urls":"null", "core_version":"version", "core_ordering":"null", "core_metakey":"metakey", "core_metadesc":"metadesc", "core_catid":"parent_id", "core_xreference":"null", "asset_id":"asset_id"}], "special": [{"parent_id":"parent_id","lft":"lft","rgt":"rgt","level":"level","path":"path","extension":"extension","note":"note"}]}'
</source>

is the field mapping for the Article type. Note that article uses the name attribs for the core field called params. If your table does not contain a field, put “null” instead. Leaving it blank may cause SQL issues. The special fields are optional. At a minimum for common fields you need to map: content_item_id, alias and title in order to successfully create urls in the tagged items list. You also will probably want: access, status, and language.

'''Router''' is an optional name of a static helper router method for this type found in its front end helpers folder.
If you only store data in #__ucm_content you will eventually be able to leave the router field blank although this option is not currently implemented. If you do not have a custom router tags falls back to the rules found in JHelperRoute.

== Modify your component's table class (or classes if you have multiple tables) ==

This has several parts.

=== Add a property ===

<source lang="php">
/**
* Indicator that the tags have been changed
*
* @var JHelperTags
* @since 3.1
*/
protected $tagsHelper = null;
</source>
This property helps to manage change in tags.

=== Modify your constructor ===

Follow this example to modify your consructor which provides substantial reduction in duplicate code.
<source lang="php">
$this->tagsHelper = new JHelperTags();
$this->tagsHelper->typeAlias = 'com_contact.contact';
</source>

=== Modify your store() method ===
Management of tagging and associated data is largely handled through the store() method. This provides maximum flexibility for the handling of tags across many extensions.

If you don't have a store() method you will need to add one. The assumption is that tables will inherit from JTable.

The handling involves preStoreProcess(), a call to the parent store() method, and then a postStoreProcess().

<source lang="php">
$this->tagsHelper->preStoreProcess($this);
$result = parent::store($updateNulls);

return $result && $this->tagsHelper->postStoreProcess($this);
</source>

It is important that this be in the correct order since completion of tag processing depends on having primary key data from the parent store() method.

Note that much of this code is designed to prevent storage in in #__ucm_content when items are not tagged. If you want to always store in #__ucm_content you should modify the handling appropriately.

=== Add or modify a delete() method ===

The basic structure:

<source lang="php">
/**
* Method to delete a row from the database table by primary key value.
*
* @param integer $pk Primary key to delete.
*
* @return boolean True on success.
*
* @since 3.1
* @throws UnexpectedValueException
*/
public function delete($pk = null)
{
$result = parent::delete($pk);
return $result && $this->tagsHelper->deleteTagData($this, $pk);
}

</source>

This manages the deletion of all related data if a content item is deleted.

== Add tags to the getItem() method of the model ==

In the getItem() (or similar) method of your model add
<source lang="php">
// Load item tags
if (!empty($item->id))
{
$item->tags = new JHelperTags;
$item->tags->getTagIds($item->id, 'com_contact.contact');
$item->metadata['tags'] = $item->tags;
}
</source>
changing to your component and alias name, matching what is in the type table.and changing the name of id property to the name of your primary key.

Note: It is our intent to make the storage field a property so that alternative fields can be used.
Note: As of 3.1.2 use:
<source lang="php">
// Load item tags
if (!empty($item->id))
{
$item->tags = new JHelperTags;
$item->tags->getTagIds($item->id, 'com_contact.contact');
}
</source>

== Add a tag field to edit screens ==
In any edit layouts where you want to allow tagging, you need to add the field to the xml and the appropriate layouts if necessary. The core layouts us a JLayout to manage this and the same layout by any extension.

Update: Note that in '''3.1.1 only''' there is special handling of this in the core. Tags in the edit screen '''MUST''' be part of a metadata <fields></fields> group. The core provides two JLayouts to help you manage standard layouts, one (details) for the metadata and one for the sidebar that includes the tabs.

<source lang="xml">
<field name="tags" type="tag"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field></source>

The field loads all the Javascript libraries required. You don't need to worry about that.

The field supports two modes:
* '''Nested tags mode.''' Hierarchical tag list. Doesn't support on the fly tag creation.
* '''AJAX mode.''' Tags are searched while user types (3 min. chars required to launch the AJAX search). Custom tags are added by pressing ENTER or COMMA keys. Tags show the global route/path. Example: <code>grandpa/parent/tag</code>

The field mode can be forced or use the com_tags setting <code>Tag field mode</code> to determine its mode. To set/force the field mode we have to add '''mode="ajax"''' or '''mode="nested"''' to the tag field definition.

Example of forced AJAX mode:

<source lang="xml">
<field name="tags" type="tag" mode="ajax"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>
</source>
The field also includes an attribute to allow/deny the user to enter custom values. Currently this only works in AJAX mode. The attribute has to be added to the field definition like **custom="allow"** or **custom="deny"**

Example field definition with custom tags denied:

<source lang="xml">
<field name="tags" type="tag" mode="ajax" custom="denied"
label="JTAG" description="JTAG_DESC"
class="inputbox span12 small" multiple="true"
>
</field>

</source>
if it is not already there. Usually multiple should be true unless you have a specific reason for it not to be.
In the core components in administrator, the field is in the group shown on the right, below the language field.

Note: As of 3.1.2 if you wish to use the field to designate parent tags you must add parent="parent" to the xml definition of the field.

== Prepare the view ==
Add an appropriate version of this to your view.html.php file before loading the layout:

<source lang="php">
$item->tags = new JHelperTags;
$item->tags->getItemTags('com_newsfeeds.newsfeed.' , $this->item->id);
</source>

The first parameter should match a type in the types table. The second parameter is the primary key under which this record is stored in your table. This would be used in any display in any view where you want the tags associated with the item to display.

== Set up the display ==

In any layout where you want to display the tags associated with an item add:
<source lang="php">
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>

</source>
Changing the object and property names as appropriate.

You will most likely want to add the show_tags parameter to the item parameters, the menu item parameters and component configuration as appropriate for your use case.

<source lang="php">
<?php if ($this->params->get('show_tags', 1) && !empty($this->item->tags)) : ?>
<?php $this->item->tagLayout = new JLayoutFile('joomla.content.tags'); ?>
<?php echo $this->item->tagLayout->render($this->item->tags->itemTags); ?>
<?php endif; ?></source>

== Batch processing ==
If you want to add the ability to do batch tagging to a backend list view do the following.

Add tag to the default_batch layout

<source lang="php">
<div class="control-group">
<div class="controls">
<?php echo JHtml::_('batch.tag');?>
</div>
</div></source>

And add tag to the button class in the modal footer (Not totally necessary at this point, but good for potential future changes e.g. if unTag is added.)

<source lang="php">
<button class="btn" type="button" onclick="document.id('batch-category-id').value='';document.id('batch-access').value='';document.id('batch-language-id').value='';document.id('batch-user-id').value='';document.id('batch-tag-id)').value=''" data-dismiss="modal">
</source>

=== Add a batch method to your model if you are not extending JModelAdmin or overriding the batch method. ===

<source lang="php">
/**
* Batch tag a list of item.
*
* @param integer $value The value of the new tag.
* @param array $pks An array of row IDs.
* @param array $contexts An array of item contexts.
*
* @return void.
*
* @since 3.1
*/
protected function batchTag($value, $pks, $contexts)
{
$tagsHelper = new JHelperTags();
$tagsHelper->tagItems($value, $pks, $contexts);

return true;
}
</source>

And modify your batch method by adding
<source lang="php">
if (!empty($commands['tag']))
{
if (!$this->batchTag($commands['tag'], $pks, $contexts))
{
return false;
}

$done = true;
}

</source>

Pay attention to any JSON encoded strings that you need special handling for in batch processing -- remember that you are saving a copy of the core fields and you need save to work as expected.

That’s it, now create some tags, tag some items and you are set.

[[Category:Development]][[Category:Content Tags]]
[[Category:Tutorials]]

J3.x:Subcategories Not Showing

2013-07-27T00:07:50Z

Elin: Created page with "Why are subcategories not showing on drill downs? In some category vies subcategory information is not showing but they did prior to updating. This seems to be the case speci..."

Why are subcategories not showing on drill downs?

In some category vies subcategory information is not showing but they did prior to updating. This seems to be the case specifically when there is not a direct menu link to the category view displaying the subcategories.

To fix the display there are several options depending on your situation.

*Go to the menu link from which the drill down is reached. In that link change "Show Empty Subcategories" to "Show."
*Change the global com_content settings for "Show Empty Subcategories" to "Show."
*Make a direct menu link with the settings you want.
*Make a layout override to use in that context that manages the show_empty_categories parameter as you prefer it to be handled for that page.

[[Category:Version 3.1.4 FAQ]]

Joomla:Release procedure and checklist

2013-07-26T03:46:33Z

Elin: /* Pre-execution phase */

[[Category:Bug Squad]]
[[Category:Coordinators]]
[[Category:Development]]

This is a general checklist when a version of Joomla! is released. Keep in mind that a major release differs a lot from a [[Minor Release]] or even a [[Maintenance Release]]. The checklist here describes the steps that need to be done for (at least) [[Maintenance Release]] and [[Minor Release]].

== Release checklist ==

It depends on the [[Development Cycle]] when the checklist is triggered. A release can be done during every stage of the [[Development Cycle]], it does not matter if you release a beta or a stable version, this is a general checklist that can be used when releasing a new version of Joomla! The checklist starts when it's decided to release a version:

=== Preparation phase ===
# Communication pre-release: check with PLT on timing
# Communication pre-release: inform Bug Squad and LT's about timing
# Decision: when the above has positive result, set a date and time for release
# Communication pre-release: inform Global Moderators about upcoming release
# Communication pre-release: check availability and assign release tasks to JBS and PLT members
# 5 days prior to release: freeze trunk for language changes
# 2 days prior to release: freeze trunk for all changes, draft release notes to translation teams
# 1 day prior to release: build packages for testing
# Day of release: set project flags on Joomlacode, update web pages
# Announce on forum, announce to LT's

=== Pre-execution phase ===
# Apply latest translations (need to be delivered by translation work group).
# Create test package.
# Offer test package to testers: [[Bug Squad]] members, [[Development Team ]] members, translation members
# If problems are found during this stage, go back to fix the problem. Use the [[Joomla! Maintenance Procedures]] and repeat until tests are performed successfully.
# Draft the release notes on Joomla.org and post draft to the [http://forum.joomla.org/viewforum.php?f=54 private translation forum].
# Obtain any CVE numbers needed.
# Draft security notices as needed and leave unpublished on developer.joomla.org.

=== Execution phase ===
# Check for security fixes.
# Create release notes document on joomla.org and post copy to translation forum.
# Change version information (libraries/cms/version/version.php)
# Add entry in CHANGELOG.php file
# Update administrator/manifests/files/joomla.xml file for version number and date.
# Check joomla.sql file for version number in #__extensions table for Joomla CMS extension
#* mysql, sqlazure, postgres
# Make sure there is at least one .sql update file in the com_admin/sql/updates/<db> folders (to update the db schema).
# Update the build.php for the new version number.
# Check language/en-GB/en-GB.files_joomla.sys.ini file for version number (not needed for minor update).
# Enable install check.
# Tag release in git and commit to local github repo.
# Package build.
# Offer test package to testers: [[Bug Squad]] members, [[Development Team ]] members, translation members
# If problems are found during this stage, go back to fix the problem. Use the [[Joomla! Maintenance Procedures]] and repeat until tests are performed successfully.
# Add package to joomlacode.org
## Before the release is public, set the joomlacode package flags as follows: Visible=No, Public=No, Require Login=Yes.
## Set the Release flags as follows: Visible=Yes, Released=Yes.
## Once package is released, change the Package flags to Visible=Yes, Public=Yes, Require Login=No.
## Change the prior version package to Visible=No but leave the prior version release flags as they are.
# Update XML file on site for the new version number information.
## FTP connect to update1.joomla.org and Navigate to www/core
## Change version attribute in list.xml (don't add new line)
## Add new update element (copy from previous) with new version number and new downloadurl and link to new archive file
## Test auto update from prior version(s) (make sure XML files have been copied to the SDN on update.joomla.org first)
# Update Joomla.org Download article
# Publish security articles on developer site.
# Publish release announcement on Joomla.org
# Publish announcement on the forum
# Update download page
# Update Wiki: FAQ, Version history
# Email OSM list

===Post Release===
# Merge release branch to master
# Push release version tag to github
# Remove install checks and prepare for next release
## Update version.php
## Add com_admin .sql scripts
## Update joomla.xml
## Close security issues in security tracker

=== Finalization phase ===
# Push release changes from local to remote Github repo
## Security fixes (if any)
## Version tag
## Version changes (SQL files, version.php, joomla.xml)
## Install checks
# Update Github repo for new version development
## Remove install checks
## Update version in version.php, joomla.xml, SQL files, SQL update files

=== Pages to update ===
#Global:
#* [http://developer.joomla.org/development-status.html Development Status]

=== Sites to update ===
#PLT Owned sites
#* [http://ux.joomla.org JUX Site]
#* [http://developer.joomla.org Developer Site]
#* [http://help.joomla.org Help Site (old)]

=== Calculating Release Statistics ===
# Extract *all* issues from Tracker into spreadsheet. Make note of the date of the last release and the number of active issues at the time of the last release.
# Set a filter on the "Closed Date" column to be "after" "the day of the last release".
#* Calculate "Closed" count by aggregating status values for Closed, Duplicate Report, Known Issue, Not a bug, Not Joomla! Core, Unable to Confirm.
#* Calculate "Fixed in SVN" count by aggregating status values for Open and Information Required. (Note: this value is presented two times in the report.)
# Set a filter on the "Closed Date" column to be blanks:
#* Calculate "Open" count by aggregating status values for "Open" and "Information Required."
#* Calculate "Confirmed" count by aggregating status values for "Confirmed" and "In Progress."
#* Calculate "Pending" count by aggregating status values for "Pending" and "Ready to Commit."
# Calculate the "New Active Issues" by aggregating the "Open", "Confirmed" and "Pending" counts.
# Calculate the "net increase/decrease" by subtracting the "Last Release Active Issues" from the "New Active Issues."
# Count the "number of commits" by reviewing the CHANGELOG.php file and counting the documented commits.

===Alternative Method for Stats===
* Fixed in SVN: Create query with close date > date of prior release and status = Fixed in SVN.
* Commits: Count from CHANGELOG.php as indicated above.
* New Reports: Run query with all status codes and open date > date of prior release.
* Increase / decrease in active issues: See note below
* Closed: Run query with closed date > date of prior release and status code one of Closed, Duplicate Report, Known Issue, Not a bug, Not Joomla! Core, Unable to Confirm.
* Open at time of release: query of all issues with status = Open or Information Required
* Confirmed at time of release: query of all issues with status = Confirmed or In Progress
* Pending at time of release: query of all issues with status = Pending or Ready to Commit

====Increase/Decrease in Active Issues====
* Total active issues now = Open at time of release + Confirmed at time of release + Pending at time of release
* This number minus the total active as of prior release is the net increase or decrease

As a check, make sure the following formula works:
* Prior release total active issues + New Reports - (Closed + Fixed in SVN) should equal the Total Active Issues now.

J3.x:Updating from an existing version

2013-07-25T21:53:30Z

Elin: /* Update the #__extensions Table */

{{RightTOC}}
=Overview=
The recommended way to update installations of Joomla! is to use the Joomla Updater component found in the Components menu of your site Administrator.

==Back up your site==

==Browse to Components, Joomla Update==
[[File:Componentsmenu.PNG]]

If an update is available there will be a message indicating this and a button to press.

[[File:Updatewaitingj3.PNG]]

==Click on the "Install the Update" button and allow the update to run==

[[File:Updatesuccess3.PNG]]

== When it has completed you may need to refresh your screen or empty your browser cache to adjust for template CSS changes.==

Note: Joomla! will notify you on your administrator home page (control panel) when an update is needed, but it will not do the update for you. You need to press the button to start the update.

[[http://docs.joomla.org/J3.1:Detailed_instructions_for_updating_from_3.1.2_to_3.1.4| Special Instructions for Version 3.1.2 Upgrades]]

'''Recommnended Steps and actions:'''
It is recommended that you follow these steps when updating a production site:
# Back up your site before upgrading to a new version. That way, if something goes wrong during the upgrade process, you can easily restore your site to the earlier version.
# Review the release notes for the new version to be familiar with what was changed.
# Update using one of the recommended methods outlined in this document. These methods install the new program files, delete unneeded old program files, and update the database as needed for the new Joomla version.
# Clear your browser cache and check that the update was successful, using the steps outlined in the '''Checking Site''' tab.

=Method A - Update Method=
This is the easier way, also called ''One click update''

==Step 1: Make sure you have a current backup of your site==
In many cases, your host will make periodic site backups.

==Step 2a: Find and install updates==
# '''If your site is prior to 2.5.4, see Step 2b instead'''
# In the back end of your Joomla site, navigate to Components → Joomla Update.
# Click on Install the Update [[Image:Update-screenshot-20120618-01.png|frame|center]]
# '''IMPORTANT:''' This process will take a few minutes. Wait until the process completes and it tells you that you are already on the current release, similar to the screen shown below. [[Image:Update-screenshot-20120618-02.png|frame|center]]
# Congratulations! At this point, your site is updated.
'''Important:''' Clear your browser cache and check that your site is working correctly. See below Checking Your Site

==Step 2b: Find and install updates (Prior to updating 2.5.4)==
# In the back end of your Joomla site, navigate to Extensions → Extension Manager and open the Update tab.
# Click on the Purge Cache icon to clear out the cache.
# Click on the Find Updates icon in the toolbar. If there is an available update, the screen will list it, similar to the screen shown below. [[Image:Update-screenshot-20120124-01.png|frame|center]] Note that available upgrades for extensions used in the site will also show in the list.
# Select the update (using the checkbox) and click on the Update icon in the toolbar.
# '''IMPORTANT:''' This process will take a few minutes. Wait until the process completes and the success message shows, similar to the screen shown below. [[Image:Update-screenshot-20120124-02.png|frame|center]]
# Congratulations! At this point, your site is updated.
'''Important:''' Clear your browser cache and check that your site is working correctly. See below Checking Your Site

=Method B - Install Method=
In some cases it may not be possible to use the Extension Manager: Update method to update your site. One reason for this might be that you are using a non-standard distribution (for example, a distribution with a different default language installed). Another reason might be that your don't have a reliable enough internet connection to support automatic installation.

In this case, you can still do an easy installation using the Extension Manager: Install screen. Like the Update screen, this method will do the database updates automatically and will completely update your system without any further steps.

==Step 1: Make sure you have a current backup of your site==
In many cases, your host will make periodic site backups.

==Step 2: Locate the update file==
Locate the required archive file (for example, .zip, .tag.gz, or tar.bz2 archive) for your version. If you are updating to an x.x.0 release (for example, from 1.7.3 to 2.5.0), this will normally be a file like Joomla_2.5.0-Stable-Update_Package.zip. If you are updating within the same release series (for example, 2.5.0 to 2.5.1), then the file will be named something like Joomla_2.5.0_to_2.5.1-Stable-Patch_Package.zip.

At this point, you have three options:
# Install from URL
# Install from Directory
# Upload Package File

Install from URL is the easiest to do. With this option, the upgrade archive is loaded directly by the server, so it works well even if your local computer has a slow or unreliable internet connection.

Install from Directory is the safest method if the server itself has a slow internet connection. With this method, you use FTP to load the unpacked update files into a temporary folder on the server. Then you point to that directory on the server for the installation.

Upload Package File is fairly simple, but it requires that you have a good connection between your local computer and the server.

The screen below shows the Extension Manager: Install screen with the three options labeled.
[[Image:Update-screenshot-20120124-03.png|frame|center]]

===Install from URL===
This option is the easiest, if the archive file is available on a website.
# In the Extension Manager: Install screen, enter the URL for the archive file in the Install URL field.
# Press the Install button.
The system will work for a period of time, up to two minutes or more for a full version update. Then a message indicating a successful installation will display.

===Install from Directory===
This option requires that you unpack the archive file in a directory on your server. This is the best method if you have a slow internet connection or you are experiencing timeouts during the update process.
# Unpack the archive file in a temporary directory on your local machine.
# Upload all the files in this directory (for example, using FTP) to a temporary directory that is visible to the web server. For example, you can create a sub-directory under the tmp directory in your Joomla root. For this example, let's say the directory on the server is <code>/home/myuser/myjoomla/tmp/upgrade250</code>).
# In the Extension Manager: Install screen, enter the full path of the temporary directory (on the server) from step 2 (for example, <code>/home/myuser/myjoomla/tmp/upgrade250</code>).
# Press the Install button.
The system will work for a short time (perhaps a minute or less, depending on your server). Then a message indicating a successful installation will display.

===Upload Package File===
This option requires that you first download the archive file to your local machine.
# Download the file to your local computer.
# In the Extension Manager: Install screen, click the Browse button next to the Package File field and browse to the archive file.
# Press the Install button.
The system will work for a period of time, up to two minutes or more for a full version update. Then a message indicating a successful installation will display.

# Congratulations! At this point, your site is updated.
'''Important:''' Clear your browser cache and check that your site is working correctly. See below Checking Your Site

=Method C - Manual Upgrade=
This method is similar to the old method for updating Joomla versions. Here we want to replace the existing program files with the files from the update archive. The advantage of this method is that it will work on slower shared hosts. The disadvantage is that it requires more work by the system administrator.

''Important: This method can also be used to repair a site where the automatic update failed due to a server timeout.''

==Copy the New Program Files to Your Site==
There are two ways you can do this.
# Copy the archive file to the root directory of your site and unpack the archive. The update archive will be named something like <code>Joomla_2.5.0-Stable-Update_Package.zip</code>. Note that you need to tell the system to replace any existing files. For example, in GoDaddy.com, use the FTP File Manager to upload the update file and then use "Unarchive" to unpack it. Check the box "Overwrite existing files".
# If you don't have the ability to unpack the archive on the server, create a temporary directory on your local machine and unpack the archive file there. Then FTP these files to the root directory of your site, overwriting the existing files.

==Update the Database==
At this point, you should be able to log into the back end of your site with the new version installed. However, you are not done. Navigate to Extension Manager: Database. You will initially have Database problems when you check the Database, similar to the screen below.
[[Image:Update-screenshot-20120124-08.png|frame|center|Database Screen Before Fix]]
This is expected. Click on the Fix icon to correct the problems. Now the screen should show that the database is up to date.

==Install New Extensions==
Navigate to Extension Manager: Discover and click on the Discover icon in the toolbar. If the updated version has new core extensions, new extensions will be listed, as shown below.
[[Image:Update-screenshot-20120124-09.png|frame|center|Discover Screen Before Install]]
Select all the extensions and click on the Install icon in the toolbar. The system should display a success message similar to the screen below.
[[Image:Update-screenshot-20120124-10.png|frame|center|Discover Screen After Install]]

==Update the #__extensions Table==
At this point, your site is updated. However, there is one more thing to do. The site will think it needs to be updated because a value in the #__extensions table is wrong. To fix this:
* Using phpMyAdmin or a similar tool, edit the row of the #__extensions table where the id column is '700'. (Note that the table prefix will be different in your site. For example, if your table prefix is "jos_", then the table will be called "jos_extensions".
* In the manifest_cache column, you will see the old version in the text (for example, <code>"version":"1.7.3"</code>). Change this to the new version (for example, <code>"version":"3.1.4"</code>). Be careful to not change anything else in this column.
* To check that this was successful, navigate to Extension Manager: Update and click Check for Updates. You should '''not''' see the current Joomla version in the list.

At this point, your site should be updated correctly.

=Checking Site=
'''This is required for method A and B!'''
After an update, it is a good idea to clear your browser cache snd check your site to make sure the update was successful. There are two quick checks you can do from the Extension Manager.
==Extension Manager: Check Database==
{{JVer|2.5}} This feature was added in version 2.5.0. It checks that your database is up to date with your Joomla programs.

Navigate to Extension Manager: Database. If your database is up to date, you should see a screen similar to the one below:
[[Image:Update-screenshot-20120124-04.png|frame|center|Database Screen With No Problems]]

If your database is not up to date, you will see a screen listing the problems found, similar to the one below:
[[Image:Update-screenshot-20120124-05.png|frame|center|Database Screen With 3 Database Problems]]
In this case, press the Fix button in the upper right corner. Joomla will update your database to correct the issues listed and then it will re-display the screen. If the fix was successful, the display will indicate that the database is up to date.

'''N.B.''' If any errors fail to fix then make sure all the database Tables are checked in.

==Extension Manager: Discover==
In some cases, when you update to a new Joomla version, new core extensions are added. If there were problems with the database update, these extensions may not have been correctly installed. To check this, navigate to Extension Manager: Discover. Then click on the Discover icon in the toolbar. The screen should show as follows:
[[Image:Update-screenshot-20120124-06.png|frame|center|Discover Screen With No Extensions To Install]]
If so, you know that any new extensions added during the udpate were correctly installed in the database.

If there are uninstalled extensions, they will show similar to the following screen:
[[Image:Update-screenshot-20120124-07.png|frame|center|Discover Screen With Two Extensions To Install]]
In this case, check the check boxes and click on the Install icon in the toolbar. Joomla will install the extension(s) and then display the screen showing no extensions discovered. At this point, the new extensions have been installed in the database.

=Troubleshooting=
If you have any questions before, during, or after the upgrade then please ask them on the [http://forum.joomla.org/viewforum.php?f=625&sid=259a29d8e21242b6770f86026f6c9c3a Joomla! 1.6 Migrating and Upgrading Forum].

If you have problems or errors during the update process, here are some tips.
* Clear your browser cache as there may have been changes to the css or javascript that will need to be reloaded by your web browser.
* If any database error messages show after the update, be sure to check the Extension Manager: Database tab followed by the Extension Manager: Discover tab. In some cases, if a database error occurs it will prevent all the database updates from running. In this case, you can run them from the Database tab and then use the Discover→Install method to check and install any new extensions.
* If you encounter any errors or problems during or after the update, be sure to check the FAQ for the version you updated to. For example, for version 2.5.0, this will be an article entitled [http://docs.joomla.org/Category:Version_2.5.0_FAQ http://docs.joomla.org/Category:Version_3.0_FAQ].

<headertabs/>
[[Category:Upgrading]]
[[Category:Joomla! 3.0]][[Category:Joomla! 3.1]]

J3.x:Updating from an existing version

2013-07-25T21:50:41Z

Elin: /* When it has completed you may need to refresh your screen or empty your browser cache to adjust for template CSS changes. */

{{RightTOC}}
=Overview=
The recommended way to update installations of Joomla! is to use the Joomla Updater component found in the Components menu of your site Administrator.

==Back up your site==

==Browse to Components, Joomla Update==
[[File:Componentsmenu.PNG]]

If an update is available there will be a message indicating this and a button to press.

[[File:Updatewaitingj3.PNG]]

==Click on the "Install the Update" button and allow the update to run==

[[File:Updatesuccess3.PNG]]

== When it has completed you may need to refresh your screen or empty your browser cache to adjust for template CSS changes.==

Note: Joomla! will notify you on your administrator home page (control panel) when an update is needed, but it will not do the update for you. You need to press the button to start the update.

[[http://docs.joomla.org/J3.1:Detailed_instructions_for_updating_from_3.1.2_to_3.1.4| Special Instructions for Version 3.1.2 Upgrades]]

'''Recommnended Steps and actions:'''
It is recommended that you follow these steps when updating a production site:
# Back up your site before upgrading to a new version. That way, if something goes wrong during the upgrade process, you can easily restore your site to the earlier version.
# Review the release notes for the new version to be familiar with what was changed.
# Update using one of the recommended methods outlined in this document. These methods install the new program files, delete unneeded old program files, and update the database as needed for the new Joomla version.
# Clear your browser cache and check that the update was successful, using the steps outlined in the '''Checking Site''' tab.

=Method A - Update Method=
This is the easier way, also called ''One click update''

==Step 1: Make sure you have a current backup of your site==
In many cases, your host will make periodic site backups.

==Step 2a: Find and install updates==
# '''If your site is prior to 2.5.4, see Step 2b instead'''
# In the back end of your Joomla site, navigate to Components → Joomla Update.
# Click on Install the Update [[Image:Update-screenshot-20120618-01.png|frame|center]]
# '''IMPORTANT:''' This process will take a few minutes. Wait until the process completes and it tells you that you are already on the current release, similar to the screen shown below. [[Image:Update-screenshot-20120618-02.png|frame|center]]
# Congratulations! At this point, your site is updated.
'''Important:''' Clear your browser cache and check that your site is working correctly. See below Checking Your Site

==Step 2b: Find and install updates (Prior to updating 2.5.4)==
# In the back end of your Joomla site, navigate to Extensions → Extension Manager and open the Update tab.
# Click on the Purge Cache icon to clear out the cache.
# Click on the Find Updates icon in the toolbar. If there is an available update, the screen will list it, similar to the screen shown below. [[Image:Update-screenshot-20120124-01.png|frame|center]] Note that available upgrades for extensions used in the site will also show in the list.
# Select the update (using the checkbox) and click on the Update icon in the toolbar.
# '''IMPORTANT:''' This process will take a few minutes. Wait until the process completes and the success message shows, similar to the screen shown below. [[Image:Update-screenshot-20120124-02.png|frame|center]]
# Congratulations! At this point, your site is updated.
'''Important:''' Clear your browser cache and check that your site is working correctly. See below Checking Your Site

=Method B - Install Method=
In some cases it may not be possible to use the Extension Manager: Update method to update your site. One reason for this might be that you are using a non-standard distribution (for example, a distribution with a different default language installed). Another reason might be that your don't have a reliable enough internet connection to support automatic installation.

In this case, you can still do an easy installation using the Extension Manager: Install screen. Like the Update screen, this method will do the database updates automatically and will completely update your system without any further steps.

==Step 1: Make sure you have a current backup of your site==
In many cases, your host will make periodic site backups.

==Step 2: Locate the update file==
Locate the required archive file (for example, .zip, .tag.gz, or tar.bz2 archive) for your version. If you are updating to an x.x.0 release (for example, from 1.7.3 to 2.5.0), this will normally be a file like Joomla_2.5.0-Stable-Update_Package.zip. If you are updating within the same release series (for example, 2.5.0 to 2.5.1), then the file will be named something like Joomla_2.5.0_to_2.5.1-Stable-Patch_Package.zip.

At this point, you have three options:
# Install from URL
# Install from Directory
# Upload Package File

Install from URL is the easiest to do. With this option, the upgrade archive is loaded directly by the server, so it works well even if your local computer has a slow or unreliable internet connection.

Install from Directory is the safest method if the server itself has a slow internet connection. With this method, you use FTP to load the unpacked update files into a temporary folder on the server. Then you point to that directory on the server for the installation.

Upload Package File is fairly simple, but it requires that you have a good connection between your local computer and the server.

The screen below shows the Extension Manager: Install screen with the three options labeled.
[[Image:Update-screenshot-20120124-03.png|frame|center]]

===Install from URL===
This option is the easiest, if the archive file is available on a website.
# In the Extension Manager: Install screen, enter the URL for the archive file in the Install URL field.
# Press the Install button.
The system will work for a period of time, up to two minutes or more for a full version update. Then a message indicating a successful installation will display.

===Install from Directory===
This option requires that you unpack the archive file in a directory on your server. This is the best method if you have a slow internet connection or you are experiencing timeouts during the update process.
# Unpack the archive file in a temporary directory on your local machine.
# Upload all the files in this directory (for example, using FTP) to a temporary directory that is visible to the web server. For example, you can create a sub-directory under the tmp directory in your Joomla root. For this example, let's say the directory on the server is <code>/home/myuser/myjoomla/tmp/upgrade250</code>).
# In the Extension Manager: Install screen, enter the full path of the temporary directory (on the server) from step 2 (for example, <code>/home/myuser/myjoomla/tmp/upgrade250</code>).
# Press the Install button.
The system will work for a short time (perhaps a minute or less, depending on your server). Then a message indicating a successful installation will display.

===Upload Package File===
This option requires that you first download the archive file to your local machine.
# Download the file to your local computer.
# In the Extension Manager: Install screen, click the Browse button next to the Package File field and browse to the archive file.
# Press the Install button.
The system will work for a period of time, up to two minutes or more for a full version update. Then a message indicating a successful installation will display.

# Congratulations! At this point, your site is updated.
'''Important:''' Clear your browser cache and check that your site is working correctly. See below Checking Your Site

=Method C - Manual Upgrade=
This method is similar to the old method for updating Joomla versions. Here we want to replace the existing program files with the files from the update archive. The advantage of this method is that it will work on slower shared hosts. The disadvantage is that it requires more work by the system administrator.

''Important: This method can also be used to repair a site where the automatic update failed due to a server timeout.''

==Copy the New Program Files to Your Site==
There are two ways you can do this.
# Copy the archive file to the root directory of your site and unpack the archive. The update archive will be named something like <code>Joomla_2.5.0-Stable-Update_Package.zip</code>. Note that you need to tell the system to replace any existing files. For example, in GoDaddy.com, use the FTP File Manager to upload the update file and then use "Unarchive" to unpack it. Check the box "Overwrite existing files".
# If you don't have the ability to unpack the archive on the server, create a temporary directory on your local machine and unpack the archive file there. Then FTP these files to the root directory of your site, overwriting the existing files.

==Update the Database==
At this point, you should be able to log into the back end of your site with the new version installed. However, you are not done. Navigate to Extension Manager: Database. You will initially have Database problems when you check the Database, similar to the screen below.
[[Image:Update-screenshot-20120124-08.png|frame|center|Database Screen Before Fix]]
This is expected. Click on the Fix icon to correct the problems. Now the screen should show that the database is up to date.

==Install New Extensions==
Navigate to Extension Manager: Discover and click on the Discover icon in the toolbar. If the updated version has new core extensions, new extensions will be listed, as shown below.
[[Image:Update-screenshot-20120124-09.png|frame|center|Discover Screen Before Install]]
Select all the extensions and click on the Install icon in the toolbar. The system should display a success message similar to the screen below.
[[Image:Update-screenshot-20120124-10.png|frame|center|Discover Screen After Install]]

==Update the #__extensions Table==
At this point, your site is updated. However, there is one more thing to do. The site will think it needs to be updated because a value in the #__extensions table is wrong. To fix this:
* Using phpMyAdmin or a similar tool, edit the row of the #__extensions table where the id column is '700'. (Note that the table prefix will be different in your site. For example, if your table prefix is "jos_", then the table will be called "jos_extensions".
* In the manifest_cache column, you will see the old version in the text (for example, <code>"version":"1.7.3"</code>). Change this to the new version (for example, <code>"version":"2.5.0"</code>). Be careful to not change anything else in this column.
* To check that this was successful, navigate to Extension Manager: Update and click Check for Updates. You should '''not''' see the current Joomla version in the list.

At this point, your site should be updated correctly.

=Checking Site=
'''This is required for method A and B!'''
After an update, it is a good idea to clear your browser cache snd check your site to make sure the update was successful. There are two quick checks you can do from the Extension Manager.
==Extension Manager: Check Database==
{{JVer|2.5}} This feature was added in version 2.5.0. It checks that your database is up to date with your Joomla programs.

Navigate to Extension Manager: Database. If your database is up to date, you should see a screen similar to the one below:
[[Image:Update-screenshot-20120124-04.png|frame|center|Database Screen With No Problems]]

If your database is not up to date, you will see a screen listing the problems found, similar to the one below:
[[Image:Update-screenshot-20120124-05.png|frame|center|Database Screen With 3 Database Problems]]
In this case, press the Fix button in the upper right corner. Joomla will update your database to correct the issues listed and then it will re-display the screen. If the fix was successful, the display will indicate that the database is up to date.

'''N.B.''' If any errors fail to fix then make sure all the database Tables are checked in.

==Extension Manager: Discover==
In some cases, when you update to a new Joomla version, new core extensions are added. If there were problems with the database update, these extensions may not have been correctly installed. To check this, navigate to Extension Manager: Discover. Then click on the Discover icon in the toolbar. The screen should show as follows:
[[Image:Update-screenshot-20120124-06.png|frame|center|Discover Screen With No Extensions To Install]]
If so, you know that any new extensions added during the udpate were correctly installed in the database.

If there are uninstalled extensions, they will show similar to the following screen:
[[Image:Update-screenshot-20120124-07.png|frame|center|Discover Screen With Two Extensions To Install]]
In this case, check the check boxes and click on the Install icon in the toolbar. Joomla will install the extension(s) and then display the screen showing no extensions discovered. At this point, the new extensions have been installed in the database.

=Troubleshooting=
If you have any questions before, during, or after the upgrade then please ask them on the [http://forum.joomla.org/viewforum.php?f=625&sid=259a29d8e21242b6770f86026f6c9c3a Joomla! 1.6 Migrating and Upgrading Forum].

If you have problems or errors during the update process, here are some tips.
* Clear your browser cache as there may have been changes to the css or javascript that will need to be reloaded by your web browser.
* If any database error messages show after the update, be sure to check the Extension Manager: Database tab followed by the Extension Manager: Discover tab. In some cases, if a database error occurs it will prevent all the database updates from running. In this case, you can run them from the Database tab and then use the Discover→Install method to check and install any new extensions.
* If you encounter any errors or problems during or after the update, be sure to check the FAQ for the version you updated to. For example, for version 2.5.0, this will be an article entitled [http://docs.joomla.org/Category:Version_2.5.0_FAQ http://docs.joomla.org/Category:Version_3.0_FAQ].

<headertabs/>
[[Category:Upgrading]]
[[Category:Joomla! 3.0]][[Category:Joomla! 3.1]]

J3.x:Updating from an existing version

2013-07-25T21:14:49Z

Elin: /* Troubleshooting */

{{RightTOC}}
=Overview=
The recommended way to update installations of Joomla! is to use the Joomla Updater component found in the Components menu of your site Administrator.

==Back up your site==

==Browse to Components, Joomla Update==
[[File:Componentsmenu.PNG]]

If an update is available there will be a message indicating this and a button to press.

[[File:Updatewaitingj3.PNG]]

==Click on the "Install the Update" button and allow the update to run==

[[File:Updatesuccess3.PNG]]

== When it has completed you may need to refresh your screen or empty your browser cache to adjust for template CSS changes.==

Note: Joomla! will notify you on your administrator home page (control panel) when an update is needed, but it will not do the update for you. You need to press the button to start the update.

'''Recommned Steps and actions:'''
It is recommended that you follow these steps when updating a production site:
# Back up your site before upgrading to a new version. That way, if something goes wrong during the upgrade process, you can easily restore your site to the earlier version.
# Review the release notes for the new version to be familiar with what was changed.
# Update using one of the recommended methods outlined in this document. These methods install the new program files, delete unneeded old program files, and update the database as needed for the new Joomla version.
# Clear your browser cache and check that the update was successful, using the steps outlined in the '''Checking Site''' tab.

=Method A - Update Method=
This is the easier way, also called ''One click update''

==Step 1: Make sure you have a current backup of your site==
In many cases, your host will make periodic site backups.

==Step 2a: Find and install updates==
# '''If your site is prior to 2.5.4, see Step 2b instead'''
# In the back end of your Joomla site, navigate to Components → Joomla Update.
# Click on Install the Update [[Image:Update-screenshot-20120618-01.png|frame|center]]
# '''IMPORTANT:''' This process will take a few minutes. Wait until the process completes and it tells you that you are already on the current release, similar to the screen shown below. [[Image:Update-screenshot-20120618-02.png|frame|center]]
# Congratulations! At this point, your site is updated.
'''Important:''' Clear your browser cache and check that your site is working correctly. See below Checking Your Site

==Step 2b: Find and install updates (Prior to updating 2.5.4)==
# In the back end of your Joomla site, navigate to Extensions → Extension Manager and open the Update tab.
# Click on the Purge Cache icon to clear out the cache.
# Click on the Find Updates icon in the toolbar. If there is an available update, the screen will list it, similar to the screen shown below. [[Image:Update-screenshot-20120124-01.png|frame|center]] Note that available upgrades for extensions used in the site will also show in the list.
# Select the update (using the checkbox) and click on the Update icon in the toolbar.
# '''IMPORTANT:''' This process will take a few minutes. Wait until the process completes and the success message shows, similar to the screen shown below. [[Image:Update-screenshot-20120124-02.png|frame|center]]
# Congratulations! At this point, your site is updated.
'''Important:''' Clear your browser cache and check that your site is working correctly. See below Checking Your Site

=Method B - Install Method=
In some cases it may not be possible to use the Extension Manager: Update method to update your site. One reason for this might be that you are using a non-standard distribution (for example, a distribution with a different default language installed). Another reason might be that your don't have a reliable enough internet connection to support automatic installation.

In this case, you can still do an easy installation using the Extension Manager: Install screen. Like the Update screen, this method will do the database updates automatically and will completely update your system without any further steps.

==Step 1: Make sure you have a current backup of your site==
In many cases, your host will make periodic site backups.

==Step 2: Locate the update file==
Locate the required archive file (for example, .zip, .tag.gz, or tar.bz2 archive) for your version. If you are updating to an x.x.0 release (for example, from 1.7.3 to 2.5.0), this will normally be a file like Joomla_2.5.0-Stable-Update_Package.zip. If you are updating within the same release series (for example, 2.5.0 to 2.5.1), then the file will be named something like Joomla_2.5.0_to_2.5.1-Stable-Patch_Package.zip.

At this point, you have three options:
# Install from URL
# Install from Directory
# Upload Package File

Install from URL is the easiest to do. With this option, the upgrade archive is loaded directly by the server, so it works well even if your local computer has a slow or unreliable internet connection.

Install from Directory is the safest method if the server itself has a slow internet connection. With this method, you use FTP to load the unpacked update files into a temporary folder on the server. Then you point to that directory on the server for the installation.

Upload Package File is fairly simple, but it requires that you have a good connection between your local computer and the server.

The screen below shows the Extension Manager: Install screen with the three options labeled.
[[Image:Update-screenshot-20120124-03.png|frame|center]]

===Install from URL===
This option is the easiest, if the archive file is available on a website.
# In the Extension Manager: Install screen, enter the URL for the archive file in the Install URL field.
# Press the Install button.
The system will work for a period of time, up to two minutes or more for a full version update. Then a message indicating a successful installation will display.

===Install from Directory===
This option requires that you unpack the archive file in a directory on your server. This is the best method if you have a slow internet connection or you are experiencing timeouts during the update process.
# Unpack the archive file in a temporary directory on your local machine.
# Upload all the files in this directory (for example, using FTP) to a temporary directory that is visible to the web server. For example, you can create a sub-directory under the tmp directory in your Joomla root. For this example, let's say the directory on the server is <code>/home/myuser/myjoomla/tmp/upgrade250</code>).
# In the Extension Manager: Install screen, enter the full path of the temporary directory (on the server) from step 2 (for example, <code>/home/myuser/myjoomla/tmp/upgrade250</code>).
# Press the Install button.
The system will work for a short time (perhaps a minute or less, depending on your server). Then a message indicating a successful installation will display.

===Upload Package File===
This option requires that you first download the archive file to your local machine.
# Download the file to your local computer.
# In the Extension Manager: Install screen, click the Browse button next to the Package File field and browse to the archive file.
# Press the Install button.
The system will work for a period of time, up to two minutes or more for a full version update. Then a message indicating a successful installation will display.

# Congratulations! At this point, your site is updated.
'''Important:''' Clear your browser cache and check that your site is working correctly. See below Checking Your Site

=Method C - Manual Upgrade=
This method is similar to the old method for updating Joomla versions. Here we want to replace the existing program files with the files from the update archive. The advantage of this method is that it will work on slower shared hosts. The disadvantage is that it requires more work by the system administrator.

''Important: This method can also be used to repair a site where the automatic update failed due to a server timeout.''

==Copy the New Program Files to Your Site==
There are two ways you can do this.
# Copy the archive file to the root directory of your site and unpack the archive. The update archive will be named something like <code>Joomla_2.5.0-Stable-Update_Package.zip</code>. Note that you need to tell the system to replace any existing files. For example, in GoDaddy.com, use the FTP File Manager to upload the update file and then use "Unarchive" to unpack it. Check the box "Overwrite existing files".
# If you don't have the ability to unpack the archive on the server, create a temporary directory on your local machine and unpack the archive file there. Then FTP these files to the root directory of your site, overwriting the existing files.

==Update the Database==
At this point, you should be able to log into the back end of your site with the new version installed. However, you are not done. Navigate to Extension Manager: Database. You will initially have Database problems when you check the Database, similar to the screen below.
[[Image:Update-screenshot-20120124-08.png|frame|center|Database Screen Before Fix]]
This is expected. Click on the Fix icon to correct the problems. Now the screen should show that the database is up to date.

==Install New Extensions==
Navigate to Extension Manager: Discover and click on the Discover icon in the toolbar. If the updated version has new core extensions, new extensions will be listed, as shown below.
[[Image:Update-screenshot-20120124-09.png|frame|center|Discover Screen Before Install]]
Select all the extensions and click on the Install icon in the toolbar. The system should display a success message similar to the screen below.
[[Image:Update-screenshot-20120124-10.png|frame|center|Discover Screen After Install]]

==Update the #__extensions Table==
At this point, your site is updated. However, there is one more thing to do. The site will think it needs to be updated because a value in the #__extensions table is wrong. To fix this:
* Using phpMyAdmin or a similar tool, edit the row of the #__extensions table where the id column is '700'. (Note that the table prefix will be different in your site. For example, if your table prefix is "jos_", then the table will be called "jos_extensions".
* In the manifest_cache column, you will see the old version in the text (for example, <code>"version":"1.7.3"</code>). Change this to the new version (for example, <code>"version":"2.5.0"</code>). Be careful to not change anything else in this column.
* To check that this was successful, navigate to Extension Manager: Update and click Check for Updates. You should '''not''' see the current Joomla version in the list.

At this point, your site should be updated correctly.

=Checking Site=
'''This is required for method A and B!'''
After an update, it is a good idea to clear your browser cache snd check your site to make sure the update was successful. There are two quick checks you can do from the Extension Manager.
==Extension Manager: Check Database==
{{JVer|2.5}} This feature was added in version 2.5.0. It checks that your database is up to date with your Joomla programs.

Navigate to Extension Manager: Database. If your database is up to date, you should see a screen similar to the one below:
[[Image:Update-screenshot-20120124-04.png|frame|center|Database Screen With No Problems]]

If your database is not up to date, you will see a screen listing the problems found, similar to the one below:
[[Image:Update-screenshot-20120124-05.png|frame|center|Database Screen With 3 Database Problems]]
In this case, press the Fix button in the upper right corner. Joomla will update your database to correct the issues listed and then it will re-display the screen. If the fix was successful, the display will indicate that the database is up to date.

'''N.B.''' If any errors fail to fix then make sure all the database Tables are checked in.

==Extension Manager: Discover==
In some cases, when you update to a new Joomla version, new core extensions are added. If there were problems with the database update, these extensions may not have been correctly installed. To check this, navigate to Extension Manager: Discover. Then click on the Discover icon in the toolbar. The screen should show as follows:
[[Image:Update-screenshot-20120124-06.png|frame|center|Discover Screen With No Extensions To Install]]
If so, you know that any new extensions added during the udpate were correctly installed in the database.

If there are uninstalled extensions, they will show similar to the following screen:
[[Image:Update-screenshot-20120124-07.png|frame|center|Discover Screen With Two Extensions To Install]]
In this case, check the check boxes and click on the Install icon in the toolbar. Joomla will install the extension(s) and then display the screen showing no extensions discovered. At this point, the new extensions have been installed in the database.

=Troubleshooting=
If you have any questions before, during, or after the upgrade then please ask them on the [http://forum.joomla.org/viewforum.php?f=625&sid=259a29d8e21242b6770f86026f6c9c3a Joomla! 1.6 Migrating and Upgrading Forum].

If you have problems or errors during the update process, here are some tips.
* Clear your browser cache as there may have been changes to the css or javascript that will need to be reloaded by your web browser.
* If any database error messages show after the update, be sure to check the Extension Manager: Database tab followed by the Extension Manager: Discover tab. In some cases, if a database error occurs it will prevent all the database updates from running. In this case, you can run them from the Database tab and then use the Discover→Install method to check and install any new extensions.
* If you encounter any errors or problems during or after the update, be sure to check the FAQ for the version you updated to. For example, for version 2.5.0, this will be an article entitled [http://docs.joomla.org/Category:Version_2.5.0_FAQ http://docs.joomla.org/Category:Version_3.0_FAQ].

<headertabs/>
[[Category:Upgrading]]
[[Category:Joomla! 3.0]][[Category:Joomla! 3.1]]

J3.x:Updating from an existing version

2013-07-25T21:13:50Z

Elin: /* Trouble Shooting and Advanced Techniques */

{{RightTOC}}
=Overview=
The recommended way to update installations of Joomla! is to use the Joomla Updater component found in the Components menu of your site Administrator.

==Back up your site==

==Browse to Components, Joomla Update==
[[File:Componentsmenu.PNG]]

If an update is available there will be a message indicating this and a button to press.

[[File:Updatewaitingj3.PNG]]

==Click on the "Install the Update" button and allow the update to run==

[[File:Updatesuccess3.PNG]]

== When it has completed you may need to refresh your screen or empty your browser cache to adjust for template CSS changes.==

Note: Joomla! will notify you on your administrator home page (control panel) when an update is needed, but it will not do the update for you. You need to press the button to start the update.

'''Recommned Steps and actions:'''
It is recommended that you follow these steps when updating a production site:
# Back up your site before upgrading to a new version. That way, if something goes wrong during the upgrade process, you can easily restore your site to the earlier version.
# Review the release notes for the new version to be familiar with what was changed.
# Update using one of the recommended methods outlined in this document. These methods install the new program files, delete unneeded old program files, and update the database as needed for the new Joomla version.
# Clear your browser cache and check that the update was successful, using the steps outlined in the '''Checking Site''' tab.

=Method A - Update Method=
This is the easier way, also called ''One click update''

==Step 1: Make sure you have a current backup of your site==
In many cases, your host will make periodic site backups.

==Step 2a: Find and install updates==
# '''If your site is prior to 2.5.4, see Step 2b instead'''
# In the back end of your Joomla site, navigate to Components → Joomla Update.
# Click on Install the Update [[Image:Update-screenshot-20120618-01.png|frame|center]]
# '''IMPORTANT:''' This process will take a few minutes. Wait until the process completes and it tells you that you are already on the current release, similar to the screen shown below. [[Image:Update-screenshot-20120618-02.png|frame|center]]
# Congratulations! At this point, your site is updated.
'''Important:''' Clear your browser cache and check that your site is working correctly. See below Checking Your Site

==Step 2b: Find and install updates (Prior to updating 2.5.4)==
# In the back end of your Joomla site, navigate to Extensions → Extension Manager and open the Update tab.
# Click on the Purge Cache icon to clear out the cache.
# Click on the Find Updates icon in the toolbar. If there is an available update, the screen will list it, similar to the screen shown below. [[Image:Update-screenshot-20120124-01.png|frame|center]] Note that available upgrades for extensions used in the site will also show in the list.
# Select the update (using the checkbox) and click on the Update icon in the toolbar.
# '''IMPORTANT:''' This process will take a few minutes. Wait until the process completes and the success message shows, similar to the screen shown below. [[Image:Update-screenshot-20120124-02.png|frame|center]]
# Congratulations! At this point, your site is updated.
'''Important:''' Clear your browser cache and check that your site is working correctly. See below Checking Your Site

=Method B - Install Method=
In some cases it may not be possible to use the Extension Manager: Update method to update your site. One reason for this might be that you are using a non-standard distribution (for example, a distribution with a different default language installed). Another reason might be that your don't have a reliable enough internet connection to support automatic installation.

In this case, you can still do an easy installation using the Extension Manager: Install screen. Like the Update screen, this method will do the database updates automatically and will completely update your system without any further steps.

==Step 1: Make sure you have a current backup of your site==
In many cases, your host will make periodic site backups.

==Step 2: Locate the update file==
Locate the required archive file (for example, .zip, .tag.gz, or tar.bz2 archive) for your version. If you are updating to an x.x.0 release (for example, from 1.7.3 to 2.5.0), this will normally be a file like Joomla_2.5.0-Stable-Update_Package.zip. If you are updating within the same release series (for example, 2.5.0 to 2.5.1), then the file will be named something like Joomla_2.5.0_to_2.5.1-Stable-Patch_Package.zip.

At this point, you have three options:
# Install from URL
# Install from Directory
# Upload Package File

Install from URL is the easiest to do. With this option, the upgrade archive is loaded directly by the server, so it works well even if your local computer has a slow or unreliable internet connection.

Install from Directory is the safest method if the server itself has a slow internet connection. With this method, you use FTP to load the unpacked update files into a temporary folder on the server. Then you point to that directory on the server for the installation.

Upload Package File is fairly simple, but it requires that you have a good connection between your local computer and the server.

The screen below shows the Extension Manager: Install screen with the three options labeled.
[[Image:Update-screenshot-20120124-03.png|frame|center]]

===Install from URL===
This option is the easiest, if the archive file is available on a website.
# In the Extension Manager: Install screen, enter the URL for the archive file in the Install URL field.
# Press the Install button.
The system will work for a period of time, up to two minutes or more for a full version update. Then a message indicating a successful installation will display.

===Install from Directory===
This option requires that you unpack the archive file in a directory on your server. This is the best method if you have a slow internet connection or you are experiencing timeouts during the update process.
# Unpack the archive file in a temporary directory on your local machine.
# Upload all the files in this directory (for example, using FTP) to a temporary directory that is visible to the web server. For example, you can create a sub-directory under the tmp directory in your Joomla root. For this example, let's say the directory on the server is <code>/home/myuser/myjoomla/tmp/upgrade250</code>).
# In the Extension Manager: Install screen, enter the full path of the temporary directory (on the server) from step 2 (for example, <code>/home/myuser/myjoomla/tmp/upgrade250</code>).
# Press the Install button.
The system will work for a short time (perhaps a minute or less, depending on your server). Then a message indicating a successful installation will display.

===Upload Package File===
This option requires that you first download the archive file to your local machine.
# Download the file to your local computer.
# In the Extension Manager: Install screen, click the Browse button next to the Package File field and browse to the archive file.
# Press the Install button.
The system will work for a period of time, up to two minutes or more for a full version update. Then a message indicating a successful installation will display.

# Congratulations! At this point, your site is updated.
'''Important:''' Clear your browser cache and check that your site is working correctly. See below Checking Your Site

=Method C - Manual Upgrade=
This method is similar to the old method for updating Joomla versions. Here we want to replace the existing program files with the files from the update archive. The advantage of this method is that it will work on slower shared hosts. The disadvantage is that it requires more work by the system administrator.

''Important: This method can also be used to repair a site where the automatic update failed due to a server timeout.''

==Copy the New Program Files to Your Site==
There are two ways you can do this.
# Copy the archive file to the root directory of your site and unpack the archive. The update archive will be named something like <code>Joomla_2.5.0-Stable-Update_Package.zip</code>. Note that you need to tell the system to replace any existing files. For example, in GoDaddy.com, use the FTP File Manager to upload the update file and then use "Unarchive" to unpack it. Check the box "Overwrite existing files".
# If you don't have the ability to unpack the archive on the server, create a temporary directory on your local machine and unpack the archive file there. Then FTP these files to the root directory of your site, overwriting the existing files.

==Update the Database==
At this point, you should be able to log into the back end of your site with the new version installed. However, you are not done. Navigate to Extension Manager: Database. You will initially have Database problems when you check the Database, similar to the screen below.
[[Image:Update-screenshot-20120124-08.png|frame|center|Database Screen Before Fix]]
This is expected. Click on the Fix icon to correct the problems. Now the screen should show that the database is up to date.

==Install New Extensions==
Navigate to Extension Manager: Discover and click on the Discover icon in the toolbar. If the updated version has new core extensions, new extensions will be listed, as shown below.
[[Image:Update-screenshot-20120124-09.png|frame|center|Discover Screen Before Install]]
Select all the extensions and click on the Install icon in the toolbar. The system should display a success message similar to the screen below.
[[Image:Update-screenshot-20120124-10.png|frame|center|Discover Screen After Install]]

==Update the #__extensions Table==
At this point, your site is updated. However, there is one more thing to do. The site will think it needs to be updated because a value in the #__extensions table is wrong. To fix this:
* Using phpMyAdmin or a similar tool, edit the row of the #__extensions table where the id column is '700'. (Note that the table prefix will be different in your site. For example, if your table prefix is "jos_", then the table will be called "jos_extensions".
* In the manifest_cache column, you will see the old version in the text (for example, <code>"version":"1.7.3"</code>). Change this to the new version (for example, <code>"version":"2.5.0"</code>). Be careful to not change anything else in this column.
* To check that this was successful, navigate to Extension Manager: Update and click Check for Updates. You should '''not''' see the current Joomla version in the list.

At this point, your site should be updated correctly.

=Checking Site=
'''This is required for method A and B!'''
After an update, it is a good idea to clear your browser cache snd check your site to make sure the update was successful. There are two quick checks you can do from the Extension Manager.
==Extension Manager: Check Database==
{{JVer|2.5}} This feature was added in version 2.5.0. It checks that your database is up to date with your Joomla programs.

Navigate to Extension Manager: Database. If your database is up to date, you should see a screen similar to the one below:
[[Image:Update-screenshot-20120124-04.png|frame|center|Database Screen With No Problems]]

If your database is not up to date, you will see a screen listing the problems found, similar to the one below:
[[Image:Update-screenshot-20120124-05.png|frame|center|Database Screen With 3 Database Problems]]
In this case, press the Fix button in the upper right corner. Joomla will update your database to correct the issues listed and then it will re-display the screen. If the fix was successful, the display will indicate that the database is up to date.

'''N.B.''' If any errors fail to fix then make sure all the database Tables are checked in.

==Extension Manager: Discover==
In some cases, when you update to a new Joomla version, new core extensions are added. If there were problems with the database update, these extensions may not have been correctly installed. To check this, navigate to Extension Manager: Discover. Then click on the Discover icon in the toolbar. The screen should show as follows:
[[Image:Update-screenshot-20120124-06.png|frame|center|Discover Screen With No Extensions To Install]]
If so, you know that any new extensions added during the udpate were correctly installed in the database.

If there are uninstalled extensions, they will show similar to the following screen:
[[Image:Update-screenshot-20120124-07.png|frame|center|Discover Screen With Two Extensions To Install]]
In this case, check the check boxes and click on the Install icon in the toolbar. Joomla will install the extension(s) and then display the screen showing no extensions discovered. At this point, the new extensions have been installed in the database.

=Troubleshooting=
If you have any questions before, during, or after the upgrade then please ask them on the [http://forum.joomla.org/viewforum.php?f=625&sid=259a29d8e21242b6770f86026f6c9c3a Joomla! 1.6 Migrating and Upgrading Forum].

If you have problems or errors during the update process, here are some tips.
* Clear your browser cache as there may have been changes to the css or javascript that will need to be reloaded by your web browser.
* If any database error messages show after the update, be sure to check the Extension Manager: Database tab followed by the Extension Manager: Discover tab. In some cases, if a database error occurs it will prevent all the database updates from running. In this case, you can run them from the Database tab and then use the Discover→Install method to check and install any new extensions.
* If you encounter any errors or problems during or after the update, be sure to check the FAQ for the version you updated to. For example, for version 2.5.0, this will be an article entitled [http://docs.joomla.org/Category:Version_2.5.0_FAQ http://docs.joomla.org/Category:Version_2.5.0_FAQ].

<headertabs/>
[[Category:Upgrading]]
[[Category:Joomla! 3.0]][[Category:Joomla! 3.1]]

J3.x:Updating from an existing version

2013-07-25T21:13:08Z

Elin: /* Overview */

{{RightTOC}}
=Overview=
The recommended way to update installations of Joomla! is to use the Joomla Updater component found in the Components menu of your site Administrator.

==Back up your site==

==Browse to Components, Joomla Update==
[[File:Componentsmenu.PNG]]

If an update is available there will be a message indicating this and a button to press.

[[File:Updatewaitingj3.PNG]]

==Click on the "Install the Update" button and allow the update to run==

[[File:Updatesuccess3.PNG]]

== When it has completed you may need to refresh your screen or empty your browser cache to adjust for template CSS changes.==

Note: Joomla! will notify you on your administrator home page (control panel) when an update is needed, but it will not do the update for you. You need to press the button to start the update.

==Trouble Shooting and Advanced Techniques==
Starting with version 1.6, there are three ways to update your Joomla Website to versions 1.6, 1.7 or 2.5.
If you are in an older version that did not support one click updates or are on a server that does not allow such updates you should use one of these options.

* Extension Manager: Update
* Extension Manager: Install
* Manually Copy Program Files

Each of these is discussed below.

'''Steps and actions:'''
It is recommended that you follow these steps when updating a production site:
# Back up your site before upgrading to a new version. That way, if something goes wrong during the upgrade process, you can easily restore your site to the earlier version.
# Review the release notes for the new version to be familiar with what was changed.
# Update using one of the recommended methods outlined in this document. These methods install the new program files, delete unneeded old program files, and update the database as needed for the new Joomla version.
# Clear your browser cache and check that the update was successful, using the steps outlined in the '''Checking Site''' tab.

=Method A - Update Method=
This is the easier way, also called ''One click update''

==Step 1: Make sure you have a current backup of your site==
In many cases, your host will make periodic site backups.

==Step 2a: Find and install updates==
# '''If your site is prior to 2.5.4, see Step 2b instead'''
# In the back end of your Joomla site, navigate to Components → Joomla Update.
# Click on Install the Update [[Image:Update-screenshot-20120618-01.png|frame|center]]
# '''IMPORTANT:''' This process will take a few minutes. Wait until the process completes and it tells you that you are already on the current release, similar to the screen shown below. [[Image:Update-screenshot-20120618-02.png|frame|center]]
# Congratulations! At this point, your site is updated.
'''Important:''' Clear your browser cache and check that your site is working correctly. See below Checking Your Site

==Step 2b: Find and install updates (Prior to updating 2.5.4)==
# In the back end of your Joomla site, navigate to Extensions → Extension Manager and open the Update tab.
# Click on the Purge Cache icon to clear out the cache.
# Click on the Find Updates icon in the toolbar. If there is an available update, the screen will list it, similar to the screen shown below. [[Image:Update-screenshot-20120124-01.png|frame|center]] Note that available upgrades for extensions used in the site will also show in the list.
# Select the update (using the checkbox) and click on the Update icon in the toolbar.
# '''IMPORTANT:''' This process will take a few minutes. Wait until the process completes and the success message shows, similar to the screen shown below. [[Image:Update-screenshot-20120124-02.png|frame|center]]
# Congratulations! At this point, your site is updated.
'''Important:''' Clear your browser cache and check that your site is working correctly. See below Checking Your Site

=Method B - Install Method=
In some cases it may not be possible to use the Extension Manager: Update method to update your site. One reason for this might be that you are using a non-standard distribution (for example, a distribution with a different default language installed). Another reason might be that your don't have a reliable enough internet connection to support automatic installation.

In this case, you can still do an easy installation using the Extension Manager: Install screen. Like the Update screen, this method will do the database updates automatically and will completely update your system without any further steps.

==Step 1: Make sure you have a current backup of your site==
In many cases, your host will make periodic site backups.

==Step 2: Locate the update file==
Locate the required archive file (for example, .zip, .tag.gz, or tar.bz2 archive) for your version. If you are updating to an x.x.0 release (for example, from 1.7.3 to 2.5.0), this will normally be a file like Joomla_2.5.0-Stable-Update_Package.zip. If you are updating within the same release series (for example, 2.5.0 to 2.5.1), then the file will be named something like Joomla_2.5.0_to_2.5.1-Stable-Patch_Package.zip.

At this point, you have three options:
# Install from URL
# Install from Directory
# Upload Package File

Install from URL is the easiest to do. With this option, the upgrade archive is loaded directly by the server, so it works well even if your local computer has a slow or unreliable internet connection.

Install from Directory is the safest method if the server itself has a slow internet connection. With this method, you use FTP to load the unpacked update files into a temporary folder on the server. Then you point to that directory on the server for the installation.

Upload Package File is fairly simple, but it requires that you have a good connection between your local computer and the server.

The screen below shows the Extension Manager: Install screen with the three options labeled.
[[Image:Update-screenshot-20120124-03.png|frame|center]]

===Install from URL===
This option is the easiest, if the archive file is available on a website.
# In the Extension Manager: Install screen, enter the URL for the archive file in the Install URL field.
# Press the Install button.
The system will work for a period of time, up to two minutes or more for a full version update. Then a message indicating a successful installation will display.

===Install from Directory===
This option requires that you unpack the archive file in a directory on your server. This is the best method if you have a slow internet connection or you are experiencing timeouts during the update process.
# Unpack the archive file in a temporary directory on your local machine.
# Upload all the files in this directory (for example, using FTP) to a temporary directory that is visible to the web server. For example, you can create a sub-directory under the tmp directory in your Joomla root. For this example, let's say the directory on the server is <code>/home/myuser/myjoomla/tmp/upgrade250</code>).
# In the Extension Manager: Install screen, enter the full path of the temporary directory (on the server) from step 2 (for example, <code>/home/myuser/myjoomla/tmp/upgrade250</code>).
# Press the Install button.
The system will work for a short time (perhaps a minute or less, depending on your server). Then a message indicating a successful installation will display.

===Upload Package File===
This option requires that you first download the archive file to your local machine.
# Download the file to your local computer.
# In the Extension Manager: Install screen, click the Browse button next to the Package File field and browse to the archive file.
# Press the Install button.
The system will work for a period of time, up to two minutes or more for a full version update. Then a message indicating a successful installation will display.

# Congratulations! At this point, your site is updated.
'''Important:''' Clear your browser cache and check that your site is working correctly. See below Checking Your Site

=Method C - Manual Upgrade=
This method is similar to the old method for updating Joomla versions. Here we want to replace the existing program files with the files from the update archive. The advantage of this method is that it will work on slower shared hosts. The disadvantage is that it requires more work by the system administrator.

''Important: This method can also be used to repair a site where the automatic update failed due to a server timeout.''

==Copy the New Program Files to Your Site==
There are two ways you can do this.
# Copy the archive file to the root directory of your site and unpack the archive. The update archive will be named something like <code>Joomla_2.5.0-Stable-Update_Package.zip</code>. Note that you need to tell the system to replace any existing files. For example, in GoDaddy.com, use the FTP File Manager to upload the update file and then use "Unarchive" to unpack it. Check the box "Overwrite existing files".
# If you don't have the ability to unpack the archive on the server, create a temporary directory on your local machine and unpack the archive file there. Then FTP these files to the root directory of your site, overwriting the existing files.

==Update the Database==
At this point, you should be able to log into the back end of your site with the new version installed. However, you are not done. Navigate to Extension Manager: Database. You will initially have Database problems when you check the Database, similar to the screen below.
[[Image:Update-screenshot-20120124-08.png|frame|center|Database Screen Before Fix]]
This is expected. Click on the Fix icon to correct the problems. Now the screen should show that the database is up to date.

==Install New Extensions==
Navigate to Extension Manager: Discover and click on the Discover icon in the toolbar. If the updated version has new core extensions, new extensions will be listed, as shown below.
[[Image:Update-screenshot-20120124-09.png|frame|center|Discover Screen Before Install]]
Select all the extensions and click on the Install icon in the toolbar. The system should display a success message similar to the screen below.
[[Image:Update-screenshot-20120124-10.png|frame|center|Discover Screen After Install]]

==Update the #__extensions Table==
At this point, your site is updated. However, there is one more thing to do. The site will think it needs to be updated because a value in the #__extensions table is wrong. To fix this:
* Using phpMyAdmin or a similar tool, edit the row of the #__extensions table where the id column is '700'. (Note that the table prefix will be different in your site. For example, if your table prefix is "jos_", then the table will be called "jos_extensions".
* In the manifest_cache column, you will see the old version in the text (for example, <code>"version":"1.7.3"</code>). Change this to the new version (for example, <code>"version":"2.5.0"</code>). Be careful to not change anything else in this column.
* To check that this was successful, navigate to Extension Manager: Update and click Check for Updates. You should '''not''' see the current Joomla version in the list.

At this point, your site should be updated correctly.

=Checking Site=
'''This is required for method A and B!'''
After an update, it is a good idea to clear your browser cache snd check your site to make sure the update was successful. There are two quick checks you can do from the Extension Manager.
==Extension Manager: Check Database==
{{JVer|2.5}} This feature was added in version 2.5.0. It checks that your database is up to date with your Joomla programs.

Navigate to Extension Manager: Database. If your database is up to date, you should see a screen similar to the one below:
[[Image:Update-screenshot-20120124-04.png|frame|center|Database Screen With No Problems]]

If your database is not up to date, you will see a screen listing the problems found, similar to the one below:
[[Image:Update-screenshot-20120124-05.png|frame|center|Database Screen With 3 Database Problems]]
In this case, press the Fix button in the upper right corner. Joomla will update your database to correct the issues listed and then it will re-display the screen. If the fix was successful, the display will indicate that the database is up to date.

'''N.B.''' If any errors fail to fix then make sure all the database Tables are checked in.

==Extension Manager: Discover==
In some cases, when you update to a new Joomla version, new core extensions are added. If there were problems with the database update, these extensions may not have been correctly installed. To check this, navigate to Extension Manager: Discover. Then click on the Discover icon in the toolbar. The screen should show as follows:
[[Image:Update-screenshot-20120124-06.png|frame|center|Discover Screen With No Extensions To Install]]
If so, you know that any new extensions added during the udpate were correctly installed in the database.

If there are uninstalled extensions, they will show similar to the following screen:
[[Image:Update-screenshot-20120124-07.png|frame|center|Discover Screen With Two Extensions To Install]]
In this case, check the check boxes and click on the Install icon in the toolbar. Joomla will install the extension(s) and then display the screen showing no extensions discovered. At this point, the new extensions have been installed in the database.

=Troubleshooting=
If you have any questions before, during, or after the upgrade then please ask them on the [http://forum.joomla.org/viewforum.php?f=625&sid=259a29d8e21242b6770f86026f6c9c3a Joomla! 1.6 Migrating and Upgrading Forum].

If you have problems or errors during the update process, here are some tips.
* Clear your browser cache as there may have been changes to the css or javascript that will need to be reloaded by your web browser.
* If any database error messages show after the update, be sure to check the Extension Manager: Database tab followed by the Extension Manager: Discover tab. In some cases, if a database error occurs it will prevent all the database updates from running. In this case, you can run them from the Database tab and then use the Discover→Install method to check and install any new extensions.
* If you encounter any errors or problems during or after the update, be sure to check the FAQ for the version you updated to. For example, for version 2.5.0, this will be an article entitled [http://docs.joomla.org/Category:Version_2.5.0_FAQ http://docs.joomla.org/Category:Version_2.5.0_FAQ].

<headertabs/>
[[Category:Upgrading]]
[[Category:Joomla! 3.0]][[Category:Joomla! 3.1]]

J3.x:Updating from an existing version

2013-07-25T21:05:45Z

Elin: /* When it has completed you may need to refresh your screen or empty your browser cache to adjust for template CSS changes. */

{{RightTOC}}
=Overview=
The recommended way to update installations of Joomla! is to use the Joomla Updater component found in the Components menu of your site Administrator.

==Back up your site==

==Browse to Components, Joomla Update==
[[File:Componentsmenu.PNG]]

If an update is available there will be a message indicating this and a button to press.

[[File:Updatewaitingj3.PNG]]

==Click on the "Install the Update" button and allow the update to run==

[[File:Updatesuccess3.PNG]]

== When it has completed you may need to refresh your screen or empty your browser cache to adjust for template CSS changes.==

Note: Joomla! will notify you on your administrator home page (control panel) when an update is needed, but it will not do the update for you. You need to press the button to start the update.

==Trouble Shooting and Advanced Techniques==
Starting with version 1.6, there are three ways to update your Joomla Website to versions 1.6, 1.7 or 2.5.
If you are in an older version that did not support one click updates or are on a server that does not allow such updates you should use one of these options.

* Extension Manager: Update
* Extension Manager: Install
* Manually Copy Program Files

Each of these is discussed below.

==Upgrade from version earlier than 1.6.x to Joomla 1.7? ==
This page does not contain the instructions for migrating a Website from Joomla versions earlier than 1.6. See the [[J2.5:Migrating from Joomla 1.5 to Joomla 2.5|Migrating from Joomla 1.5 to Joomla 2.5]] page.

==Upgrade from version 1.6.x to Joomla 1.7? ==
Note: To upgrade from version 1.6.x to Joomla 1.7 please follow the [[Upgrade 1.6.5 to 1.7|Upgrade 1.6.5 to 1.7 guide]] before you upgrade to Joomla 2.5.

==Upgrade to Joomla 2.5 on shared hosts==
{{notice|<small>'''Important note as of 28 January 2012:''' ''On some shared host environments (GoDaddy.com and perhaps others), the normal Joomla update from 1.7 to 2.5 can intermittently fail with the error "Internal Server Error". In some cases, this can happen in the middle of the file transfer process and cause errors on the site. On GoDaddy.com, this appears to happen when the server is under a heavy load and the update takes longer than 2 minutes to complete.''
''Based on recent testing, sites on these slower shared hosts can safely be updated using a free third-party extension called [http://tinyurl.com/7d9odse Admin Tools]. If you are updating a site on a shared host, please consider using Admin Tools or else use the Manually Copy Program Files method outlined below.''
''If you have experienced an error during the update, there is a process for repairing the site.''</small>}}

'''Steps and actions:'''
It is recommended that you follow these steps when updating a production site:
# Back up your site before upgrading to a new version. That way, if something goes wrong during the upgrade process, you can easily restore your site to the earlier version.
# Review the release notes for the new version to be familiar with what was changed.
# Update using one of the recommended methods outlined in this document. These methods install the new program files, delete unneeded old program files, and update the database as needed for the new Joomla version.
# Clear your browser cache and check that the update was successful, using the steps outlined in the '''Checking Site''' tab.

=Method A - Update Method=
This is the easier way, also called ''One click update''

==Step 1: Make sure you have a current backup of your site==
In many cases, your host will make periodic site backups.

==Step 2a: Find and install updates==
# '''If your site is prior to 2.5.4, see Step 2b instead'''
# In the back end of your Joomla site, navigate to Components → Joomla Update.
# Click on Install the Update [[Image:Update-screenshot-20120618-01.png|frame|center]]
# '''IMPORTANT:''' This process will take a few minutes. Wait until the process completes and it tells you that you are already on the current release, similar to the screen shown below. [[Image:Update-screenshot-20120618-02.png|frame|center]]
# Congratulations! At this point, your site is updated.
'''Important:''' Clear your browser cache and check that your site is working correctly. See below Checking Your Site

==Step 2b: Find and install updates (Prior to updating 2.5.4)==
# In the back end of your Joomla site, navigate to Extensions → Extension Manager and open the Update tab.
# Click on the Purge Cache icon to clear out the cache.
# Click on the Find Updates icon in the toolbar. If there is an available update, the screen will list it, similar to the screen shown below. [[Image:Update-screenshot-20120124-01.png|frame|center]] Note that available upgrades for extensions used in the site will also show in the list.
# Select the update (using the checkbox) and click on the Update icon in the toolbar.
# '''IMPORTANT:''' This process will take a few minutes. Wait until the process completes and the success message shows, similar to the screen shown below. [[Image:Update-screenshot-20120124-02.png|frame|center]]
# Congratulations! At this point, your site is updated.
'''Important:''' Clear your browser cache and check that your site is working correctly. See below Checking Your Site

=Method B - Install Method=
In some cases it may not be possible to use the Extension Manager: Update method to update your site. One reason for this might be that you are using a non-standard distribution (for example, a distribution with a different default language installed). Another reason might be that your don't have a reliable enough internet connection to support automatic installation.

In this case, you can still do an easy installation using the Extension Manager: Install screen. Like the Update screen, this method will do the database updates automatically and will completely update your system without any further steps.

==Step 1: Make sure you have a current backup of your site==
In many cases, your host will make periodic site backups.

==Step 2: Locate the update file==
Locate the required archive file (for example, .zip, .tag.gz, or tar.bz2 archive) for your version. If you are updating to an x.x.0 release (for example, from 1.7.3 to 2.5.0), this will normally be a file like Joomla_2.5.0-Stable-Update_Package.zip. If you are updating within the same release series (for example, 2.5.0 to 2.5.1), then the file will be named something like Joomla_2.5.0_to_2.5.1-Stable-Patch_Package.zip.

At this point, you have three options:
# Install from URL
# Install from Directory
# Upload Package File

Install from URL is the easiest to do. With this option, the upgrade archive is loaded directly by the server, so it works well even if your local computer has a slow or unreliable internet connection.

Install from Directory is the safest method if the server itself has a slow internet connection. With this method, you use FTP to load the unpacked update files into a temporary folder on the server. Then you point to that directory on the server for the installation.

Upload Package File is fairly simple, but it requires that you have a good connection between your local computer and the server.

The screen below shows the Extension Manager: Install screen with the three options labeled.
[[Image:Update-screenshot-20120124-03.png|frame|center]]

===Install from URL===
This option is the easiest, if the archive file is available on a website.
# In the Extension Manager: Install screen, enter the URL for the archive file in the Install URL field.
# Press the Install button.
The system will work for a period of time, up to two minutes or more for a full version update. Then a message indicating a successful installation will display.

===Install from Directory===
This option requires that you unpack the archive file in a directory on your server. This is the best method if you have a slow internet connection or you are experiencing timeouts during the update process.
# Unpack the archive file in a temporary directory on your local machine.
# Upload all the files in this directory (for example, using FTP) to a temporary directory that is visible to the web server. For example, you can create a sub-directory under the tmp directory in your Joomla root. For this example, let's say the directory on the server is <code>/home/myuser/myjoomla/tmp/upgrade250</code>).
# In the Extension Manager: Install screen, enter the full path of the temporary directory (on the server) from step 2 (for example, <code>/home/myuser/myjoomla/tmp/upgrade250</code>).
# Press the Install button.
The system will work for a short time (perhaps a minute or less, depending on your server). Then a message indicating a successful installation will display.

===Upload Package File===
This option requires that you first download the archive file to your local machine.
# Download the file to your local computer.
# In the Extension Manager: Install screen, click the Browse button next to the Package File field and browse to the archive file.
# Press the Install button.
The system will work for a period of time, up to two minutes or more for a full version update. Then a message indicating a successful installation will display.

# Congratulations! At this point, your site is updated.
'''Important:''' Clear your browser cache and check that your site is working correctly. See below Checking Your Site

=Method C - Manual Upgrade=
This method is similar to the old method for updating Joomla versions. Here we want to replace the existing program files with the files from the update archive. The advantage of this method is that it will work on slower shared hosts. The disadvantage is that it requires more work by the system administrator.

''Important: This method can also be used to repair a site where the automatic update failed due to a server timeout.''

==Copy the New Program Files to Your Site==
There are two ways you can do this.
# Copy the archive file to the root directory of your site and unpack the archive. The update archive will be named something like <code>Joomla_2.5.0-Stable-Update_Package.zip</code>. Note that you need to tell the system to replace any existing files. For example, in GoDaddy.com, use the FTP File Manager to upload the update file and then use "Unarchive" to unpack it. Check the box "Overwrite existing files".
# If you don't have the ability to unpack the archive on the server, create a temporary directory on your local machine and unpack the archive file there. Then FTP these files to the root directory of your site, overwriting the existing files.

==Update the Database==
At this point, you should be able to log into the back end of your site with the new version installed. However, you are not done. Navigate to Extension Manager: Database. You will initially have Database problems when you check the Database, similar to the screen below.
[[Image:Update-screenshot-20120124-08.png|frame|center|Database Screen Before Fix]]
This is expected. Click on the Fix icon to correct the problems. Now the screen should show that the database is up to date.

==Install New Extensions==
Navigate to Extension Manager: Discover and click on the Discover icon in the toolbar. If the updated version has new core extensions, new extensions will be listed, as shown below.
[[Image:Update-screenshot-20120124-09.png|frame|center|Discover Screen Before Install]]
Select all the extensions and click on the Install icon in the toolbar. The system should display a success message similar to the screen below.
[[Image:Update-screenshot-20120124-10.png|frame|center|Discover Screen After Install]]

==Update the #__extensions Table==
At this point, your site is updated. However, there is one more thing to do. The site will think it needs to be updated because a value in the #__extensions table is wrong. To fix this:
* Using phpMyAdmin or a similar tool, edit the row of the #__extensions table where the id column is '700'. (Note that the table prefix will be different in your site. For example, if your table prefix is "jos_", then the table will be called "jos_extensions".
* In the manifest_cache column, you will see the old version in the text (for example, <code>"version":"1.7.3"</code>). Change this to the new version (for example, <code>"version":"2.5.0"</code>). Be careful to not change anything else in this column.
* To check that this was successful, navigate to Extension Manager: Update and click Check for Updates. You should '''not''' see the current Joomla version in the list.

At this point, your site should be updated correctly.

=Checking Site=
'''This is required for method A and B!'''
After an update, it is a good idea to clear your browser cache snd check your site to make sure the update was successful. There are two quick checks you can do from the Extension Manager.
==Extension Manager: Check Database==
{{JVer|2.5}} This feature was added in version 2.5.0. It checks that your database is up to date with your Joomla programs.

Navigate to Extension Manager: Database. If your database is up to date, you should see a screen similar to the one below:
[[Image:Update-screenshot-20120124-04.png|frame|center|Database Screen With No Problems]]

If your database is not up to date, you will see a screen listing the problems found, similar to the one below:
[[Image:Update-screenshot-20120124-05.png|frame|center|Database Screen With 3 Database Problems]]
In this case, press the Fix button in the upper right corner. Joomla will update your database to correct the issues listed and then it will re-display the screen. If the fix was successful, the display will indicate that the database is up to date.

'''N.B.''' If any errors fail to fix then make sure all the database Tables are checked in.

==Extension Manager: Discover==
In some cases, when you update to a new Joomla version, new core extensions are added. If there were problems with the database update, these extensions may not have been correctly installed. To check this, navigate to Extension Manager: Discover. Then click on the Discover icon in the toolbar. The screen should show as follows:
[[Image:Update-screenshot-20120124-06.png|frame|center|Discover Screen With No Extensions To Install]]
If so, you know that any new extensions added during the udpate were correctly installed in the database.

If there are uninstalled extensions, they will show similar to the following screen:
[[Image:Update-screenshot-20120124-07.png|frame|center|Discover Screen With Two Extensions To Install]]
In this case, check the check boxes and click on the Install icon in the toolbar. Joomla will install the extension(s) and then display the screen showing no extensions discovered. At this point, the new extensions have been installed in the database.

=Troubleshooting=
If you have any questions before, during, or after the upgrade then please ask them on the [http://forum.joomla.org/viewforum.php?f=625&sid=259a29d8e21242b6770f86026f6c9c3a Joomla! 1.6 Migrating and Upgrading Forum].

If you have problems or errors during the update process, here are some tips.
* Clear your browser cache as there may have been changes to the css or javascript that will need to be reloaded by your web browser.
* If any database error messages show after the update, be sure to check the Extension Manager: Database tab followed by the Extension Manager: Discover tab. In some cases, if a database error occurs it will prevent all the database updates from running. In this case, you can run them from the Database tab and then use the Discover→Install method to check and install any new extensions.
* If you encounter any errors or problems during or after the update, be sure to check the FAQ for the version you updated to. For example, for version 2.5.0, this will be an article entitled [http://docs.joomla.org/Category:Version_2.5.0_FAQ http://docs.joomla.org/Category:Version_2.5.0_FAQ].

<headertabs/>
[[Category:Upgrading]]
[[Category:Joomla! 3.0]][[Category:Joomla! 3.1]]

J3.x:Updating from an existing version

2013-07-25T21:04:15Z

Elin: /* Click on the "Install the Update" button and allow the update to run */

{{RightTOC}}
=Overview=
The recommended way to update installations of Joomla! is to use the Joomla Updater component found in the Components menu of your site Administrator.

==Back up your site==

==Browse to Components, Joomla Update==
[[File:Componentsmenu.PNG]]

If an update is available there will be a message indicating this and a button to press.

[[File:Updatewaitingj3.PNG]]

==Click on the "Install the Update" button and allow the update to run==

[[File:Updatesuccess3.PNG]]

== When it has completed you may need to refresh your screen or empty your browser cache to adjust for template CSS changes.==

Note: Joomla! will notify on your administrator home page (control panel) when an update is needed, but it will not do the update for you. You need to press the button to start the update.

==Trouble Shooting and Advanced Techniques==
Starting with version 1.6, there are three ways to update your Joomla Website to versions 1.6, 1.7 or 2.5.
If you are in an older version that did not support one click updates or are on a server that does not allow such updates you should use one of these options.

* Extension Manager: Update
* Extension Manager: Install
* Manually Copy Program Files

Each of these is discussed below.

==Upgrade from version earlier than 1.6.x to Joomla 1.7? ==
This page does not contain the instructions for migrating a Website from Joomla versions earlier than 1.6. See the [[J2.5:Migrating from Joomla 1.5 to Joomla 2.5|Migrating from Joomla 1.5 to Joomla 2.5]] page.

==Upgrade from version 1.6.x to Joomla 1.7? ==
Note: To upgrade from version 1.6.x to Joomla 1.7 please follow the [[Upgrade 1.6.5 to 1.7|Upgrade 1.6.5 to 1.7 guide]] before you upgrade to Joomla 2.5.

==Upgrade to Joomla 2.5 on shared hosts==
{{notice|<small>'''Important note as of 28 January 2012:''' ''On some shared host environments (GoDaddy.com and perhaps others), the normal Joomla update from 1.7 to 2.5 can intermittently fail with the error "Internal Server Error". In some cases, this can happen in the middle of the file transfer process and cause errors on the site. On GoDaddy.com, this appears to happen when the server is under a heavy load and the update takes longer than 2 minutes to complete.''
''Based on recent testing, sites on these slower shared hosts can safely be updated using a free third-party extension called [http://tinyurl.com/7d9odse Admin Tools]. If you are updating a site on a shared host, please consider using Admin Tools or else use the Manually Copy Program Files method outlined below.''
''If you have experienced an error during the update, there is a process for repairing the site.''</small>}}

'''Steps and actions:'''
It is recommended that you follow these steps when updating a production site:
# Back up your site before upgrading to a new version. That way, if something goes wrong during the upgrade process, you can easily restore your site to the earlier version.
# Review the release notes for the new version to be familiar with what was changed.
# Update using one of the recommended methods outlined in this document. These methods install the new program files, delete unneeded old program files, and update the database as needed for the new Joomla version.
# Clear your browser cache and check that the update was successful, using the steps outlined in the '''Checking Site''' tab.

=Method A - Update Method=
This is the easier way, also called ''One click update''

==Step 1: Make sure you have a current backup of your site==
In many cases, your host will make periodic site backups.

==Step 2a: Find and install updates==
# '''If your site is prior to 2.5.4, see Step 2b instead'''
# In the back end of your Joomla site, navigate to Components → Joomla Update.
# Click on Install the Update [[Image:Update-screenshot-20120618-01.png|frame|center]]
# '''IMPORTANT:''' This process will take a few minutes. Wait until the process completes and it tells you that you are already on the current release, similar to the screen shown below. [[Image:Update-screenshot-20120618-02.png|frame|center]]
# Congratulations! At this point, your site is updated.
'''Important:''' Clear your browser cache and check that your site is working correctly. See below Checking Your Site

==Step 2b: Find and install updates (Prior to updating 2.5.4)==
# In the back end of your Joomla site, navigate to Extensions → Extension Manager and open the Update tab.
# Click on the Purge Cache icon to clear out the cache.
# Click on the Find Updates icon in the toolbar. If there is an available update, the screen will list it, similar to the screen shown below. [[Image:Update-screenshot-20120124-01.png|frame|center]] Note that available upgrades for extensions used in the site will also show in the list.
# Select the update (using the checkbox) and click on the Update icon in the toolbar.
# '''IMPORTANT:''' This process will take a few minutes. Wait until the process completes and the success message shows, similar to the screen shown below. [[Image:Update-screenshot-20120124-02.png|frame|center]]
# Congratulations! At this point, your site is updated.
'''Important:''' Clear your browser cache and check that your site is working correctly. See below Checking Your Site

=Method B - Install Method=
In some cases it may not be possible to use the Extension Manager: Update method to update your site. One reason for this might be that you are using a non-standard distribution (for example, a distribution with a different default language installed). Another reason might be that your don't have a reliable enough internet connection to support automatic installation.

In this case, you can still do an easy installation using the Extension Manager: Install screen. Like the Update screen, this method will do the database updates automatically and will completely update your system without any further steps.

==Step 1: Make sure you have a current backup of your site==
In many cases, your host will make periodic site backups.

==Step 2: Locate the update file==
Locate the required archive file (for example, .zip, .tag.gz, or tar.bz2 archive) for your version. If you are updating to an x.x.0 release (for example, from 1.7.3 to 2.5.0), this will normally be a file like Joomla_2.5.0-Stable-Update_Package.zip. If you are updating within the same release series (for example, 2.5.0 to 2.5.1), then the file will be named something like Joomla_2.5.0_to_2.5.1-Stable-Patch_Package.zip.

At this point, you have three options:
# Install from URL
# Install from Directory
# Upload Package File

Install from URL is the easiest to do. With this option, the upgrade archive is loaded directly by the server, so it works well even if your local computer has a slow or unreliable internet connection.

Install from Directory is the safest method if the server itself has a slow internet connection. With this method, you use FTP to load the unpacked update files into a temporary folder on the server. Then you point to that directory on the server for the installation.

Upload Package File is fairly simple, but it requires that you have a good connection between your local computer and the server.

The screen below shows the Extension Manager: Install screen with the three options labeled.
[[Image:Update-screenshot-20120124-03.png|frame|center]]

===Install from URL===
This option is the easiest, if the archive file is available on a website.
# In the Extension Manager: Install screen, enter the URL for the archive file in the Install URL field.
# Press the Install button.
The system will work for a period of time, up to two minutes or more for a full version update. Then a message indicating a successful installation will display.

===Install from Directory===
This option requires that you unpack the archive file in a directory on your server. This is the best method if you have a slow internet connection or you are experiencing timeouts during the update process.
# Unpack the archive file in a temporary directory on your local machine.
# Upload all the files in this directory (for example, using FTP) to a temporary directory that is visible to the web server. For example, you can create a sub-directory under the tmp directory in your Joomla root. For this example, let's say the directory on the server is <code>/home/myuser/myjoomla/tmp/upgrade250</code>).
# In the Extension Manager: Install screen, enter the full path of the temporary directory (on the server) from step 2 (for example, <code>/home/myuser/myjoomla/tmp/upgrade250</code>).
# Press the Install button.
The system will work for a short time (perhaps a minute or less, depending on your server). Then a message indicating a successful installation will display.

===Upload Package File===
This option requires that you first download the archive file to your local machine.
# Download the file to your local computer.
# In the Extension Manager: Install screen, click the Browse button next to the Package File field and browse to the archive file.
# Press the Install button.
The system will work for a period of time, up to two minutes or more for a full version update. Then a message indicating a successful installation will display.

# Congratulations! At this point, your site is updated.
'''Important:''' Clear your browser cache and check that your site is working correctly. See below Checking Your Site

=Method C - Manual Upgrade=
This method is similar to the old method for updating Joomla versions. Here we want to replace the existing program files with the files from the update archive. The advantage of this method is that it will work on slower shared hosts. The disadvantage is that it requires more work by the system administrator.

''Important: This method can also be used to repair a site where the automatic update failed due to a server timeout.''

==Copy the New Program Files to Your Site==
There are two ways you can do this.
# Copy the archive file to the root directory of your site and unpack the archive. The update archive will be named something like <code>Joomla_2.5.0-Stable-Update_Package.zip</code>. Note that you need to tell the system to replace any existing files. For example, in GoDaddy.com, use the FTP File Manager to upload the update file and then use "Unarchive" to unpack it. Check the box "Overwrite existing files".
# If you don't have the ability to unpack the archive on the server, create a temporary directory on your local machine and unpack the archive file there. Then FTP these files to the root directory of your site, overwriting the existing files.

==Update the Database==
At this point, you should be able to log into the back end of your site with the new version installed. However, you are not done. Navigate to Extension Manager: Database. You will initially have Database problems when you check the Database, similar to the screen below.
[[Image:Update-screenshot-20120124-08.png|frame|center|Database Screen Before Fix]]
This is expected. Click on the Fix icon to correct the problems. Now the screen should show that the database is up to date.

==Install New Extensions==
Navigate to Extension Manager: Discover and click on the Discover icon in the toolbar. If the updated version has new core extensions, new extensions will be listed, as shown below.
[[Image:Update-screenshot-20120124-09.png|frame|center|Discover Screen Before Install]]
Select all the extensions and click on the Install icon in the toolbar. The system should display a success message similar to the screen below.
[[Image:Update-screenshot-20120124-10.png|frame|center|Discover Screen After Install]]

==Update the #__extensions Table==
At this point, your site is updated. However, there is one more thing to do. The site will think it needs to be updated because a value in the #__extensions table is wrong. To fix this:
* Using phpMyAdmin or a similar tool, edit the row of the #__extensions table where the id column is '700'. (Note that the table prefix will be different in your site. For example, if your table prefix is "jos_", then the table will be called "jos_extensions".
* In the manifest_cache column, you will see the old version in the text (for example, <code>"version":"1.7.3"</code>). Change this to the new version (for example, <code>"version":"2.5.0"</code>). Be careful to not change anything else in this column.
* To check that this was successful, navigate to Extension Manager: Update and click Check for Updates. You should '''not''' see the current Joomla version in the list.

At this point, your site should be updated correctly.

=Checking Site=
'''This is required for method A and B!'''
After an update, it is a good idea to clear your browser cache snd check your site to make sure the update was successful. There are two quick checks you can do from the Extension Manager.
==Extension Manager: Check Database==
{{JVer|2.5}} This feature was added in version 2.5.0. It checks that your database is up to date with your Joomla programs.

Navigate to Extension Manager: Database. If your database is up to date, you should see a screen similar to the one below:
[[Image:Update-screenshot-20120124-04.png|frame|center|Database Screen With No Problems]]

If your database is not up to date, you will see a screen listing the problems found, similar to the one below:
[[Image:Update-screenshot-20120124-05.png|frame|center|Database Screen With 3 Database Problems]]
In this case, press the Fix button in the upper right corner. Joomla will update your database to correct the issues listed and then it will re-display the screen. If the fix was successful, the display will indicate that the database is up to date.

'''N.B.''' If any errors fail to fix then make sure all the database Tables are checked in.

==Extension Manager: Discover==
In some cases, when you update to a new Joomla version, new core extensions are added. If there were problems with the database update, these extensions may not have been correctly installed. To check this, navigate to Extension Manager: Discover. Then click on the Discover icon in the toolbar. The screen should show as follows:
[[Image:Update-screenshot-20120124-06.png|frame|center|Discover Screen With No Extensions To Install]]
If so, you know that any new extensions added during the udpate were correctly installed in the database.

If there are uninstalled extensions, they will show similar to the following screen:
[[Image:Update-screenshot-20120124-07.png|frame|center|Discover Screen With Two Extensions To Install]]
In this case, check the check boxes and click on the Install icon in the toolbar. Joomla will install the extension(s) and then display the screen showing no extensions discovered. At this point, the new extensions have been installed in the database.

=Troubleshooting=
If you have any questions before, during, or after the upgrade then please ask them on the [http://forum.joomla.org/viewforum.php?f=625&sid=259a29d8e21242b6770f86026f6c9c3a Joomla! 1.6 Migrating and Upgrading Forum].

If you have problems or errors during the update process, here are some tips.
* Clear your browser cache as there may have been changes to the css or javascript that will need to be reloaded by your web browser.
* If any database error messages show after the update, be sure to check the Extension Manager: Database tab followed by the Extension Manager: Discover tab. In some cases, if a database error occurs it will prevent all the database updates from running. In this case, you can run them from the Database tab and then use the Discover→Install method to check and install any new extensions.
* If you encounter any errors or problems during or after the update, be sure to check the FAQ for the version you updated to. For example, for version 2.5.0, this will be an article entitled [http://docs.joomla.org/Category:Version_2.5.0_FAQ http://docs.joomla.org/Category:Version_2.5.0_FAQ].

<headertabs/>
[[Category:Upgrading]]
[[Category:Joomla! 3.0]][[Category:Joomla! 3.1]]

File:Updatesuccess3-en.PNG

2013-07-25T21:03:55Z

Elin:

J3.x:Updating from an existing version

2013-07-25T21:03:08Z

Elin: /* Browse to Components, Joomla Update */

{{RightTOC}}
=Overview=
The recommended way to update installations of Joomla! is to use the Joomla Updater component found in the Components menu of your site Administrator.

==Back up your site==

==Browse to Components, Joomla Update==
[[File:Componentsmenu.PNG]]

If an update is available there will be a message indicating this and a button to press.

[[File:Updatewaitingj3.PNG]]

==Click on the "Install the Update" button and allow the update to run==

[[File:Updatecompleted25.PNG]]

== When it has completed you may need to refresh your screen or empty your browser cache to adjust for template CSS changes.==

Note: Joomla! will notify on your administrator home page (control panel) when an update is needed, but it will not do the update for you. You need to press the button to start the update.

==Trouble Shooting and Advanced Techniques==
Starting with version 1.6, there are three ways to update your Joomla Website to versions 1.6, 1.7 or 2.5.
If you are in an older version that did not support one click updates or are on a server that does not allow such updates you should use one of these options.

* Extension Manager: Update
* Extension Manager: Install
* Manually Copy Program Files

Each of these is discussed below.

==Upgrade from version earlier than 1.6.x to Joomla 1.7? ==
This page does not contain the instructions for migrating a Website from Joomla versions earlier than 1.6. See the [[J2.5:Migrating from Joomla 1.5 to Joomla 2.5|Migrating from Joomla 1.5 to Joomla 2.5]] page.

==Upgrade from version 1.6.x to Joomla 1.7? ==
Note: To upgrade from version 1.6.x to Joomla 1.7 please follow the [[Upgrade 1.6.5 to 1.7|Upgrade 1.6.5 to 1.7 guide]] before you upgrade to Joomla 2.5.

==Upgrade to Joomla 2.5 on shared hosts==
{{notice|<small>'''Important note as of 28 January 2012:''' ''On some shared host environments (GoDaddy.com and perhaps others), the normal Joomla update from 1.7 to 2.5 can intermittently fail with the error "Internal Server Error". In some cases, this can happen in the middle of the file transfer process and cause errors on the site. On GoDaddy.com, this appears to happen when the server is under a heavy load and the update takes longer than 2 minutes to complete.''
''Based on recent testing, sites on these slower shared hosts can safely be updated using a free third-party extension called [http://tinyurl.com/7d9odse Admin Tools]. If you are updating a site on a shared host, please consider using Admin Tools or else use the Manually Copy Program Files method outlined below.''
''If you have experienced an error during the update, there is a process for repairing the site.''</small>}}

'''Steps and actions:'''
It is recommended that you follow these steps when updating a production site:
# Back up your site before upgrading to a new version. That way, if something goes wrong during the upgrade process, you can easily restore your site to the earlier version.
# Review the release notes for the new version to be familiar with what was changed.
# Update using one of the recommended methods outlined in this document. These methods install the new program files, delete unneeded old program files, and update the database as needed for the new Joomla version.
# Clear your browser cache and check that the update was successful, using the steps outlined in the '''Checking Site''' tab.

=Method A - Update Method=
This is the easier way, also called ''One click update''

==Step 1: Make sure you have a current backup of your site==
In many cases, your host will make periodic site backups.

==Step 2a: Find and install updates==
# '''If your site is prior to 2.5.4, see Step 2b instead'''
# In the back end of your Joomla site, navigate to Components → Joomla Update.
# Click on Install the Update [[Image:Update-screenshot-20120618-01.png|frame|center]]
# '''IMPORTANT:''' This process will take a few minutes. Wait until the process completes and it tells you that you are already on the current release, similar to the screen shown below. [[Image:Update-screenshot-20120618-02.png|frame|center]]
# Congratulations! At this point, your site is updated.
'''Important:''' Clear your browser cache and check that your site is working correctly. See below Checking Your Site

==Step 2b: Find and install updates (Prior to updating 2.5.4)==
# In the back end of your Joomla site, navigate to Extensions → Extension Manager and open the Update tab.
# Click on the Purge Cache icon to clear out the cache.
# Click on the Find Updates icon in the toolbar. If there is an available update, the screen will list it, similar to the screen shown below. [[Image:Update-screenshot-20120124-01.png|frame|center]] Note that available upgrades for extensions used in the site will also show in the list.
# Select the update (using the checkbox) and click on the Update icon in the toolbar.
# '''IMPORTANT:''' This process will take a few minutes. Wait until the process completes and the success message shows, similar to the screen shown below. [[Image:Update-screenshot-20120124-02.png|frame|center]]
# Congratulations! At this point, your site is updated.
'''Important:''' Clear your browser cache and check that your site is working correctly. See below Checking Your Site

=Method B - Install Method=
In some cases it may not be possible to use the Extension Manager: Update method to update your site. One reason for this might be that you are using a non-standard distribution (for example, a distribution with a different default language installed). Another reason might be that your don't have a reliable enough internet connection to support automatic installation.

In this case, you can still do an easy installation using the Extension Manager: Install screen. Like the Update screen, this method will do the database updates automatically and will completely update your system without any further steps.

==Step 1: Make sure you have a current backup of your site==
In many cases, your host will make periodic site backups.

==Step 2: Locate the update file==
Locate the required archive file (for example, .zip, .tag.gz, or tar.bz2 archive) for your version. If you are updating to an x.x.0 release (for example, from 1.7.3 to 2.5.0), this will normally be a file like Joomla_2.5.0-Stable-Update_Package.zip. If you are updating within the same release series (for example, 2.5.0 to 2.5.1), then the file will be named something like Joomla_2.5.0_to_2.5.1-Stable-Patch_Package.zip.

At this point, you have three options:
# Install from URL
# Install from Directory
# Upload Package File

Install from URL is the easiest to do. With this option, the upgrade archive is loaded directly by the server, so it works well even if your local computer has a slow or unreliable internet connection.

Install from Directory is the safest method if the server itself has a slow internet connection. With this method, you use FTP to load the unpacked update files into a temporary folder on the server. Then you point to that directory on the server for the installation.

Upload Package File is fairly simple, but it requires that you have a good connection between your local computer and the server.

The screen below shows the Extension Manager: Install screen with the three options labeled.
[[Image:Update-screenshot-20120124-03.png|frame|center]]

===Install from URL===
This option is the easiest, if the archive file is available on a website.
# In the Extension Manager: Install screen, enter the URL for the archive file in the Install URL field.
# Press the Install button.
The system will work for a period of time, up to two minutes or more for a full version update. Then a message indicating a successful installation will display.

===Install from Directory===
This option requires that you unpack the archive file in a directory on your server. This is the best method if you have a slow internet connection or you are experiencing timeouts during the update process.
# Unpack the archive file in a temporary directory on your local machine.
# Upload all the files in this directory (for example, using FTP) to a temporary directory that is visible to the web server. For example, you can create a sub-directory under the tmp directory in your Joomla root. For this example, let's say the directory on the server is <code>/home/myuser/myjoomla/tmp/upgrade250</code>).
# In the Extension Manager: Install screen, enter the full path of the temporary directory (on the server) from step 2 (for example, <code>/home/myuser/myjoomla/tmp/upgrade250</code>).
# Press the Install button.
The system will work for a short time (perhaps a minute or less, depending on your server). Then a message indicating a successful installation will display.

===Upload Package File===
This option requires that you first download the archive file to your local machine.
# Download the file to your local computer.
# In the Extension Manager: Install screen, click the Browse button next to the Package File field and browse to the archive file.
# Press the Install button.
The system will work for a period of time, up to two minutes or more for a full version update. Then a message indicating a successful installation will display.

# Congratulations! At this point, your site is updated.
'''Important:''' Clear your browser cache and check that your site is working correctly. See below Checking Your Site

=Method C - Manual Upgrade=
This method is similar to the old method for updating Joomla versions. Here we want to replace the existing program files with the files from the update archive. The advantage of this method is that it will work on slower shared hosts. The disadvantage is that it requires more work by the system administrator.

''Important: This method can also be used to repair a site where the automatic update failed due to a server timeout.''

==Copy the New Program Files to Your Site==
There are two ways you can do this.
# Copy the archive file to the root directory of your site and unpack the archive. The update archive will be named something like <code>Joomla_2.5.0-Stable-Update_Package.zip</code>. Note that you need to tell the system to replace any existing files. For example, in GoDaddy.com, use the FTP File Manager to upload the update file and then use "Unarchive" to unpack it. Check the box "Overwrite existing files".
# If you don't have the ability to unpack the archive on the server, create a temporary directory on your local machine and unpack the archive file there. Then FTP these files to the root directory of your site, overwriting the existing files.

==Update the Database==
At this point, you should be able to log into the back end of your site with the new version installed. However, you are not done. Navigate to Extension Manager: Database. You will initially have Database problems when you check the Database, similar to the screen below.
[[Image:Update-screenshot-20120124-08.png|frame|center|Database Screen Before Fix]]
This is expected. Click on the Fix icon to correct the problems. Now the screen should show that the database is up to date.

==Install New Extensions==
Navigate to Extension Manager: Discover and click on the Discover icon in the toolbar. If the updated version has new core extensions, new extensions will be listed, as shown below.
[[Image:Update-screenshot-20120124-09.png|frame|center|Discover Screen Before Install]]
Select all the extensions and click on the Install icon in the toolbar. The system should display a success message similar to the screen below.
[[Image:Update-screenshot-20120124-10.png|frame|center|Discover Screen After Install]]

==Update the #__extensions Table==
At this point, your site is updated. However, there is one more thing to do. The site will think it needs to be updated because a value in the #__extensions table is wrong. To fix this:
* Using phpMyAdmin or a similar tool, edit the row of the #__extensions table where the id column is '700'. (Note that the table prefix will be different in your site. For example, if your table prefix is "jos_", then the table will be called "jos_extensions".
* In the manifest_cache column, you will see the old version in the text (for example, <code>"version":"1.7.3"</code>). Change this to the new version (for example, <code>"version":"2.5.0"</code>). Be careful to not change anything else in this column.
* To check that this was successful, navigate to Extension Manager: Update and click Check for Updates. You should '''not''' see the current Joomla version in the list.

At this point, your site should be updated correctly.

=Checking Site=
'''This is required for method A and B!'''
After an update, it is a good idea to clear your browser cache snd check your site to make sure the update was successful. There are two quick checks you can do from the Extension Manager.
==Extension Manager: Check Database==
{{JVer|2.5}} This feature was added in version 2.5.0. It checks that your database is up to date with your Joomla programs.

Navigate to Extension Manager: Database. If your database is up to date, you should see a screen similar to the one below:
[[Image:Update-screenshot-20120124-04.png|frame|center|Database Screen With No Problems]]

If your database is not up to date, you will see a screen listing the problems found, similar to the one below:
[[Image:Update-screenshot-20120124-05.png|frame|center|Database Screen With 3 Database Problems]]
In this case, press the Fix button in the upper right corner. Joomla will update your database to correct the issues listed and then it will re-display the screen. If the fix was successful, the display will indicate that the database is up to date.

'''N.B.''' If any errors fail to fix then make sure all the database Tables are checked in.

==Extension Manager: Discover==
In some cases, when you update to a new Joomla version, new core extensions are added. If there were problems with the database update, these extensions may not have been correctly installed. To check this, navigate to Extension Manager: Discover. Then click on the Discover icon in the toolbar. The screen should show as follows:
[[Image:Update-screenshot-20120124-06.png|frame|center|Discover Screen With No Extensions To Install]]
If so, you know that any new extensions added during the udpate were correctly installed in the database.

If there are uninstalled extensions, they will show similar to the following screen:
[[Image:Update-screenshot-20120124-07.png|frame|center|Discover Screen With Two Extensions To Install]]
In this case, check the check boxes and click on the Install icon in the toolbar. Joomla will install the extension(s) and then display the screen showing no extensions discovered. At this point, the new extensions have been installed in the database.

=Troubleshooting=
If you have any questions before, during, or after the upgrade then please ask them on the [http://forum.joomla.org/viewforum.php?f=625&sid=259a29d8e21242b6770f86026f6c9c3a Joomla! 1.6 Migrating and Upgrading Forum].

If you have problems or errors during the update process, here are some tips.
* Clear your browser cache as there may have been changes to the css or javascript that will need to be reloaded by your web browser.
* If any database error messages show after the update, be sure to check the Extension Manager: Database tab followed by the Extension Manager: Discover tab. In some cases, if a database error occurs it will prevent all the database updates from running. In this case, you can run them from the Database tab and then use the Discover→Install method to check and install any new extensions.
* If you encounter any errors or problems during or after the update, be sure to check the FAQ for the version you updated to. For example, for version 2.5.0, this will be an article entitled [http://docs.joomla.org/Category:Version_2.5.0_FAQ http://docs.joomla.org/Category:Version_2.5.0_FAQ].

<headertabs/>
[[Category:Upgrading]]
[[Category:Joomla! 3.0]][[Category:Joomla! 3.1]]

File:J3-joomla-update-component-en.PNG

2013-07-25T21:01:35Z

Elin: