Joomla! Documentation - User contributions [en]

Talk:Manifest files

2023-11-28T21:16:18Z

Munchkin:

Manifest information on adding dashboards needs to be added. See https://github.com/joomla/joomla-cms/pull/31397

== Confusing description regarding languages element ==

The given description for the languages element (<languages><language tag="...">..</language></language>) is confusing to me. It sounds like in recent versions of Joomla, it is enough to specify the "language" folder to copy to the extension folder. [https://github.com/codeling/bfstop/issues/204 From my experience however], this is not enough; in the linked case, onlyadding the separate "<languages>" element (without the folder attribute, as mentioned following the sentence "Note that both ways can work together.") actually makes the translations '''within a language folder in the extension folder '''work '''reliably'''.

The text following the example code for the languages element ("The advantages of this solution are the following...") I also find confusing: If I understand it correctly, adding the languages element enables files in the top level language folder (put there either by the extension itself or by the user) to override language strings from the language folder in the extension; and that this is not possible if the languages element does not exist.

But nowhere is it explained what the languages element with its sub-elements actually is really good for in this case. Why is this information needed, and why is that "advantage" only available if the element exists? The file names need to follow a fixed naming scheme anyway, right? Supposedly, Joomla only checks the root level language folder if the languages element exists? But from the bug report linked to above, I can rule out that this entry is '''just''' there to make Joomla also check the root languages folder; it apparently at least ''also'' somehow affects the loading/processing of files inside the extensions directory.

I have neither the time nor the knowledge to check this in the Joomla code unfortunately (that's why I'm posting here instead of changing the documentation directly; but I do suspect that for making translations '''reliably work''', both a "languages" folder copied to within the extension directory, as well as the "languages" element, are actually required / best practice; and using anything else (is probably not well-tested and) can lead to unforseen consequences.

[[User:Munchkin|Munchkin]] ([[User talk:Munchkin|talk]]) 15:14, 28 November 2023 (CST)

Talk:Manifest files

2023-11-28T21:14:20Z

Munchkin:

Manifest information on adding dashboards needs to be added. See https://github.com/joomla/joomla-cms/pull/31397

== Confusing description regarding languages element ==

The given description for the languages element (<languages><language tag="...">..</language></language>) is confusing to me. It sounds like in recent versions of Joomla, it is enough to specify the "language" folder to copy to the extension folder. [https://github.com/codeling/bfstop/issues/204 From my experience however], this is not enough; only adding the separate "<languages>" element (without folder) as mentioned following the sentence "Note that both ways can work together." actually makes it work '''reliably'''.

The text following the example code for the languages element ("The advantages of this solution are the following...") I also find confusing: If I understand it correctly, adding the languages element enables files in the top level language folder (put there either by the extension itself or by the user) to override language strings from the language folder in the extension; and that this is not possible if the languages element does not exist.

But nowhere is it explained what the languages element with its sub-elements actually is really good for in this case. Why is this information needed, and why is that "advantage" only available if the element exists? The file names need to follow a fixed naming scheme anyway, right? Supposedly, Joomla only checks the root level language folder if the languages element exists? But from the bug report linked to above, I can rule out that this entry is '''just''' there to make Joomla also check the root languages folder; it apparently at least ''also'' somehow affects the loading/processing of files inside the extensions directory.

I have neither the time nor the knowledge to check this in the Joomla code unfortunately (that's why I'm posting here instead of changing the documentation directly; but I do suspect that for making translations '''reliably work''', both a "languages" folder copied to within the extension directory, as well as the "languages" element, are actually required / best practice; and using anything else (is probably not well-tested and) can lead to unforseen consequences.

[[User:Munchkin|Munchkin]] ([[User talk:Munchkin|talk]]) 15:14, 28 November 2023 (CST)

Talk:Manifest files

2023-11-28T21:07:44Z

Munchkin:

Manifest information on adding dashboards needs to be added. See https://github.com/joomla/joomla-cms/pull/31397

== Confusing description regarding languages element ==

The given description for the languages element (<languages><language tag="...">..</language></language>) is confusing to me. It sounds like in recent versions of Joomla, it is enough to specify the "language" folder to copy to the extension folder. [https://github.com/codeling/bfstop/issues/204 From my experience however], this is not enough; only adding the separate "<languages>" element (without folder) as mentioned following the sentence "Note that both ways can work together." actually makes it work '''reliably'''.

The text following the example code for the languages element ("The advantages of this solution are the following...") I also find confusing: If I understand it correctly, adding the languages element enables files in the top level language folder (put there either by the extension itself or by the user) to override language strings from the language folder in the extension; and that this is not possible if the languages element does not exist.

But nowhere is it explained what the languages element with its sub-elements actually is really good for in this case. Why is this information needed, and why is that "advantage" only available if the element exists? The file names need to follow a fixed naming scheme anyway, right? Supposedly, Joomla only checks the root level language folder if the languages element exists? But from the bug report linked to above, I can rule out that this entry is '''just''' there to make Joomla also check the root languages folder; it apparently at least ''also'' somehow affects the loading/processing of files inside the extensions directory.

I have neither the time nor the knowledge to check this in the Joomla code unfortunately (that's why I'm posting here instead of changing the documentation directly; but I do suspect that for making translations '''reliably work''', both a "languages" folder copied to within the extension directory, as well as the "languages" element, are actually required / best practice; and using anything else (is probably not well-tested and) can lead to unforseen consequences.

Potential backward compatibility issues in Joomla 4

2018-02-27T07:46:43Z

Munchkin: correct JSubMenuHelper note

<noinclude><languages /></noinclude>
{{incomplete}}{{RightTOC}}<translate>
This document tracks potential backward compatibility issues for Joomla! 4. Listed are issues which potentially break extensions.


The base of this comparison is Joomla! 3.7.</translate>

<translate>
== Updated System Requirements == 
</translate>
<translate>
The system requirements have been updated as follows:
*PHP 7
*MySQL 5.5.3
*PostgreSQL 9.2
*SQL Server support has been dropped.</translate>

<translate>
=== PHP MySQL Extension === 
</translate>
<translate>
*Joomla no longer supports using PHP's ext/mysql driver (which was removed in PHP 7.0). Joomla will automatically try and use the mysqli extension (available since PHP 5.3) or the mysql PDO Driver (available since PHP 5.3) else it will fail to create a database connection.</translate>

<translate>

== CMS Libraries == 
</translate>
<translate>
The following changes have been made to Joomla! CMS libraries (this is primarily code found in the `libraries/cms` directory in Joomla! 3).</translate>

<translate>
=== Installer === 
</translate>

<translate>
==== Removed Classes ==== 
</translate>
<translate>
The following classes have been removed in Joomla! 4.0:
*JInstallerComponent (use JInstallerAdapterComponent instead)
*JInstallerFile (use JInstallerAdapterFile instead)
*JInstallerLanguage (use JInstallerAdapterLanguage instead)
*JInstallerLibrary (use JInstallerAdapterLibrary instead)
*JInstallerModule (use JInstallerAdapterModule instead)
*JInstallerPackage (use JInstallerAdapterPackage instead)
*JInstallerPlugin (use JInstallerAdapterPlugin instead)
*JInstallerTemplate (use JInstallerAdapterTemplate instead)
*JSubMenuHelper (use JHtmlSidebar instead; note that in contrast to JSubMenuHelper, this requires an addition of a placeholder in your view template)
</translate>

<translate>
==== JInstallerAdapter Inheritance ==== 
</translate>
<translate>
JInstallerAdapter no longer extends from JAdapterInstance and inherently JObject.</translate>

<translate>
=== Menu === 
</translate>
<translate>
==== JMenu is now an abstract class ==== 
</translate>
<translate>
JMenu is now an abstract class. Subclasses of JMenu must now also implement a load method.</translate>

<translate>
==== Manual Include Behavior Removed ==== 
</translate>
<translate>
The logic in JMenu::getInstance() to manually include a file from the application's includes/menu.php path has been removed. The JMenu subclass should be autoloaded instead.</translate>

<translate>
=== Pathway === 
</translate>

<translate>
==== Manual Include Behavior Removed ==== 
</translate>
<translate>
The logic in JPathway::getInstance() to manually include a file from the application's includes/pathway.php path has been removed. The JPathway subclass should be autoloaded instead.</translate>

<translate>
=== Router === 
</translate>

<translate>
==== Manual Include Behavior Removed ==== 
</translate>
<translate>
The logic in JRouter::getInstance() to manually include a file from the application's includes/router.php path has been removed. The JRouter subclass should be autoloaded instead.</translate>

<translate>
=== JVersion === 
</translate>
<translate>
Support for accessing the JVersion class constants as class properties is no longer supported. The constants were introduced in Joomla! 3.5 to prevent the old class properties from being edited.</translate>

<translate>
== Platform == 
</translate>
<translate>
The following changes have been made to Joomla! Platform libraries (this is primarily code found in the `libraries/joomla` or `libraries/legacy` directories in Joomla! 3).</translate>

<translate>
=== Application === 
</translate>

<translate>
==== Removed Classes ==== 
</translate>
<translate>
The following classes have been removed in Joomla! 4.0:
*JApplicationWebRouter (use the `joomla/router` package instead)
*JApplicationWebRouterBase (use the `joomla/router` package instead)
*JApplicationWebRouterRest (use the `joomla/router` package instead)</translate>

<translate>
==== Deprecated Classes ==== 
</translate>
<translate>
The following classes have been deprecated and scheduled for removal in Joomla! 5.0:
*JApplicationBase (use Joomla\Application\AbstractApplication instead)</translate>

<translate>
==== CLI/Web Class Changes ==== 
</translate>
<translate>
The JApplicationCli and JApplicationWeb classes have been recomposed to extend from the Framework's Application package instead. This breaks type checks for a JApplicationBase object. For forward compatibility, it is recommended to check if application classes are an instance of Joomla\Application\AbstractApplication (JApplicationBase has extended this class since Joomla! 3.4).</translate>

<translate>
Additionally, both of these classes are now abstract. Developers implementing these classes must provide a `doExecute` method with their application's logic.</translate>

===== JApplicationCli =====

*<translate>
Old:</translate> JApplicationCli {{rarr}} JApplicationBase {{rarr}} Joomla\Application\AbstractApplication
*<translate>
New:</translate> JApplicationCli {{rarr}} Joomla\Application\AbstractCliApplication {{rarr}} Joomla\Application\AbstractApplication

===== JApplicationWeb =====

*<translate>
Old:</translate> JApplicationWeb {{rarr}} JApplicationBase {{rarr}} Joomla\Application\AbstractApplication
*<translate>
New:</translate> JApplicationWeb {{rarr}} Joomla\Application\AbstractWebApplication {{rarr}} Joomla\Application\AbstractApplication

=== Crypt ===
<translate>
Removed Classes</translate>

<translate>
The following ciphers have been removed in Joomla! 4.0:</translate>
*JCryptCipher3Des
*JCryptCipherBlowfish
*JCryptCipherMcrypt
*JCryptCipherRijndael256
*JCryptCipherSimple

<translate>
These have been removed without replacement. Use JCryptCipherCrypto</translate>

<translate>
=== Document === 
</translate>

<translate>
==== Deprecated Classes ==== 
</translate>
<translate>
The following classes have been deprecated and scheduled for removal in Joomla! 5.0:
*JDocumentError (use \Joomla\Cms\Error\RendererInterface objects instead)</translate>

==== JDocumentFeed ====
<translate>
The property type of JDocumentFeed::$lastBuildDate has changed from a string to a JDate object. The property was previously unused by the core Joomla API but extensions may have used it.</translate>

==== JDocumentRendererFeedRss ====
<translate>
In order to comply with the RSS feed specification, JDocumentRendererFeedRss now allows the lastBuildDate element to be configured using the JDocumentFeed::$lastBuildDate class property when a feed is rendered. This value defaults to the current time, as is the case with Joomla! 3.x and earlier, however the time can be correctly set by changing this class property to a JDate object representing the desired timestamp.</translate>

=== HTTP ===

<translate>==== Deprecated Classes and Interfaces ==== </translate>
<translate>
The following classes and interfaces have been deprecated and scheduled for removal in Joomla! 5.0:
*JHttpResponse (use Joomla\Http\Response instead)
*JHttpTransport (implement Joomla\Http\TransportInterface instead)</translate>

<translate>==== Class Changes ==== </translate>
<translate>
The Framework's HTTP package is now included in Joomla! 4.0 and JHttp and the JHttpTransport subclasses have been refactored to use the upstream package.</translate>

===== JHttp =====
<translate>
The JHttp class constructor has been loosened with the following changes:</translate>

<translate>
*The options parameter is no longer typehinted as a Joomla\Registry\Registry object, an array or any object implementing the [https://secure.php.net/manual/en/class.arrayaccess.php ArrayAccess] interface can be used instead
*The transport parameter now allows any Joomla\Http\TransportInterface object.</translate>

===== JHttpTransport =====
<translate>
The now deprecated JHttpTransport interface extends Joomla\Http\TransportInterface now and has caused backward compatibility breaking changes in the interface. The constructor is no longer part of the interface, and the interface's `request()` method has had a signature change. Specifically, the second parameter which previously typehinted the JUri class now typehints Joomla\Uri\UriInterface.</translate>

===== JHttpResponse =====
<translate>
In refactoring the response object to inherit from the Framework's HTTP package, which is now using the PSR-7 ResponseInterface API, a minor compatibility break has been made in the structure of the response headers. As of 4.0, this will now always be a multi-dimensional array where the key is the header name and the value is an array of values for that header (previously, this was a string).</translate>

<translate>
=== Image === 
</translate>

<translate>
==== Deprecated Classes and Interfaces ==== 
</translate>
<translate>
The following classes and interfaces have been deprecated and scheduled for removal in Joomla! 5.0:
* JImageFilter (use Joomla\Image\ImageFilter instead)
* JImageFilterBackgroundfill (use Joomla\Image\Filter\Backgroundfill instead)
* JImageFilterBrightness (use Joomla\Image\Filter\Brightness instead)
* JImageFilterContrast (use Joomla\Image\Filter\Contrast instead)
* JImageFilterEdgedetect (use Joomla\Image\Filter\Edgedetect instead)
* JImageFilterEmboss (use Joomla\Image\Filter\Emboss instead)
* JImageFilterGrayscale (use Joomla\Image\Filter\Grayscale instead)
* JImageFilterNegate (use Joomla\Image\Filter\Negate instead)
* JImageFilterSketchy (use Joomla\Image\Filter\Sketchy instead)
* JImageFilterSmooth (use Joomla\Image\Filter\Smooth instead)</translate>
<translate>
==== Class Changes ==== 
</translate>
<translate>
The Framework's Image package is now included in Joomla! 4.0 and JImage and the JImageFilter subclasses have been refactored to use the upstream package.</translate>
=== Keychain ===
Removing the keychain with 4.0 has resulted in the removal of the following class:
*JKeychain
<translate>
=== Table === 
</translate>
<translate>
* JTable::__construct database object is now typehinted to be a JDatabaseDriver.
** Subclasses of JTable will need to ensure they are passing a JDatabaseDriver object to the parent constructor
** Subclasses of JTable will need to change the method signature of setDbo() if they have an extended version of that method to include the typehint</translate>

<translate>
=== Mail === 
</translate>
<translate>
The following methods have been removed in Joomla! 4.0:</translate>

<translate>
* JMail::sendAdminMail has been removed</translate>

<translate>
=== Legacy MVC Layer === 
</translate>
<translate>
==== Legacy Controller ==== 
</translate>
<translate>
* JControllerLegacy has been removed from the legacy layer, and we no longer intend to remove it or it's subclasses in the near future.
* JControllerLegacy no longer extends JObject. Controllers should not call any of the methods contained in the JObject class.
* JControllerLegacy implements an interface for multiple task controllers
* JControllerLegacy::_construct now requires a compulsory JApplicationCms object. If you were previously getting a Controller object through JControllerLegacy::getInstance you do not need to change your code.
* JControllerForm now using the StringInflector package to determine the list view. This should improve it's ability to guess determine the list view of more view names. If extension developers find that their list view is no longer being found they should manually set the `view_list` class property in their controller.</translate>

<translate>
=== Session === 
</translate>
<translate>
The session package has undergone a major refactoring to use the Framework's Session package. This change primarily effects the internals of the package; changes to the primary public API through the JSession class are minimal.</translate>

<translate>
==== Removed Classes and Interfaces ==== 
</translate>
<translate>
The following classes and interfaces have been removed in Joomla! 5.0:</translate>
*JSessionExceptionUnsupported
*JSessionHandlerInterface
*JSessionHandlerJoomla
*JSessionHandlerNative
*JSessionStorage
*JSessionStorageApc
*JSessionStorageDatabase
*JSessionStorageMemcache
*JSessionStorageMemcached
*JSessionStorageNone
*JSessionStorageWincache
*JSessionStorageXcache

<translate>
==== JSession ==== 
</translate>
<translate>
JSession now extends from the Framework's Joomla\Session\Session class. Many of the methods have a modified signature and a compatibility layer exists to help with the transition.</translate>
<translate>
===== Namespace Parameter Deprecated ===== 
</translate>
<translate>
The get, set, has, and clear methods previously supported a namespace parameter. This parameter is now deprecated, the namespace should be prepended to the name before calling these methods.</translate>
<translate>
===== JSession::clear() Repurposed ===== 
</translate>
<translate>
In the Joomla\Session\Session class, the clear method is used to clear all data from the session store. In JSession, this method is used to remove a single key. When this method is called with parameters, it will call the new Joomla\Session\Session::remove() method.</translate>

<translate>===== JSession::getInstance() Deprecated ===== 
</translate>
<translate>
The singleton getInstance() method has been deprecated. The session object should be retrieved from the active application or the dependency injection container instead.</translate>

<translate>
===== Session Handlers ===== 
</translate>
<translate>
In Joomla! 3.x and earlier, session handlers were represented by the JSessionStorage class and its subclasses. In Joomla! 4.0, session handlers are now implementations of Joomla\Session\HandlerInterface (which is an extension of PHP's [https://secure.php.net/manual/en/class.sessionhandlerinterface.php SessionHandlerInterface]. All handlers which were supported in Joomla! 3.x are still available in 4.0 in addition to two additional handlers; a handler natively implementing the APCu extension and a handler supporting Redis.</translate>

<translate>
=== Classes Removed Without Replacement === 
</translate>
* JNode
* JTree

<translate>
==== Utilities ==== 
</translate>
<translate>
==== Removed Classes and Interfaces ==== 
</translate>
<translate>

The following classes and interfaces have been removed in Joomla! 4.0:</translate>
*JArrayHelper
use Joomla\Utilities\ArrayHelper; instead.

<translate>

== External Libraries == 
</translate>
<translate>
The following changes have been made to the external libraries that Joomla! packages and ships.</translate>

=== PHPMailer ===
<translate>
Joomla! 4.0 ships with PHPMailer 6.0. Please review [https://github.com/PHPMailer/PHPMailer/blob/6.0/UPGRADING.md the upgrading guide] for relevant changes.</translate>

=== PHPUTF8 ===
<translate>
At Joomla! 3.4, the PHPUTF8 library lived in two locations in the Joomla! package; `libraries/phputf8` and `libraries/vendor/joomla/string/src/phputf8`. In Joomla! 4.0, the copy of the library in `libraries/phputf8` has been removed. The Joomla\String\StringHelper class exposes many of the library's functions and the Composer autoloader definition imports much of the library as well, however, if you need a feature that is not already included then you should import the required functions from the `libraries/vendor/joomla/string/src/phputf8` path.</translate>

=== SimplePie ===
<translate>
The SimplePie library is no longer included with Joomla! 4.0.</translate>

=== jQuery ===
<translate>
Joomla! 4.0 ships with jQuery 3. Please review [https://jquery.com/upgrade-guide/3.0/ the upgrading guide] for relevant changes. Note that we are not including jQuery Migrate anymore either. We recommend using it locally to help debug your code if there are any issues.</translate>

=== Bootstrap ===
<translate>
Joomla! 4.0 ships with Bootstrap 4.</translate>

Bootstrap 2.3.2 has been deprecated.

<translate>
== Templates == </translate>
<translate>
All the Joomla! 3 templates - ISIS and Hathor in the backend, and protostar and Beeze in the frontend are no longer supported. The new 4.0 backend template is called Atum and the frontend template is called Cassiopeia.</translate>

As a consequence, all extensions must migrate to the new Bootstrap 4 style, away from the current Bootstrap 2.3.2 implementation. For more information about Bootstrap 4: [http://getbootstrap.com/docs/4.0/getting-started/introduction/]. For more information about Bootstrap 2.3.2: [http://getbootstrap.com/2.3.2/]

<translate>
== Other == 
</translate>

<translate>
=== Bin === 
</translate>
<translate>
Removing the keychain with 4.0 has resulted in the removal of the entire Bin directory as it only contained keychain.</translate>

<noinclude>
<translate>

[[Category:Compatibility]]
[[Category:Development]]
[[Category:Platform]]
[[Category:Migration]]
[[Category:Update Working Group]]
[[Category:Joomla! 4.x]]
</translate>
</noinclude>

Potential backward compatibility issues in Joomla 4

2018-02-27T07:19:11Z

Munchkin: JSubmenuHelper removed and alternatives explanation

<noinclude><languages /></noinclude>
{{incomplete}}{{RightTOC}}<translate>
This document tracks potential backward compatibility issues for Joomla! 4. Listed are issues which potentially break extensions.


The base of this comparison is Joomla! 3.7.</translate>

<translate>
== Updated System Requirements == 
</translate>
<translate>
The system requirements have been updated as follows:
*PHP 7
*MySQL 5.5.3
*PostgreSQL 9.2
*SQL Server support has been dropped.</translate>

<translate>
=== PHP MySQL Extension === 
</translate>
<translate>
*Joomla no longer supports using PHP's ext/mysql driver (which was removed in PHP 7.0). Joomla will automatically try and use the mysqli extension (available since PHP 5.3) or the mysql PDO Driver (available since PHP 5.3) else it will fail to create a database connection.</translate>

<translate>

== CMS Libraries == 
</translate>
<translate>
The following changes have been made to Joomla! CMS libraries (this is primarily code found in the `libraries/cms` directory in Joomla! 3).</translate>

<translate>
=== Installer === 
</translate>

<translate>
==== Removed Classes ==== 
</translate>
<translate>
The following classes have been removed in Joomla! 4.0:
*JInstallerComponent (use JInstallerAdapterComponent instead)
*JInstallerFile (use JInstallerAdapterFile instead)
*JInstallerLanguage (use JInstallerAdapterLanguage instead)
*JInstallerLibrary (use JInstallerAdapterLibrary instead)
*JInstallerModule (use JInstallerAdapterModule instead)
*JInstallerPackage (use JInstallerAdapterPackage instead)
*JInstallerPlugin (use JInstallerAdapterPlugin instead)
*JInstallerTemplate (use JInstallerAdapterTemplate instead)
*JSubmenuHelper (replaced by JHtmlSidebar - but sidebar is not showing so far in J4 Alpha builds. Use submenu entries in the manifest instead to link to views of your component)
</translate>

<translate>
==== JInstallerAdapter Inheritance ==== 
</translate>
<translate>
JInstallerAdapter no longer extends from JAdapterInstance and inherently JObject.</translate>

<translate>
=== Menu === 
</translate>
<translate>
==== JMenu is now an abstract class ==== 
</translate>
<translate>
JMenu is now an abstract class. Subclasses of JMenu must now also implement a load method.</translate>

<translate>
==== Manual Include Behavior Removed ==== 
</translate>
<translate>
The logic in JMenu::getInstance() to manually include a file from the application's includes/menu.php path has been removed. The JMenu subclass should be autoloaded instead.</translate>

<translate>
=== Pathway === 
</translate>

<translate>
==== Manual Include Behavior Removed ==== 
</translate>
<translate>
The logic in JPathway::getInstance() to manually include a file from the application's includes/pathway.php path has been removed. The JPathway subclass should be autoloaded instead.</translate>

<translate>
=== Router === 
</translate>

<translate>
==== Manual Include Behavior Removed ==== 
</translate>
<translate>
The logic in JRouter::getInstance() to manually include a file from the application's includes/router.php path has been removed. The JRouter subclass should be autoloaded instead.</translate>

<translate>
=== JVersion === 
</translate>
<translate>
Support for accessing the JVersion class constants as class properties is no longer supported. The constants were introduced in Joomla! 3.5 to prevent the old class properties from being edited.</translate>

<translate>
== Platform == 
</translate>
<translate>
The following changes have been made to Joomla! Platform libraries (this is primarily code found in the `libraries/joomla` or `libraries/legacy` directories in Joomla! 3).</translate>

<translate>
=== Application === 
</translate>

<translate>
==== Removed Classes ==== 
</translate>
<translate>
The following classes have been removed in Joomla! 4.0:
*JApplicationWebRouter (use the `joomla/router` package instead)
*JApplicationWebRouterBase (use the `joomla/router` package instead)
*JApplicationWebRouterRest (use the `joomla/router` package instead)</translate>

<translate>
==== Deprecated Classes ==== 
</translate>
<translate>
The following classes have been deprecated and scheduled for removal in Joomla! 5.0:
*JApplicationBase (use Joomla\Application\AbstractApplication instead)</translate>

<translate>
==== CLI/Web Class Changes ==== 
</translate>
<translate>
The JApplicationCli and JApplicationWeb classes have been recomposed to extend from the Framework's Application package instead. This breaks type checks for a JApplicationBase object. For forward compatibility, it is recommended to check if application classes are an instance of Joomla\Application\AbstractApplication (JApplicationBase has extended this class since Joomla! 3.4).</translate>

<translate>
Additionally, both of these classes are now abstract. Developers implementing these classes must provide a `doExecute` method with their application's logic.</translate>

===== JApplicationCli =====

*<translate>
Old:</translate> JApplicationCli {{rarr}} JApplicationBase {{rarr}} Joomla\Application\AbstractApplication
*<translate>
New:</translate> JApplicationCli {{rarr}} Joomla\Application\AbstractCliApplication {{rarr}} Joomla\Application\AbstractApplication

===== JApplicationWeb =====

*<translate>
Old:</translate> JApplicationWeb {{rarr}} JApplicationBase {{rarr}} Joomla\Application\AbstractApplication
*<translate>
New:</translate> JApplicationWeb {{rarr}} Joomla\Application\AbstractWebApplication {{rarr}} Joomla\Application\AbstractApplication

=== Crypt ===
<translate>
Removed Classes</translate>

<translate>
The following ciphers have been removed in Joomla! 4.0:</translate>
*JCryptCipher3Des
*JCryptCipherBlowfish
*JCryptCipherMcrypt
*JCryptCipherRijndael256
*JCryptCipherSimple

<translate>
These have been removed without replacement. Use JCryptCipherCrypto</translate>

<translate>
=== Document === 
</translate>

<translate>
==== Deprecated Classes ==== 
</translate>
<translate>
The following classes have been deprecated and scheduled for removal in Joomla! 5.0:
*JDocumentError (use \Joomla\Cms\Error\RendererInterface objects instead)</translate>

==== JDocumentFeed ====
<translate>
The property type of JDocumentFeed::$lastBuildDate has changed from a string to a JDate object. The property was previously unused by the core Joomla API but extensions may have used it.</translate>

==== JDocumentRendererFeedRss ====
<translate>
In order to comply with the RSS feed specification, JDocumentRendererFeedRss now allows the lastBuildDate element to be configured using the JDocumentFeed::$lastBuildDate class property when a feed is rendered. This value defaults to the current time, as is the case with Joomla! 3.x and earlier, however the time can be correctly set by changing this class property to a JDate object representing the desired timestamp.</translate>

=== HTTP ===

<translate>==== Deprecated Classes and Interfaces ==== </translate>
<translate>
The following classes and interfaces have been deprecated and scheduled for removal in Joomla! 5.0:
*JHttpResponse (use Joomla\Http\Response instead)
*JHttpTransport (implement Joomla\Http\TransportInterface instead)</translate>

<translate>==== Class Changes ==== </translate>
<translate>
The Framework's HTTP package is now included in Joomla! 4.0 and JHttp and the JHttpTransport subclasses have been refactored to use the upstream package.</translate>

===== JHttp =====
<translate>
The JHttp class constructor has been loosened with the following changes:</translate>

<translate>
*The options parameter is no longer typehinted as a Joomla\Registry\Registry object, an array or any object implementing the [https://secure.php.net/manual/en/class.arrayaccess.php ArrayAccess] interface can be used instead
*The transport parameter now allows any Joomla\Http\TransportInterface object.</translate>

===== JHttpTransport =====
<translate>
The now deprecated JHttpTransport interface extends Joomla\Http\TransportInterface now and has caused backward compatibility breaking changes in the interface. The constructor is no longer part of the interface, and the interface's `request()` method has had a signature change. Specifically, the second parameter which previously typehinted the JUri class now typehints Joomla\Uri\UriInterface.</translate>

===== JHttpResponse =====
<translate>
In refactoring the response object to inherit from the Framework's HTTP package, which is now using the PSR-7 ResponseInterface API, a minor compatibility break has been made in the structure of the response headers. As of 4.0, this will now always be a multi-dimensional array where the key is the header name and the value is an array of values for that header (previously, this was a string).</translate>

<translate>
=== Image === 
</translate>

<translate>
==== Deprecated Classes and Interfaces ==== 
</translate>
<translate>
The following classes and interfaces have been deprecated and scheduled for removal in Joomla! 5.0:
* JImageFilter (use Joomla\Image\ImageFilter instead)
* JImageFilterBackgroundfill (use Joomla\Image\Filter\Backgroundfill instead)
* JImageFilterBrightness (use Joomla\Image\Filter\Brightness instead)
* JImageFilterContrast (use Joomla\Image\Filter\Contrast instead)
* JImageFilterEdgedetect (use Joomla\Image\Filter\Edgedetect instead)
* JImageFilterEmboss (use Joomla\Image\Filter\Emboss instead)
* JImageFilterGrayscale (use Joomla\Image\Filter\Grayscale instead)
* JImageFilterNegate (use Joomla\Image\Filter\Negate instead)
* JImageFilterSketchy (use Joomla\Image\Filter\Sketchy instead)
* JImageFilterSmooth (use Joomla\Image\Filter\Smooth instead)</translate>
<translate>
==== Class Changes ==== 
</translate>
<translate>
The Framework's Image package is now included in Joomla! 4.0 and JImage and the JImageFilter subclasses have been refactored to use the upstream package.</translate>
=== Keychain ===
Removing the keychain with 4.0 has resulted in the removal of the following class:
*JKeychain
<translate>
=== Table === 
</translate>
<translate>
* JTable::__construct database object is now typehinted to be a JDatabaseDriver.
** Subclasses of JTable will need to ensure they are passing a JDatabaseDriver object to the parent constructor
** Subclasses of JTable will need to change the method signature of setDbo() if they have an extended version of that method to include the typehint</translate>

<translate>
=== Mail === 
</translate>
<translate>
The following methods have been removed in Joomla! 4.0:</translate>

<translate>
* JMail::sendAdminMail has been removed</translate>

<translate>
=== Legacy MVC Layer === 
</translate>
<translate>
==== Legacy Controller ==== 
</translate>
<translate>
* JControllerLegacy has been removed from the legacy layer, and we no longer intend to remove it or it's subclasses in the near future.
* JControllerLegacy no longer extends JObject. Controllers should not call any of the methods contained in the JObject class.
* JControllerLegacy implements an interface for multiple task controllers
* JControllerLegacy::_construct now requires a compulsory JApplicationCms object. If you were previously getting a Controller object through JControllerLegacy::getInstance you do not need to change your code.
* JControllerForm now using the StringInflector package to determine the list view. This should improve it's ability to guess determine the list view of more view names. If extension developers find that their list view is no longer being found they should manually set the `view_list` class property in their controller.</translate>

<translate>
=== Session === 
</translate>
<translate>
The session package has undergone a major refactoring to use the Framework's Session package. This change primarily effects the internals of the package; changes to the primary public API through the JSession class are minimal.</translate>

<translate>
==== Removed Classes and Interfaces ==== 
</translate>
<translate>
The following classes and interfaces have been removed in Joomla! 5.0:</translate>
*JSessionExceptionUnsupported
*JSessionHandlerInterface
*JSessionHandlerJoomla
*JSessionHandlerNative
*JSessionStorage
*JSessionStorageApc
*JSessionStorageDatabase
*JSessionStorageMemcache
*JSessionStorageMemcached
*JSessionStorageNone
*JSessionStorageWincache
*JSessionStorageXcache

<translate>
==== JSession ==== 
</translate>
<translate>
JSession now extends from the Framework's Joomla\Session\Session class. Many of the methods have a modified signature and a compatibility layer exists to help with the transition.</translate>
<translate>
===== Namespace Parameter Deprecated ===== 
</translate>
<translate>
The get, set, has, and clear methods previously supported a namespace parameter. This parameter is now deprecated, the namespace should be prepended to the name before calling these methods.</translate>
<translate>
===== JSession::clear() Repurposed ===== 
</translate>
<translate>
In the Joomla\Session\Session class, the clear method is used to clear all data from the session store. In JSession, this method is used to remove a single key. When this method is called with parameters, it will call the new Joomla\Session\Session::remove() method.</translate>

<translate>===== JSession::getInstance() Deprecated ===== 
</translate>
<translate>
The singleton getInstance() method has been deprecated. The session object should be retrieved from the active application or the dependency injection container instead.</translate>

<translate>
===== Session Handlers ===== 
</translate>
<translate>
In Joomla! 3.x and earlier, session handlers were represented by the JSessionStorage class and its subclasses. In Joomla! 4.0, session handlers are now implementations of Joomla\Session\HandlerInterface (which is an extension of PHP's [https://secure.php.net/manual/en/class.sessionhandlerinterface.php SessionHandlerInterface]. All handlers which were supported in Joomla! 3.x are still available in 4.0 in addition to two additional handlers; a handler natively implementing the APCu extension and a handler supporting Redis.</translate>

<translate>
=== Classes Removed Without Replacement === 
</translate>
* JNode
* JTree

<translate>
==== Utilities ==== 
</translate>
<translate>
==== Removed Classes and Interfaces ==== 
</translate>
<translate>

The following classes and interfaces have been removed in Joomla! 4.0:</translate>
*JArrayHelper
use Joomla\Utilities\ArrayHelper; instead.

<translate>

== External Libraries == 
</translate>
<translate>
The following changes have been made to the external libraries that Joomla! packages and ships.</translate>

=== PHPMailer ===
<translate>
Joomla! 4.0 ships with PHPMailer 6.0. Please review [https://github.com/PHPMailer/PHPMailer/blob/6.0/UPGRADING.md the upgrading guide] for relevant changes.</translate>

=== PHPUTF8 ===
<translate>
At Joomla! 3.4, the PHPUTF8 library lived in two locations in the Joomla! package; `libraries/phputf8` and `libraries/vendor/joomla/string/src/phputf8`. In Joomla! 4.0, the copy of the library in `libraries/phputf8` has been removed. The Joomla\String\StringHelper class exposes many of the library's functions and the Composer autoloader definition imports much of the library as well, however, if you need a feature that is not already included then you should import the required functions from the `libraries/vendor/joomla/string/src/phputf8` path.</translate>

=== SimplePie ===
<translate>
The SimplePie library is no longer included with Joomla! 4.0.</translate>

=== jQuery ===
<translate>
Joomla! 4.0 ships with jQuery 3. Please review [https://jquery.com/upgrade-guide/3.0/ the upgrading guide] for relevant changes. Note that we are not including jQuery Migrate anymore either. We recommend using it locally to help debug your code if there are any issues.</translate>

=== Bootstrap ===
<translate>
Joomla! 4.0 ships with Bootstrap 4.</translate>

Bootstrap 2.3.2 has been deprecated.

<translate>
== Templates == </translate>
<translate>
All the Joomla! 3 templates - ISIS and Hathor in the backend, and protostar and Beeze in the frontend are no longer supported. The new 4.0 backend template is called Atum and the frontend template is called Cassiopeia.</translate>

As a consequence, all extensions must migrate to the new Bootstrap 4 style, away from the current Bootstrap 2.3.2 implementation. For more information about Bootstrap 4: [http://getbootstrap.com/docs/4.0/getting-started/introduction/]. For more information about Bootstrap 2.3.2: [http://getbootstrap.com/2.3.2/]

<translate>
== Other == 
</translate>

<translate>
=== Bin === 
</translate>
<translate>
Removing the keychain with 4.0 has resulted in the removal of the entire Bin directory as it only contained keychain.</translate>

<noinclude>
<translate>

[[Category:Compatibility]]
[[Category:Development]]
[[Category:Platform]]
[[Category:Migration]]
[[Category:Update Working Group]]
[[Category:Joomla! 4.x]]
</translate>
</noinclude>

Using JLog

2014-03-07T01:22:34Z

Munchkin: small correction

{{version|2.5,3.1|platform=11.1}}{{RightTOC}}
Using JLog can be very useful in components when analysing the performance of custom extensions - or analysing where extensions are giving issues. Note this should be used in tandem with php exceptions - not as a replacement. See [[Exceptions and Logging in Joomla 1.7 and Joomla Platform 11.1]] for more information on this

== Calling the class ==

To use JLog you need to call the JLog class. Done through the following code:

jimport('joomla.log.log');

== Basic File Logging ==

Often you may wish to display an error log message and log to an error file. Joomla allows this natively through the [[JLog::add]] function. For example:

JLog::add(JText::_('JTEXT_ERROR_MESSAGE'), JLog::WARNING, 'jerror');

Adding the category of jerror means that this message will also be displayed to users. To only write to file you can easily drop that parameter and simply use

JLog::add(JText::_('JTEXT_ERROR_MESSAGE'), JLog::WARNING);

== Logging a specific extension ==
Sometimes it may be useful to log the errors to a specific file. In this case you can

JLog::addLogger(
array(
// Sets file name
'text_file' => 'com_helloworld.errors.php'
),
// Sets messages of all log levels to be sent to the file
JLog::ALL,
// The log category/categories which should be recorded in this file
// In this case, it's just the one category from our extension, still
// we need to put it inside an array
array('com_helloworld')
);

Now remember to change the category when you add a log message. Such as in the example below.

JLog::add(JText::_('JTEXT_ERROR_MESSAGE'), JLog::WARNING, 'com_helloworld');

'''Note:''' You may wish to combine this with the [[Display error messages and notices]] section to display visable error notifications to users.

== Logging specific priorities ==

You can also add an additional logger to capture only critical and emergency log notifications:

JLog::addLogger(
array(
// Sets file name
'text_file' => 'com_helloworld.critical_emergency.php'
),
// Sets critical and emergency log level messages to be sent to the file
JLog::CRITICAL + JLog::EMERGENCY,
// The log category which should be recorded in this file
array('com_helloworld')
);

You can also exclude a specific category from being included. For example, to log all but DEBUG messages:

JLog::addLogger(
array(
// Sets file name
'text_file' => 'com_helloworld.all_but_debug.php'
),
// Sets all but DEBUG log level messages to be sent to the file
JLog::ALL & ~JLog::DEBUG,
// The log category which should be recorded in this file
array('com_helloworld')
);

Notice how bitwise operations (bitwise AND, &; and bitwise NOT, ~)
are used to calculate the accepted log levels.

== Formatting the logfile ==

The first parameter to addLogger can have a few optional additional settings
in addition to the 'text_file' entry.

There is for example the entry '''text_entry_format''', specifying the format
of each line in your logfile.

The default format is

'{DATETIME} {PRIORITY} {CATEGORY} {MESSAGE}'

Here is an example of a different format which shows how to omit the category:

JLog::addLogger(
array(
// Sets file name
'text_file' => 'com_helloworld.critical_emergency.php'
// Sets the format of each line
'text_entry_format' => '{DATETIME} {PRIORITY} {MESSAGE}'
),
// Sets all but DEBUG log level messages to be sent to the file
JLog::ALL & ~JLog::DEBUG,
// The log category which should be recorded in this file
array('com_helloworld')
);

In addition to the placeholders shown above in the default string, the following
values are available:

{CLIENTIP}
{TIME}
{DATE}

There is an additional optional boolean parameter '''text_file_no_php''', which specifies
whether the log file is prepended with the usual prefix of

#
#<?php die('Forbidden.');?>

'''Note:''' Usually you should not set this setting to false. Log files should not be readable
from the outside, since they can provide valuable information about your system for attackers.
Only dabble with this if you know what you're doing!

Furthermore, if you want to store the log file somewhere else than the logging path configured
in the Joomla! settings, you can there is the '''text_file_path''' setting.

[[Category:Development]]
[[category:Joomla! 1.7]]
[[category:Joomla! 2.5]]
[[category:Joomla! 3.0]]

Using JLog

2014-03-07T01:21:03Z

Munchkin: correction of categories parameter; describe all available options with special detail on formatting an entry; describe in more details how to log specific log levels only

{{version|2.5,3.1|platform=11.1}}{{RightTOC}}
Using JLog can be very useful in components when analysing the performance of custom extensions - or analysing where extensions are giving issues. Note this should be used in tandem with php exceptions - not as a replacement. See [[Exceptions and Logging in Joomla 1.7 and Joomla Platform 11.1]] for more information on this

== Calling the class ==

To use JLog you need to call the JLog class. Done through the following code:

jimport('joomla.log.log');

== Basic File Logging ==

Often you may wish to display an error log message and log to an error file. Joomla allows this natively through the [[JLog::add]] function. For example:

JLog::add(JText::_('JTEXT_ERROR_MESSAGE'), JLog::WARNING, 'jerror');

Adding the category of jerror means that this message will also be displayed to users. To only write to file you can easily drop that parameter and simply use

JLog::add(JText::_('JTEXT_ERROR_MESSAGE'), JLog::WARNING);

== Logging a specific extension ==
Sometimes it may be useful to log the errors to a specific file. In this case you can

JLog::addLogger(
array(
// Sets file name
'text_file' => 'com_helloworld.errors.php'
),
// Sets messages of all log levels to be sent to the file
JLog::ALL,
// The log category/categories which should be recorded in this file
// In this case, it's just the one category from our extension, still
// we need to put it inside an array
array('com_helloworld')
);

Now remember to change the category when you add a log message. Such as in the example below.

JLog::add(JText::_('JTEXT_ERROR_MESSAGE'), JLog::WARNING, 'com_helloworld');

'''Note:''' You may wish to combine this with the [[Display error messages and notices]] section to display visable error notifications to users.

== Logging specific priorities ==

You can also add an additional logger to capture only critical and emergency log notifications:

JLog::addLogger(
array(
// Sets file name
'text_file' => 'com_helloworld.critical_emergency.php'
),
// Sets critical and emergency log level messages to be sent to the file
JLog::CRITICAL + JLog::EMERGENCY,
// The log category which should be recorded in this file
array('com_helloworld')
);

You can also exclude a specific category from being included. For example, to log all but DEBUG messages:

JLog::addLogger(
array(
// Sets file name
'text_file' => 'com_helloworld.all_but_debug.php'
),
// Sets all but DEBUG log level messages to be sent to the file
JLog::ALL & ~JLog::DEBUG,
// The log category which should be recorded in this file
array('com_helloworld')
);

Notice how bitwise operations (bitwise AND, &; and bitwise NOT, ~)
are used to calculate the accepted log levels.

== Formatting the logfile ==

The first parameter to addLogger can have a few optional additional settings
in addition to the 'text_file' entry.

There is for example the entry '''text_entry_format''', specifying the format
of each line in your logfile.

The default format is

'{DATETIME} {PRIORITY} {CATEGORY} {MESSAGE}'

Here is an example of a different format which shows how to omit the category:

JLog::addLogger(
array(
// Sets file name
'text_file' => 'com_helloworld.critical_emergency.php'
// Sets the format of each line
'text_entry_format' => '{DATETIME} {PRIORITY} {MESSAGE}'
),
// Sets all but DEBUG log level messages to be sent to the file
JLog::ALL & ~JLog::DEBUG,
// The log category which should be recorded in this file
array('com_helloworld')
);

In addition to the placeholders shown above in the default string, the following
values are available:

{CLIENTIP}
{TIME}
{DATE}

There is an additional optional boolean parameter '''text_file_no_php''', which specifies
whether the log file is prepended with the usual prefix of

<?php die(\'Forbidden.

'''Note:''' Usually you should not set this setting to false. Log files should not be readable
from the outside, since they can provide valuable information about your system for attackers.
Only dabble with this if you know what you're doing!

Furthermore, if you want to store the log file somewhere else than the logging path configured
in the Joomla! settings, you can there is the '''text_file_path''' setting.

[[Category:Development]]
[[category:Joomla! 1.7]]
[[category:Joomla! 2.5]]
[[category:Joomla! 3.0]]

Using JLog

2014-03-07T00:27:46Z

Munchkin: /* Logging a specific extension */ correction for category parameter

Using JLog

2013-06-22T07:22:17Z

Munchkin: /* Basic File Logging */ fixes copy&paste error ('jerror' was still a parameter in the function call, while the text above stated that it wasn't)

Archived talk:Developing a MVC Component/Adding backend actions

2013-06-05T20:00:59Z

Munchkin: /* Joomla 3.x */ clarification - works, just missed one small thing

It's not clear to me where the word "helloworld" refers to in these examples. Can you please clarify when 'helloworld' refers to the component,controller,model,table,view or form? While following this, I've changed the name of my component, and when running this I get a 'call to member function getTable() on non-object'. It seems that I used the wrong name somewhere, but I have no idea where.

We're also introducing JForms and JFields. These are powerful and important, and warrant some richer explanation.

== Attention! ==

There is a change in /admin/views/helloworlds/tmpl/default_body.php that isnt mentioned on this page but is present in the archive file.

== Model subtlety ==

Note that the model loaded in the getModel function by the HelloWorlds controller (admin/controllers/helloworlds.php) is NOT the HelloWorlds model; it is instead the HelloWorld model. The HelloWorlds model (HelloWorldModelHelloWorlds) extends JModelList, which has no delete function. The HelloWorld model (HelloWorldModelHelloWorld) extends JModelAdmin, which has the delete function needed to delete items.

== Naming confusion ==
I agree with the first user. helloworld is an abused word in the example. We could call the table greetings, so the models (greetings and greeting) and so on. Without using different and clear name the reader cannot understand the mechanism of the MVC pattern. There is also a lack of documentation, e.g. when we create the form in admin/models/forms/helloworld.xml we should give a link or something to possible values of the fields used.
: +1 over here. Naming is too confusing: "HelloWorldControllerHelloWorlds and HelloWorldControllerHelloWorld have to be coded." oh come on, I can't believe there's no better example than "HelloWorld"</br>admin/controllers/'''helloworld'''s.php and </br>admin/controllers/'''helloworld'''.php files... That's just too much for me!</br> [[User:Jpfreire|João Paulo Freire]] 17:54, 11 April 2012 (CDT)

== Joomla 2.5 ==
The counting of the checkboxes are not working any more in Joomla 2.5. Does someone have a solution to this?

Try...
<input type="checkbox" name="checkall-toggle" value="" title="<?php echo JText::_('JGLOBAL_CHECK_ALL'); ?>" onclick="Joomla.checkAll(this)" />
... in the appropriate template. [[User:Cwinebrinner|Cwinebrinner]] ([[User talk:Cwinebrinner|talk]]) 22:23, 31 March 2013 (CDT)

== Joomla 3.x ==
Anybody know what changes are required to this for Joomla 3.x? I've followed the tutorial and it seems to be working fine under Joomla 2.5, however under Joomla 3.1, the "Save and Close" and "Cancel"/"Close" Button on the details form just do nothing (clicking on them only gives a Javascript error: "TypeError: b is null"; and the form looks weird (there is still a bulletin point for all the list elements).
[[User:Munchkin|Munchkin]] ([[User talk:Munchkin|talk]]) 17:28, 3 June 2013 (CDT)

:Hi
:This sounds like a bug of some kind - I'd check you don't have php errors on the page! The button itself should be called exactly the same way in 3.x as in 2.5!!
:Kind Regards,
:George --[[User:Wilsonge|Wilsonge]] ([[User talk:Wilsonge|talk]]) 19:34, 4 June 2013 (CDT)

::Thanks for the quick answer! Turns out I had missed one small detail: The form has to have name '''and id''' of adminForm. Somehow I had used a different ID, and under Joomla 2.5 it still had worked, but not on J3.
::With that id set correctly, it works as well on J3! Weirdest thing is, I checked in com_banners component, and that doesn't seem to use the adminForm id as well, but it still works there... no idea how they do it, but I don't care now as long as it works for me ;).
:: Thanks and so long,
:: [[User:Munchkin|Munchkin]] ([[User talk:Munchkin|talk]]) 15:00, 5 June 2013 (CDT)

Archived talk:Developing a MVC Component/Adding backend actions

2013-06-03T22:28:38Z

Munchkin: Joomla 3 changes

Adding sortable columns to a table in a component

2013-06-03T20:18:19Z

Munchkin: /* Step 1: The Model */ Joomla 3 compabitibility: escape(...) instead of getEscaped(...)

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

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

==Step 1: The Model==

The first thing you need to do is to populate the order state of your model. Change 'default_column_name' to the name of the column you want to use as the default sort, and change the second parameter to DESC if you wish the default order direction to be descending. Calling the parents populateState method will make sure that the State object is filled and accessible to all of the code that might need it.

<source lang="php">
protected function populateState($ordering = null, $direction = null) {
parent::populateState('default_column_name', 'ASC');
}
</source>

The JModelList::populateState only allows predefined values for the ordering. Therefore you'll have to add the names of all columns by which your data can be sorted to the 'filter_fields' config, like this:
<source>
public function __construct($config = array())
{
$config['filter_fields'] = array(
'column_name_1',
'column_name_2',
// ...
'column_name_3'
);
parent::__construct($config);
}
</source>
If you use column prefixes in your query you can also specify them along with the column name (e.g. 'b.id').

In the model which generates the data that will form the table, you need to make a change to the method which builds the database query that will be used to populate the HTML table. Most often this is the [[JModelList::getListQuery|getListQuery()]] method, but might not be.

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

This information gets called by whatever function builds the ORDER BY clause, typically a private function like this:

<source lang="php">
public function getListQuery() {
$db = JFactory::getDbo();
$query = $db->getQuery(true);

// ...

$query->order($db->escape($this->getState('list.ordering', 'default_sort_column')).' '.
$db->escape($this->getState('list.direction', 'ASC')));

return $query;
}
</source>

Replace 'default_sort_column' with the column you want to sort by by default. You can also change 'ASC' to 'DESC', depending on which way you want to sort by default.

==Step 2: The View==
Having generated the sorting variables in the model, you need to assign them to the view so that they show up on the page when it is displayed.

To do this you need to add a few lines of code to your view file, typically view.html.php with code similar to this:
<source lang="php">
public function display($tpl=null) {
$items = $this->get('Items');
$state = $this->get('State');

$this->sortDirection = $state->get('list.direction');
$this->sortColumn = $state->get('list.ordering');

parent::display($tpl);
}
</source>

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

The form tags will look something like this:

<source lang="php">
<form id="adminForm" method="post" name="adminForm">

.... table goes here ....

</form>
</source>
Notice that the form name must be "adminForm". In some special cases you might need to add the action attribute (e.g. action="<?php echo JRoute::_( 'index.php' );?>"), but usually this should not be required, when it's not there the form will just be submitted to the current documents address, i.e. the same page, which is usually the correct behavior.

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

.... table goes here ....

<input type="hidden" name="filter_order" value="<?php echo $this->sortColumn; ?>" />
<input type="hidden" name="filter_order_Dir" value="<?php echo $this->sortDirection; ?>" />
</form>
</source>

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

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

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

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

This completes the changes you need to make to the layout. [[JHTML]] [[JHTMLGrid|grid.sort]] will now add a call to the ''tableOrdering'' function so that ''tableOrdering'' will be called whenever the user clicks on the column header. ''tableOrdering'' puts the name of the column that was clicked, and the sort direction, into the hidden form fields and submits the form; the changed values will get picked up by the populateState method, and then retrieved by your model via the list.ordering/list.dirc.

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

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

==See also==
* [[Developing a Model-View-Controller Component]]

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

Talk:Adding sortable columns to a table in a component

2013-06-02T15:42:03Z

Munchkin: Removes redirect

Since this page now is applying for 2.5, I removed the discussion page redirect which was referring to the 1.5 discussion page.
Here is the link to that old discussion page: [[J1.5 talk:Adding sortable columns to a table in a component]]
[[User:Munchkin|Munchkin]] ([[User talk:Munchkin|talk]]) 10:42, 2 June 2013 (CDT)

Adding sortable columns to a table in a component

2013-06-02T15:39:51Z

Munchkin: Adds again the removed version hint

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

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

==Step 1: The Model==

The first thing you need to do is to populate the order state of your model. Change 'default_column_name' to the name of the column you want to use as the default sort, and change the second parameter to DESC if you wish the default order direction to be descending. Calling the parents populateState method will make sure that the State object is filled and accessible to all of the code that might need it.

<source lang="php">
protected function populateState($ordering = null, $direction = null) {
parent::populateState('default_column_name', 'ASC');
}
</source>

The JModelList::populateState only allows predefined values for the ordering. Therefore you'll have to add the names of all columns by which your data can be sorted to the 'filter_fields' config, like this:
<source>
public function __construct($config = array())
{
$config['filter_fields'] = array(
'column_name_1',
'column_name_2',
// ...
'column_name_3'
);
parent::__construct($config);
}
</source>
If you use column prefixes in your query you can also specify them along with the column name (e.g. 'b.id').

In the model which generates the data that will form the table, you need to make a change to the method which builds the database query that will be used to populate the HTML table. Most often this is the [[JModelList::getListQuery|getListQuery()]] method, but might not be.

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

This information gets called by whatever function builds the ORDER BY clause, typically a private function like this:

<source lang="php">
public function getListQuery() {
$db = JFactory::getDbo();
$query = $db->getQuery(true);

// ...

$query->order($db->getEscaped($this->getState('list.ordering', 'default_sort_column')).' '.
$db->getEscaped($this->getState('list.direction', 'ASC')));

return $query;
}
</source>

Replace 'default_sort_column' with the column you want to sort by by default. You can also change 'ASC' to 'DESC', depending on which way you want to sort by default.

==Step 2: The View==
Having generated the sorting variables in the model, you need to assign them to the view so that they show up on the page when it is displayed.

To do this you need to add a few lines of code to your view file, typically view.html.php with code similar to this:
<source lang="php">
public function display($tpl=null) {
$items = $this->get('Items');
$state = $this->get('State');

$this->sortDirection = $state->get('list.direction');
$this->sortColumn = $state->get('list.ordering');

parent::display($tpl);
}
</source>

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

The form tags will look something like this:

<source lang="php">
<form id="adminForm" method="post" name="adminForm">

.... table goes here ....

</form>
</source>
Notice that the form name must be "adminForm". In some special cases you might need to add the action attribute (e.g. action="<?php echo JRoute::_( 'index.php' );?>"), but usually this should not be required, when it's not there the form will just be submitted to the current documents address, i.e. the same page, which is usually the correct behavior.

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

.... table goes here ....

<input type="hidden" name="filter_order" value="<?php echo $this->sortColumn; ?>" />
<input type="hidden" name="filter_order_Dir" value="<?php echo $this->sortDirection; ?>" />
</form>
</source>

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

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

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

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

This completes the changes you need to make to the layout. [[JHTML]] [[JHTMLGrid|grid.sort]] will now add a call to the ''tableOrdering'' function so that ''tableOrdering'' will be called whenever the user clicks on the column header. ''tableOrdering'' puts the name of the column that was clicked, and the sort direction, into the hidden form fields and submits the form; the changed values will get picked up by the populateState method, and then retrieved by your model via the list.ordering/list.dirc.

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

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

==See also==
* [[Developing a Model-View-Controller Component]]

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

Adding sortable columns to a table in a component

2013-06-02T15:29:45Z

Munchkin: adds missing filter_fields configuration

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

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

==Step 1: The Model==

The first thing you need to do is to populate the order state of your model. Change 'default_column_name' to the name of the column you want to use as the default sort, and change the second parameter to DESC if you wish the default order direction to be descending. Calling the parents populateState method will make sure that the State object is filled and accessible to all of the code that might need it.

<source lang="php">
protected function populateState($ordering = null, $direction = null) {
parent::populateState('default_column_name', 'ASC');
}
</source>

The JModelList::populateState only allows predefined values for the ordering. Therefore you'll have to add the names of all columns by which your data can be sorted to the 'filter_fields' config, like this:
<source>
public function __construct($config = array())
{
$config['filter_fields'] = array(
'column_name_1',
'column_name_2',
// ...
'column_name_3'
);
parent::__construct($config);
}
</source>
If you use column prefixes in your query you can also specify them along with the column name (e.g. 'b.id').

In the model which generates the data that will form the table, you need to make a change to the method which builds the database query that will be used to populate the HTML table. Most often this is the [[JModelList::getListQuery|getListQuery()]] method, but might not be.

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

This information gets called by whatever function builds the ORDER BY clause, typically a private function like this:

<source lang="php">
public function getListQuery() {
$db = JFactory::getDbo();
$query = $db->getQuery(true);

// ...

$query->order($db->getEscaped($this->getState('list.ordering', 'default_sort_column')).' '.
$db->getEscaped($this->getState('list.direction', 'ASC')));

return $query;
}
</source>

Replace 'default_sort_column' with the column you want to sort by by default. You can also change 'ASC' to 'DESC', depending on which way you want to sort by default.

==Step 2: The View==
Having generated the sorting variables in the model, you need to assign them to the view so that they show up on the page when it is displayed.

To do this you need to add a few lines of code to your view file, typically view.html.php with code similar to this:
<source lang="php">
public function display($tpl=null) {
$items = $this->get('Items');
$state = $this->get('State');

$this->sortDirection = $state->get('list.direction');
$this->sortColumn = $state->get('list.ordering');

parent::display($tpl);
}
</source>

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

The form tags will look something like this:

<source lang="php">
<form id="adminForm" method="post" name="adminForm">

.... table goes here ....

</form>
</source>
Notice that the form name must be "adminForm". In some special cases you might need to add the action attribute (e.g. action="<?php echo JRoute::_( 'index.php' );?>"), but usually this should not be required, when it's not there the form will just be submitted to the current documents address, i.e. the same page, which is usually the correct behavior.

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

.... table goes here ....

<input type="hidden" name="filter_order" value="<?php echo $this->sortColumn; ?>" />
<input type="hidden" name="filter_order_Dir" value="<?php echo $this->sortDirection; ?>" />
</form>
</source>

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

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

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

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

This completes the changes you need to make to the layout. [[JHTML]] [[JHTMLGrid|grid.sort]] will now add a call to the ''tableOrdering'' function so that ''tableOrdering'' will be called whenever the user clicks on the column header. ''tableOrdering'' puts the name of the column that was clicked, and the sort direction, into the hidden form fields and submits the form; the changed values will get picked up by the populateState method, and then retrieved by your model via the list.ordering/list.dirc.

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

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

==See also==
* [[Developing a Model-View-Controller Component]]

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

Adding sortable columns to a table in a component

2013-06-02T14:58:34Z

Munchkin: Adapt to Joomla! 2.5 (mainly filter_order -> list.ordering)

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

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

==Step 1: The Model==

The first thing you need to do is to populate the order state of your model. Change 'default_column_name' to the name of the column you want to use as the default sort, and change the second parameter to DESC if you wish the default order direction to be descending. Calling the parents populateState method will make sure that the State object is filled and accessible to all of the code that might need it.

<source lang="php">
protected function populateState($ordering = null, $direction = null) {
parent::populateState('default_column_name', 'ASC');
}
</source>

In the model which generates the data that will form the table, you need to make a change to the method which builds the database query that will be used to populate the HTML table. Most often this is the [[JModelList::getListQuery|getListQuery()]] method, but might not be.

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

This information gets called by whatever function builds the ORDER BY clause, typically a private function like this:

<source lang="php">
public function getListQuery() {
$db = JFactory::getDbo();
$query = $db->getQuery(true);

// ...

$query->order($db->getEscaped($this->getState('list.ordering', 'default_sort_column')).' '.
$db->getEscaped($this->getState('list.direction', 'ASC')));

return $query;
}
</source>

Replace 'default_sort_column' with the column you want to sort by by default. You can also change 'ASC' to 'DESC', depending on which way you want to sort by default.

==Step 2: The View==
Having generated the sorting variables in the model, you need to assign them to the view so that they show up on the page when it is displayed.

To do this you need to add a few lines of code to your view file, typically view.html.php with code similar to this:
<source lang="php">
public function display($tpl=null) {
$items = $this->get('Items');
$state = $this->get('State');

$this->sortDirection = $state->get('list.direction');
$this->sortColumn = $state->get('list.ordering');

parent::display($tpl);
}
</source>

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

The form tags will look something like this:

<source lang="php">
<form id="adminForm" method="post" name="adminForm">

.... table goes here ....

</form>
</source>
Notice that the form name must be "adminForm". In some special cases you might need to add the action attribute (e.g. action="<?php echo JRoute::_( 'index.php' );?>"), but usually this should not be required, when it's not there the form will just be submitted to the current documents address, i.e. the same page, which is usually the correct behavior.

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

.... table goes here ....

<input type="hidden" name="filter_order" value="<?php echo $this->sortColumn; ?>" />
<input type="hidden" name="filter_order_Dir" value="<?php echo $this->sortDirection; ?>" />
</form>
</source>

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

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

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

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

This completes the changes you need to make to the layout. [[JHTML]] [[JHTMLGrid|grid.sort]] will now add a call to the ''tableOrdering'' function so that ''tableOrdering'' will be called whenever the user clicks on the column header. ''tableOrdering'' puts the name of the column that was clicked, and the sort direction, into the hidden form fields and submits the form; the changed values will get picked up by the populateState method, and then retrieved by your model via the list.ordering/list.dirc.

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

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

==See also==
* [[Developing a Model-View-Controller Component]]

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

Migrating from Joomla 1.5 to Joomla 1.6+

2011-10-19T12:40:38Z

Munchkin: /* How to Manually Migrate Joomla */

With Joomla 1.6 officially released, there have been a lot of questions as to how to migrate or upgrade to Joomla 1.6 from 1.5. This guide will take you step-by-step through the general procedure of how to migrate to Joomla 1.6.
Please read through all the material as this is not a light undertaking.
=Before Upgrading=
Don't let the numerical closeness of 1.5 and 1.6, mislead you. Joomla 1.6 took three years to develop and has been a major undertaking. Countless hours have been spent by many volunteers from around the world to put it all together. Although much of the code is the same from Joomla 1.5, much of it has been written from the ground up, and the changes are comparable to the changes from Joomla 1.0 to 1.5.
Because the changes from Joomla 1.5 to 1.6 are so large and because of the massive effort put into getting Joomla 1.6 to where it is today, there is no core upgrade path, this is indeed a migration. In planned future releases of Joomla (which will be released every 6 months), such as Joomla 1.7, 1.8, etc, the changes from version to version will be more incremental and a core upgrade path is planned.
Now that Joomla 1.6 is finally here and stable, a community initiative led by the developers of Joomla is turning towards [http://extensions.joomla.org/extensions/migration-a-conversion/joomla-migration/11658 jUpgrade] (a 3rd party Joomla extension on the JED originally developed by Matias Aguirre) for help and to help. Many of Joomla's developers (who are all volunteers that freely contribute their time) are volunteering to put the finishing touches on [http://extensions.joomla.org/extensions/migration-a-conversion/joomla-migration/11658 jUpgrade].

[http://extensions.joomla.org/extensions/migration-a-conversion/joomla-migration/11658 jUpgrade] allows you to migrate from Joomla 1.5 to 1.6.
Lets get started!
==Review the Requirements==
Please, please save yourself (and possibly your clients) a lot of headaches and make sure that your server (and in the case of jUpgrade, your browser too) is up for the task. please review the [http://docs.joomla.org/Joomla_1.6_technical_requirements technical requirements for Joomla! 1.6]. Please review the [http://www.matware.com.ar/joomla/jupgrade.html requirements for jUpgrade] as well.
==Before You Get Started==
Before you get started, there are a few things that you are going to have to check and/or think about:
# Is your Joomla 1.5 version up to date? The most up-to-date version of Joomla 1.5 is 1.5.23. If your version is not up-to-date, upgrade to 1.5.23 before migrating, especially if you are running Joomla 1.5.11 or lower.
# Do all your extensions have Joomla 1.6 native versions? At the time of the writing of this tutorial there are 108 available on the JED. Please note that jUpgrade is not currently able to upgrade Joomla 3rd party extensions, so those will have to be done via their respective upgrade procedures. This is however a work in progress.
# Have you modified any core files? Any changes that you have made to core files in Joomla will be lost so please be forewarned.
# Is there a Joomla 1.6 compatible template available from your template provider? If not, do you feel comfortable making the changes yourself? There are a couple good resources:
## [http://community.joomla.org/blogs/community/1257-16-templates.html Chad Windnagle's Joomla Community blog]
## [http://www.slideshare.net/chrisdavenport/template-changes-for-joomla-16 Chris Davenport's "Template Changes for Joomla 1.6" presentation]
## [[Upgrading a Joomla 1.5 template to Joomla 1.6|Joomla's Docs Template Tutorial]] Please note that although jUpgrade is not able to currently upgrade templates, the developers are working hard at implementing the feature.
# Is your language pack available in Joomla 1.6? [http://community.joomla.org/translations/joomla-16-translations.html Find your Joomla1 1.6 Translation].
# Do you have folder or file permissions issues in your Joomla 1.5 installation?
# Do you NEED to migrate to Joomla 1.6? Joomla 1.5 is powerful and very mature. For many people there is not a need to rush into Joomla 1.6. Joomla will continue to support Joomla 1.5 for at least another year and three months, releasing security updates and bug squashing updates when needed.
#: The two main features of Joomla 1.6 that makes it superior to Joomla 1.5 are: Access Control List (ACL) and nested categories. Gone are the days of simply having guests, registered users, authors, and editors, without being able to specify what they can and can't do in the frontend. Also, with 1.6 you can have more flexibility of organizing (and therefore displaying) your content with nicely organized categories within categories. No more being restricted to the section >> category structure. Those are all great things to have (especially the ACL), however, for many 1.5 users, it isn't needed. The main point is to decide for yourself.
#: For a massive list of changes from Joomla 1.5 to Joomla 1.6, please see [[What's new in Joomla 1.6]].

==Backup, Backup, Backup==
Skipping this part is perhaps the biggest mistake you can make. If you have a proper backup (or several) you can always revert back if needed. However, if you don't properly backup your site and something goes wrong, you are going to waste a lot of valuable time, and sometimes a lot money, getting things back to the way they were. So please backup!

==== Using Akeeba to backup ====

* Akeeba Backup produces a .jpa file

* The .jpa file contains all the folders/files and database files.

* The .jpa file also contains an installer

* Kickstart.php (from Akeeba) unpacks the .jpa file

* You then run the installer and install your site like a Joomla install.

* The installer has an option to change the configuration for restoring to a different location

After you create the Database for your Joomla download and install Akeeba, it can be download from [http://extensions.joomla.org/extensions/access-a-security/site-security/backup/1606 Joomla extension directory]. There is a link to full instructions there as well.

=Upgrading=
==Download jUpgrade==
Download the [http://www.matware.com.ar/downloads/joomla/jupgrade.html latest version of jUpgrade]. It is highly advisible, especially when development still is progressing, to always use the latest available version!

==Optional Testing Environment==
If you are really nervous by this point and your heart is beating fast, then you should probably set up a testing environment.

=== Install XAMPP ===
XAMPP is an easy-to-install package that bundles the Apache web server, PHP, XDEBUG, and the MySql database. This allows you to create the environment you need to run Joomla! on your local machine. The latest version of XAMPP is available at [http://www.apachefriends.org/en/xampp.html the XAMPP web site]. Downloads are available for Linux, Windows, Mac OS X and Solaris. Download the package for your platform.

''Important Note Regarding XAMPP and Skype:'' Apache and Skype both use port 80 as an alternative for incoming connections. If you use Skype, go into the Tools-Options-Advanced-Connection panel and deselect the "Use 80 and 443 as alternatives for incoming connections" option. If Apache starts as a service, it will take 80 before Skype starts and you will not see a problem. But, to be safe, disable the option in Skype.

'''Update'''

''As of August 5, 2010, XDebug has been updated (to version 2.1) which fixes some important bugs (for example, watching local variables for nesting functions). The latest XAMPP package (1.7.3) now includes this new version of XDebug. If you just want to update XDebug, you can download the latest module from [http://www.xdebug.org]. There is a handy website that tells you which XDebug binary you need, depending on your phpinfo() information [http://xdebug.org/find-binary.php here]. To use it, you just copy the output of your phpinfo() display and paste it into the form on the site.''

===== Installation on Windows =====

Installation for Windows is very simple. You can use the XAMPP installer executable (for example, "xampp-win32-1.7.3-installer.exe"). Detailed installation instructions for Windows are available [http://www.apachefriends.org/en/xampp-windows.html here].

For Windows, it is recommended to install XAMPP in "c:\xampp" (not in "c:\program files"). If you do this, your Joomla! (and any other local web site folders) will go into the folder "c:\xampp\htdocs". (By convention, all web content goes under the "htdocs" folder.)

If you have multiple http servers (like IIS) you can change the xampp listening port. In <xamppDir>\apache\conf\httpd.conf, modify the line Listen 80 to Listen [portnumber] (ex: "Listen 8080").

===== Installation on Linux =====

Install xammp
Open Terminal and enter:
sudo tar xvfz xampp-linux-1.7.3a.tar.gz -C /opt
(replace ''xampp-linux-1.7.3a.tar.gz'' with the version of xammp you downloaded).
It has been reported that the MYSQL database of xampp 1.7.4 does not work with Joomla 1.5.22

This installs ... Apache2, mysql and php5 as well as an ftp server.

''sudo /opt/lampp/lampp start''

and
''sudo /opt/lampp/lampp stop''

starts/stops all the services

==== Test your xammp localhost server ====
Open your Browser and point it to
http://localhost
The index.php will redirect to
http://localhost/xammp

There you will find instructions on how to change default usernames/passwords. On a PC that does not serve files to the Internet or LAN then changing the defaults is personal choice.

== Install jUpgrade ==
Go to your Joomla backend. e.g. www.yoursite.com/administrator

'''Extensions''' >> '''Install/Uninstall'''

[[Image:Installjupgrade.png|alt=Installing jUpgrade]]

'''Browse''' >> '''Select com_jupgrade''' >> '''Upload File & Install'''

[[Image:browse.png|Browse and Upload Component]]

[[Image:Installjupgrade2.png|alt=Installing jUpgrade]]

== Enable Mootools Upgrade Plugin ==
# Go to Extensions | Plugin Manager
# Search for "System - Mootools Upgrade"
# Enable the plugin
It is important that this plugin is installed and that it has been set to enabled, as the proper functioning of jUpgrade depends on it.

== Configure Options ==
As of jUpgrade version 1.1.1, support is present to migrate to Joomla! 1.6, Joomla! 1.7, and an old Molajo build. As well, for jUpgrade to be successful, you must configure your current table prefix prior to beginning the migration. The following are the options that can be configured with jUpgrade:

Global:
* Distribution - Select whether to migrate to Joomla! 1.6, 1.7, or Molajo
* Prefix for old database - Your current table prefix
* Prefix for new database - Your selected table prefix for your migrated site

Skips:
* Skip checks - Skip pre-migration checks
* Skip download - Skip downloading the package (Note: Must have a package already downloaded to your temp folder or set this and Skip Decompress if set to yes)
* Skip decompress - Skip decompressing the downloaded package (Note: Must have a package already downloaded and decompressed to site_root/jupgrade if set to Yes)

Templates:
* Keep original positions - Keep the currently defined positions for modules

Debug:
* Enable Debug - Enable this to have messages displayed below the migration process concerning the progress, helpful if having issues

[[Image:Jupgrade_options.png|alt=jUpgrade 1.1.1 Options]]

== Migration ==
'''Components''' >> '''jUpgrade'''

[[Image:Accessjupgrade.png]]

'''Start Upgrade'''

[[Image:Startjupgrade.png|alt=Start jUpgrade]]

[[Image:Runjupgrade.png|alt=Run jUpgrade]]

'''Do not exit the screen''' until everything has finished loading. Scroll down to check if finished.

[[Image:Jupgradefinished.png|alt=jUpgrade Finished]]

'''Success!!!'''

Please note that jUpgrade currently does not migrate templates, only default templates.

==Behind the Scenes==
As explained in the background information, the changes from Joomla 1.5 and 1.6 are quite significant. The fact that jUpgrade creates a new Joomla 1.6 installation for us is, in my opinion, pure genius. If the migration process was not 100% successful, your Joomla 1.5 is still perfectly intact and none of your users are affected. You have an opportunity to check out your site both in the frontend and the backend to make sure everything is up to par. So what actually happens? jUpgrade downloads the latest version of Joomla 1.6 for you to the jupgrade directory (which it creates) in the root folder of your Joomla 1.5 installation. It then extracts all the files from the download. Once extraction has completed, jUpgrade installs Joomla 1.6 and then proceeds to migrate your old database to the new Joomla 1.6 database which it has created.
Your Joomla 1.6 site will be installed in www.mysites.com/jupgrade assuming that your Joomla 1.5 installation is in your html root.
==Check Your Joomla! 1.6==
Please do a full site review of your Joomla 1.6 installation and make sure everything is set up properly.
Your Joomla 1.6 site will be installed in www.mysites.com/jupgrade assuming that your Joomla 1.5 installation is in your html root.
Here is a general checklist to check:
* Banners
* Categories
* Contacts
* Content
* Menus
* Modules
* Newsfeeds
* Users
* Weblinks
* Templates - Work is currently being done on the template upgrade feature of jUpdate and it is not yet fully functional. Your module positions may have to be adjusted in module manager.
==Backup Joomla! 1.6==
If everything looks good to go, then let's backup the new Joomla 1.6 installation.
==Overview of the Rest of the Process==
Quick overview of what we are going to try to do now:
# Relocate our Joomla 1.5 installation to a subfolder as a "just in case".
# Relocate our Joomla 1.6 installation to the html folder.
'It should happen in this order' If you do it in reverse order, the Joomla 1.6 files will get mixed with the Joomla 1.5 files (many of 1.5 files will be overwritten) and you will have a big mess! Your site will likely still work, but it's a security ticking time bomb waiting to go off.

=Going Live=
Next log onto your host's file manager (e.g. cPanel, Plesk, etc) or an FTP Client, however, preferably a file manager.
The general procedure is (it should take about 30 seconds if you review the steps before you start):
# Create a subfolder (e.g. myoldsite) for the Joomla 1.5 installation in your html root, e.g. public_html/myoldsite
# Select all the folders (***except the jupgrade folder***) and files in the html root and move them into the Joomla 1.5 subfolder (e.g. myoldsite)
# Select all the folders and files in the jupgrade folder and move them to the html root
# Double check the frontend and backend

=How to Manually Migrate Joomla=
If Jupgrade did not work out for you like many of us, you might want to consider manual upgrade. '''Be warned, however, that this process is very tedious (especially see step 6 below), and the procedure is not well tested as of yet (if at all)'''. So just like the Jupgrade method, you will want to backup your database just in case. Before upgrading you should check to make sure every extension you want is joomla 1.6/1.7 compatible. Also back up your directory files just in case and keep a list of the extensions you used.

Now onto the upgrade; please note that the following procedure should only be chosen if all else fails, and requires a good working knowledge of SQL! See the last paragraph of this section for a possibly less tedious alternative to doing steps 1, 2, 6 and 7) :

'''Step 0:''' First of all, as always before big changes, backup all your data; that includes all files as well as exporting all database tables.

'''Step 1:''' If you want, you can convert the prefixes of all the tables in your database. This is especially useful if you would like to keep your 1.5 database in parallel to your 1.6/1.7 installation, at least for the transition period. It is best done using a script, here is one that worked pretty well as seen on [http://www.nilpo.com/2009/01/web-development/mysql-table-prefix-changer-tool/ Nilop]. '''Beware''', however, that executing this script will stop your old site from working because after the prefix conversion, your old installation can't access the database anymore (it will still try to access the tables by their old prefix)! To enable it again, import the database export created in step 0 after the script has finished running. Joomla 1.5 usually has the prefix of "jos" which you can convert to the prefix "jml" or "j16", for example. So using your ftp install the php converter script onto the root of your site. It should be at the url '''Mysite.com'''/prefix.php which all you need to do is fill in the database information. After this you have all the tables nicely converted to the new prefix.

[[File:Changer.JPG|center]]

Notice in the following screen shot that the sql data is "jos":
[[File:Tables.JPG|thumb|center|500px]]

You want it converted to "jml" as seen here:
[[File:Prefix.JPG|thumb|center|500px]]

'''Step 2:''' Export all the database tables you would like to use on your joomla 1.6+ site. Usually this is things like content and components.

[[File:Export.JPG|thumb|center|500px]]

'''Step 3:''' Uninstall your old site including the database, files, and directories that are associated with joomla. Or if you would rather just test the upgrade, skip step this step and create a new directory for your joomla 1.6+ site.

'''Step 4:''' Install the new joomla which is done through a ftp or a cpanel. If you have no database associated with it, install a new database and user.

'''Step 5:''' Install the components and other extensions you would have used before onto your new joomla 1.6+ site. This is done first, in order for none of your old database tables to be overwritten later.

'''Step 6: ''' Convert the .sql file with your 1.5 tables to an sql file compatible with the version you want to upgrade to. That is a very tedious step - you'll have to check the database schema changes between the 1.5 you're upgrading from and the 1.6.+ version you're upgrading to, and adapt the sql file accordingly. '''Note:''' This step could use a more detailed description, if you have ever done a manual Joomla migration, please help and share your experiences and knowledge here!

'''Step 7:''' Import the .sql file from your computer onto your joomla 1.6+ database. It is also possible that some extensions may have the possibility of changes to the sql tables when they upgraded there extension to joomla 1.6+. If this is the case, it is recommended that you ask the developer of that extension for help with knowing what changes to the sql were made.

'''Keep in mind!''' It is possible for settings to be lost based on how the component stored the settings. From personal experience it worked just fine, but you may want to review the settings of each component.

For an easier way to migrate articles, categories/sections, contacts, images, and users, be sure to use [http://extensions.joomla.org/extensions/migration-a-conversion/data-import-a-export/12816 J2XML] for exporting and [http://extensions.joomla.org/extensions/migration-a-conversion/joomla-migration/15807 J2XML Importer] for importing the data.

=Troubleshooting=
* first check, if you have php5 at least. (use phpinfo() or /usr/bin/php --version)
* '''jUpgrade cannot download Joomla 1.6 package?''' - When the download fails (timeouts, javascript issues, etc) you can download it manually here: http://anonymous:@joomlacode.org/svn/joomla/development/branches/jupgrade/pack/joomla16.zip and put this file into your ROOT/tmp directory. Then, in the preferences of jUpgrade, you must set 'Skip Download' to 'Yes'. After that, run the upgrade again.
* '''Are you getting errors with the progress bar in Internet Explorer (Windows XP)?''' - Use Firefox: http://www.mozilla.com/en-US/firefox/
* Go through the Requirements and Before You Get Started sections above and double check everything!
* '''Report Bugs:''' http://matware.com.ar/foros/jupgrade.html
* '''Support:''' http://matware.com.ar/foros/jupgrade.html
==How You can Contribute & Help==
Creating an extension as significant as jUpgrade requires an enormous amount of time and effort considering the major structural changes between Joomla 1.5 and 1.6. Add to this the fact that during each release of Joomla 1.6 betas, the extension would have to be modified to work with the new changes between releases, and all of a sudden it's too hard for any one person to complete in a short period of time (especially when you are not being paid).
With this being said, it's time to step up and make a difference, whether big or small. Have you profited from Joomla in the last year? Are you excited about the future of Joomla? Would you like to contribute back and show your gratitude? Now you can in this project!
We, as part of the Joomla community, are calling on the entire Joomla community to help out in whatever way you can. You don't have to be a master developer, just go through this tutorial on a test site and if you come across any bugs, report it. If you know how to fix it, create a patch for it. If you are a master developer, step up to the challenge.
* You can report bugs here: http://matware.com.ar/foros/jupgrade.html
* You can volunteer and ask questions about volunteering here: http://www.matware.com.ar/forum/projects/jupgrade/volunteer-information.html
[[Category:Joomla! 1.6]]
[[Category:Tutorials]]
[[Category:Migration]]
[[Category:Installation]]

Migrating from Joomla 1.5 to Joomla 1.6+

2011-10-18T11:57:12Z

Munchkin: /* How to Manually Upgrade Joomla */ upgrade -> migration, warning that manual migration might be very tedious

With Joomla 1.6 officially released, there have been a lot of questions as to how to migrate or upgrade to Joomla 1.6 from 1.5. This guide will take you step-by-step through the general procedure of how to migrate to Joomla 1.6.
Please read through all the material as this is not a light undertaking.
=Before Upgrading=
Don't let the numerical closeness of 1.5 and 1.6, mislead you. Joomla 1.6 took three years to develop and has been a major undertaking. Countless hours have been spent by many volunteers from around the world to put it all together. Although much of the code is the same from Joomla 1.5, much of it has been written from the ground up, and the changes are comparable to the changes from Joomla 1.0 to 1.5.
Because the changes from Joomla 1.5 to 1.6 are so large and because of the massive effort put into getting Joomla 1.6 to where it is today, there is no core upgrade path, this is indeed a migration. In planned future releases of Joomla (which will be released every 6 months), such as Joomla 1.7, 1.8, etc, the changes from version to version will be more incremental and a core upgrade path is planned.
Now that Joomla 1.6 is finally here and stable, a community initiative led by the developers of Joomla is turning towards [http://extensions.joomla.org/extensions/migration-a-conversion/joomla-migration/11658 jUpgrade] (a 3rd party Joomla extension on the JED originally developed by Matias Aguirre) for help and to help. Many of Joomla's developers (who are all volunteers that freely contribute their time) are volunteering to put the finishing touches on [http://extensions.joomla.org/extensions/migration-a-conversion/joomla-migration/11658 jUpgrade].

[http://extensions.joomla.org/extensions/migration-a-conversion/joomla-migration/11658 jUpgrade] allows you to migrate from Joomla 1.5 to 1.6.
Lets get started!
==Review the Requirements==
Please, please save yourself (and possibly your clients) a lot of headaches and make sure that your server (and in the case of jUpgrade, your browser too) is up for the task. please review the [http://docs.joomla.org/Joomla_1.6_technical_requirements technical requirements for Joomla! 1.6]. Please review the [http://www.matware.com.ar/joomla/jupgrade.html requirements for jUpgrade] as well.
==Before You Get Started==
Before you get started, there are a few things that you are going to have to check and/or think about:
# Is your Joomla 1.5 version up to date? The most up-to-date version of Joomla 1.5 is 1.5.23. If your version is not up-to-date, upgrade to 1.5.23 before migrating, especially if you are running Joomla 1.5.11 or lower.
# Do all your extensions have Joomla 1.6 native versions? At the time of the writing of this tutorial there are 108 available on the JED. Please note that jUpgrade is not currently able to upgrade Joomla 3rd party extensions, so those will have to be done via their respective upgrade procedures. This is however a work in progress.
# Have you modified any core files? Any changes that you have made to core files in Joomla will be lost so please be forewarned.
# Is there a Joomla 1.6 compatible template available from your template provider? If not, do you feel comfortable making the changes yourself? There are a couple good resources:
## [http://community.joomla.org/blogs/community/1257-16-templates.html Chad Windnagle's Joomla Community blog]
## [http://www.slideshare.net/chrisdavenport/template-changes-for-joomla-16 Chris Davenport's "Template Changes for Joomla 1.6" presentation]
## [[Upgrading a Joomla 1.5 template to Joomla 1.6|Joomla's Docs Template Tutorial]] Please note that although jUpgrade is not able to currently upgrade templates, the developers are working hard at implementing the feature.
# Is your language pack available in Joomla 1.6? [http://community.joomla.org/translations/joomla-16-translations.html Find your Joomla1 1.6 Translation].
# Do you have folder or file permissions issues in your Joomla 1.5 installation?
# Do you NEED to migrate to Joomla 1.6? Joomla 1.5 is powerful and very mature. For many people there is not a need to rush into Joomla 1.6. Joomla will continue to support Joomla 1.5 for at least another year and three months, releasing security updates and bug squashing updates when needed.
#: The two main features of Joomla 1.6 that makes it superior to Joomla 1.5 are: Access Control List (ACL) and nested categories. Gone are the days of simply having guests, registered users, authors, and editors, without being able to specify what they can and can't do in the frontend. Also, with 1.6 you can have more flexibility of organizing (and therefore displaying) your content with nicely organized categories within categories. No more being restricted to the section >> category structure. Those are all great things to have (especially the ACL), however, for many 1.5 users, it isn't needed. The main point is to decide for yourself.
#: For a massive list of changes from Joomla 1.5 to Joomla 1.6, please see [[What's new in Joomla 1.6]].

==Backup, Backup, Backup==
Skipping this part is perhaps the biggest mistake you can make. If you have a proper backup (or several) you can always revert back if needed. However, if you don't properly backup your site and something goes wrong, you are going to waste a lot of valuable time, and sometimes a lot money, getting things back to the way they were. So please backup!

==== Using Akeeba to backup ====

* Akeeba Backup produces a .jpa file

* The .jpa file contains all the folders/files and database files.

* The .jpa file also contains an installer

* Kickstart.php (from Akeeba) unpacks the .jpa file

* You then run the installer and install your site like a Joomla install.

* The installer has an option to change the configuration for restoring to a different location

After you create the Database for your Joomla download and install Akeeba, it can be download from [http://extensions.joomla.org/extensions/access-a-security/site-security/backup/1606 Joomla extension directory]. There is a link to full instructions there as well.

=Upgrading=
==Download jUpgrade==
Download the [http://www.matware.com.ar/downloads/joomla/jupgrade.html latest version of jUpgrade]. It is highly advisible, especially when development still is progressing, to always use the latest available version!

==Optional Testing Environment==
If you are really nervous by this point and your heart is beating fast, then you should probably set up a testing environment.

=== Install XAMPP ===
XAMPP is an easy-to-install package that bundles the Apache web server, PHP, XDEBUG, and the MySql database. This allows you to create the environment you need to run Joomla! on your local machine. The latest version of XAMPP is available at [http://www.apachefriends.org/en/xampp.html the XAMPP web site]. Downloads are available for Linux, Windows, Mac OS X and Solaris. Download the package for your platform.

''Important Note Regarding XAMPP and Skype:'' Apache and Skype both use port 80 as an alternative for incoming connections. If you use Skype, go into the Tools-Options-Advanced-Connection panel and deselect the "Use 80 and 443 as alternatives for incoming connections" option. If Apache starts as a service, it will take 80 before Skype starts and you will not see a problem. But, to be safe, disable the option in Skype.

'''Update'''

''As of August 5, 2010, XDebug has been updated (to version 2.1) which fixes some important bugs (for example, watching local variables for nesting functions). The latest XAMPP package (1.7.3) now includes this new version of XDebug. If you just want to update XDebug, you can download the latest module from [http://www.xdebug.org]. There is a handy website that tells you which XDebug binary you need, depending on your phpinfo() information [http://xdebug.org/find-binary.php here]. To use it, you just copy the output of your phpinfo() display and paste it into the form on the site.''

===== Installation on Windows =====

Installation for Windows is very simple. You can use the XAMPP installer executable (for example, "xampp-win32-1.7.3-installer.exe"). Detailed installation instructions for Windows are available [http://www.apachefriends.org/en/xampp-windows.html here].

For Windows, it is recommended to install XAMPP in "c:\xampp" (not in "c:\program files"). If you do this, your Joomla! (and any other local web site folders) will go into the folder "c:\xampp\htdocs". (By convention, all web content goes under the "htdocs" folder.)

If you have multiple http servers (like IIS) you can change the xampp listening port. In <xamppDir>\apache\conf\httpd.conf, modify the line Listen 80 to Listen [portnumber] (ex: "Listen 8080").

===== Installation on Linux =====

Install xammp
Open Terminal and enter:
sudo tar xvfz xampp-linux-1.7.3a.tar.gz -C /opt
(replace ''xampp-linux-1.7.3a.tar.gz'' with the version of xammp you downloaded).
It has been reported that the MYSQL database of xampp 1.7.4 does not work with Joomla 1.5.22

This installs ... Apache2, mysql and php5 as well as an ftp server.

''sudo /opt/lampp/lampp start''

and
''sudo /opt/lampp/lampp stop''

starts/stops all the services

==== Test your xammp localhost server ====
Open your Browser and point it to
http://localhost
The index.php will redirect to
http://localhost/xammp

There you will find instructions on how to change default usernames/passwords. On a PC that does not serve files to the Internet or LAN then changing the defaults is personal choice.

== Install jUpgrade ==
Go to your Joomla backend. e.g. www.yoursite.com/administrator

'''Extensions''' >> '''Install/Uninstall'''

[[Image:Installjupgrade.png|alt=Installing jUpgrade]]

'''Browse''' >> '''Select com_jupgrade''' >> '''Upload File & Install'''

[[Image:browse.png|Browse and Upload Component]]

[[Image:Installjupgrade2.png|alt=Installing jUpgrade]]

== Enable Mootools Upgrade Plugin ==
# Go to Extensions | Plugin Manager
# Search for "System - Mootools Upgrade"
# Enable the plugin
It is important that this plugin is installed and that it has been set to enabled, as the proper functioning of jUpgrade depends on it.

== Configure Options ==
As of jUpgrade version 1.1.1, support is present to migrate to Joomla! 1.6, Joomla! 1.7, and an old Molajo build. As well, for jUpgrade to be successful, you must configure your current table prefix prior to beginning the migration. The following are the options that can be configured with jUpgrade:

Global:
* Distribution - Select whether to migrate to Joomla! 1.6, 1.7, or Molajo
* Prefix for old database - Your current table prefix
* Prefix for new database - Your selected table prefix for your migrated site

Skips:
* Skip checks - Skip pre-migration checks
* Skip download - Skip downloading the package (Note: Must have a package already downloaded to your temp folder or set this and Skip Decompress if set to yes)
* Skip decompress - Skip decompressing the downloaded package (Note: Must have a package already downloaded and decompressed to site_root/jupgrade if set to Yes)

Templates:
* Keep original positions - Keep the currently defined positions for modules

Debug:
* Enable Debug - Enable this to have messages displayed below the migration process concerning the progress, helpful if having issues

[[Image:Jupgrade_options.png|alt=jUpgrade 1.1.1 Options]]

== Migration ==
'''Components''' >> '''jUpgrade'''

[[Image:Accessjupgrade.png]]

'''Start Upgrade'''

[[Image:Startjupgrade.png|alt=Start jUpgrade]]

[[Image:Runjupgrade.png|alt=Run jUpgrade]]

'''Do not exit the screen''' until everything has finished loading. Scroll down to check if finished.

[[Image:Jupgradefinished.png|alt=jUpgrade Finished]]

'''Success!!!'''

Please note that jUpgrade currently does not migrate templates, only default templates.

==Behind the Scenes==
As explained in the background information, the changes from Joomla 1.5 and 1.6 are quite significant. The fact that jUpgrade creates a new Joomla 1.6 installation for us is, in my opinion, pure genius. If the migration process was not 100% successful, your Joomla 1.5 is still perfectly intact and none of your users are affected. You have an opportunity to check out your site both in the frontend and the backend to make sure everything is up to par. So what actually happens? jUpgrade downloads the latest version of Joomla 1.6 for you to the jupgrade directory (which it creates) in the root folder of your Joomla 1.5 installation. It then extracts all the files from the download. Once extraction has completed, jUpgrade installs Joomla 1.6 and then proceeds to migrate your old database to the new Joomla 1.6 database which it has created.
Your Joomla 1.6 site will be installed in www.mysites.com/jupgrade assuming that your Joomla 1.5 installation is in your html root.
==Check Your Joomla! 1.6==
Please do a full site review of your Joomla 1.6 installation and make sure everything is set up properly.
Your Joomla 1.6 site will be installed in www.mysites.com/jupgrade assuming that your Joomla 1.5 installation is in your html root.
Here is a general checklist to check:
* Banners
* Categories
* Contacts
* Content
* Menus
* Modules
* Newsfeeds
* Users
* Weblinks
* Templates - Work is currently being done on the template upgrade feature of jUpdate and it is not yet fully functional. Your module positions may have to be adjusted in module manager.
==Backup Joomla! 1.6==
If everything looks good to go, then let's backup the new Joomla 1.6 installation.
==Overview of the Rest of the Process==
Quick overview of what we are going to try to do now:
# Relocate our Joomla 1.5 installation to a subfolder as a "just in case".
# Relocate our Joomla 1.6 installation to the html folder.
'It should happen in this order' If you do it in reverse order, the Joomla 1.6 files will get mixed with the Joomla 1.5 files (many of 1.5 files will be overwritten) and you will have a big mess! Your site will likely still work, but it's a security ticking time bomb waiting to go off.

=Going Live=
Next log onto your host's file manager (e.g. cPanel, Plesk, etc) or an FTP Client, however, preferably a file manager.
The general procedure is (it should take about 30 seconds if you review the steps before you start):
# Create a subfolder (e.g. myoldsite) for the Joomla 1.5 installation in your html root, e.g. public_html/myoldsite
# Select all the folders (***except the jupgrade folder***) and files in the html root and move them into the Joomla 1.5 subfolder (e.g. myoldsite)
# Select all the folders and files in the jupgrade folder and move them to the html root
# Double check the frontend and backend

=How to Manually Migrate Joomla=
If Jupgrade did not work out for you like many of us, you might want to consider manual upgrade. Be warned, however, that this process is very tedious (especially see step 6 below), and the procedure is not well tested as of yet (if at all). So just like the Jupgrade method, you will want to backup your database just in case. Before upgrading you should check to make sure every extension you want is joomla 1.6/1.7 compatible. Also back up your directory files just in case and keep a list of the extensions you used.

Now onto the upgrade; please note that the following procedure should only be chosen if all else fails, and requires a good working knowledge of SQL! See the last paragraph of this section for a possibly less tedious alternative to doing steps 1, 2, 6 and 7) :

'''Step 0:''' First of all, as always before big changes, backup all your data; that includes all files as well as exporting all database tables.

'''Step 1:''' If you want, you can convert the prefixes of all the tables in your database. This is especially useful if you would like to keep your 1.5 database in parallel to your 1.6/1.7 installation, at least for the transition period. It is best done using a script, here is one that worked pretty well as seen on [http://www.nilpo.com/2009/01/web-development/mysql-table-prefix-changer-tool/ Nilop]. '''Beware''', however, that executing this script will stop your old site from working because after the prefix conversion, your old installation can't access the database anymore (it will still try to access the tables by their old prefix)! To enable it again, import the database export created in step 0 after the script has finished running. Joomla 1.5 usually has the prefix of "jos" which you can convert to the prefix "jml" or "j16", for example. So using your ftp install the php converter script onto the root of your site. It should be at the url '''Mysite.com'''/prefix.php which all you need to do is fill in the database information. After this you have all the tables nicely converted to the new prefix.

[[File:Changer.JPG|center]]

Notice in the following screen shot that the sql data is "jos":
[[File:Tables.JPG|thumb|center|500px]]

You want it converted to "jml" as seen here:
[[File:Prefix.JPG|thumb|center|500px]]

'''Step 2:''' Export all the database tables you would like to use on your joomla 1.6+ site. Usually this is things like content and components.

[[File:Export.JPG|thumb|center|500px]]

'''Step 3:''' Uninstall your old site including the database, files, and directories that are associated with joomla. Or if you would rather just test the upgrade, skip step this step and create a new directory for your joomla 1.6+ site.

'''Step 4:''' Install the new joomla which is done through a ftp or a cpanel. If you have no database associated with it, install a new database and user.

'''Step 5:''' Install the components and other extensions you would have used before onto your new joomla 1.6+ site. This is done first, in order for none of your old database tables to be overwritten later.

'''Step 6: ''' Convert the .sql file with your 1.5 tables to an sql file compatible with the version you want to upgrade to. That is a very tedious step - you'll have to check the database schema changes between the 1.5 you're upgrading from and the 1.6.+ version you're upgrading to, and adapt the sql file accordingly. '''Note:''' This step could use a more detailed description, if you have ever done a manual Joomla migration, please help and share your experiences and knowledge here!

'''Step 7:''' Import the .sql file from your computer onto your joomla 1.6+ database. It is also possible that some extensions may have the possibility of changes to the sql tables when they upgraded there extension to joomla 1.6+. If this is the case, it is recommended that you ask the developer of that extension for help with knowing what changes to the sql were made.

'''Keep in mind!''' It is possible for settings to be lost based on how the component stored the settings. From personal experience it worked just fine, but you may want to review the settings of each component.

For an easier way to migrate articles, categories/sections, contacts, images, and users, be sure to use [http://extensions.joomla.org/extensions/migration-a-conversion/data-import-a-export/12816 J2XML] for exporting and [http://extensions.joomla.org/extensions/migration-a-conversion/joomla-migration/15807 J2XML Importer] for importing the data.

=Troubleshooting=
* first check, if you have php5 at least. (use phpinfo() or /usr/bin/php --version)
* '''jUpgrade cannot download Joomla 1.6 package?''' - When the download fails (timeouts, javascript issues, etc) you can download it manually here: http://anonymous:@joomlacode.org/svn/joomla/development/branches/jupgrade/pack/joomla16.zip and put this file into your ROOT/tmp directory. Then, in the preferences of jUpgrade, you must set 'Skip Download' to 'Yes'. After that, run the upgrade again.
* '''Are you getting errors with the progress bar in Internet Explorer (Windows XP)?''' - Use Firefox: http://www.mozilla.com/en-US/firefox/
* Go through the Requirements and Before You Get Started sections above and double check everything!
* '''Report Bugs:''' http://matware.com.ar/foros/jupgrade.html
* '''Support:''' http://matware.com.ar/foros/jupgrade.html
==How You can Contribute & Help==
Creating an extension as significant as jUpgrade requires an enormous amount of time and effort considering the major structural changes between Joomla 1.5 and 1.6. Add to this the fact that during each release of Joomla 1.6 betas, the extension would have to be modified to work with the new changes between releases, and all of a sudden it's too hard for any one person to complete in a short period of time (especially when you are not being paid).
With this being said, it's time to step up and make a difference, whether big or small. Have you profited from Joomla in the last year? Are you excited about the future of Joomla? Would you like to contribute back and show your gratitude? Now you can in this project!
We, as part of the Joomla community, are calling on the entire Joomla community to help out in whatever way you can. You don't have to be a master developer, just go through this tutorial on a test site and if you come across any bugs, report it. If you know how to fix it, create a patch for it. If you are a master developer, step up to the challenge.
* You can report bugs here: http://matware.com.ar/foros/jupgrade.html
* You can volunteer and ask questions about volunteering here: http://www.matware.com.ar/forum/projects/jupgrade/volunteer-information.html
[[Category:Joomla! 1.6]]
[[Category:Tutorials]]
[[Category:Migration]]
[[Category:Installation]]

Migrating from Joomla 1.5 to Joomla 1.6+

2011-10-18T11:29:09Z

Munchkin: /* How to Manually Upgrade Joomla */ db upgrade - slightly more detailed instructions / clarifications

With Joomla 1.6 officially released, there have been a lot of questions as to how to migrate or upgrade to Joomla 1.6 from 1.5. This guide will take you step-by-step through the general procedure of how to migrate to Joomla 1.6.
Please read through all the material as this is not a light undertaking.
=Before Upgrading=
Don't let the numerical closeness of 1.5 and 1.6, mislead you. Joomla 1.6 took three years to develop and has been a major undertaking. Countless hours have been spent by many volunteers from around the world to put it all together. Although much of the code is the same from Joomla 1.5, much of it has been written from the ground up, and the changes are comparable to the changes from Joomla 1.0 to 1.5.
Because the changes from Joomla 1.5 to 1.6 are so large and because of the massive effort put into getting Joomla 1.6 to where it is today, there is no core upgrade path, this is indeed a migration. In planned future releases of Joomla (which will be released every 6 months), such as Joomla 1.7, 1.8, etc, the changes from version to version will be more incremental and a core upgrade path is planned.
Now that Joomla 1.6 is finally here and stable, a community initiative led by the developers of Joomla is turning towards [http://extensions.joomla.org/extensions/migration-a-conversion/joomla-migration/11658 jUpgrade] (a 3rd party Joomla extension on the JED originally developed by Matias Aguirre) for help and to help. Many of Joomla's developers (who are all volunteers that freely contribute their time) are volunteering to put the finishing touches on [http://extensions.joomla.org/extensions/migration-a-conversion/joomla-migration/11658 jUpgrade].

[http://extensions.joomla.org/extensions/migration-a-conversion/joomla-migration/11658 jUpgrade] allows you to migrate from Joomla 1.5 to 1.6.
Lets get started!
==Review the Requirements==
Please, please save yourself (and possibly your clients) a lot of headaches and make sure that your server (and in the case of jUpgrade, your browser too) is up for the task. please review the [http://docs.joomla.org/Joomla_1.6_technical_requirements technical requirements for Joomla! 1.6]. Please review the [http://www.matware.com.ar/joomla/jupgrade.html requirements for jUpgrade] as well.
==Before You Get Started==
Before you get started, there are a few things that you are going to have to check and/or think about:
# Is your Joomla 1.5 version up to date? The most up-to-date version of Joomla 1.5 is 1.5.23. If your version is not up-to-date, upgrade to 1.5.23 before migrating, especially if you are running Joomla 1.5.11 or lower.
# Do all your extensions have Joomla 1.6 native versions? At the time of the writing of this tutorial there are 108 available on the JED. Please note that jUpgrade is not currently able to upgrade Joomla 3rd party extensions, so those will have to be done via their respective upgrade procedures. This is however a work in progress.
# Have you modified any core files? Any changes that you have made to core files in Joomla will be lost so please be forewarned.
# Is there a Joomla 1.6 compatible template available from your template provider? If not, do you feel comfortable making the changes yourself? There are a couple good resources:
## [http://community.joomla.org/blogs/community/1257-16-templates.html Chad Windnagle's Joomla Community blog]
## [http://www.slideshare.net/chrisdavenport/template-changes-for-joomla-16 Chris Davenport's "Template Changes for Joomla 1.6" presentation]
## [[Upgrading a Joomla 1.5 template to Joomla 1.6|Joomla's Docs Template Tutorial]] Please note that although jUpgrade is not able to currently upgrade templates, the developers are working hard at implementing the feature.
# Is your language pack available in Joomla 1.6? [http://community.joomla.org/translations/joomla-16-translations.html Find your Joomla1 1.6 Translation].
# Do you have folder or file permissions issues in your Joomla 1.5 installation?
# Do you NEED to migrate to Joomla 1.6? Joomla 1.5 is powerful and very mature. For many people there is not a need to rush into Joomla 1.6. Joomla will continue to support Joomla 1.5 for at least another year and three months, releasing security updates and bug squashing updates when needed.
#: The two main features of Joomla 1.6 that makes it superior to Joomla 1.5 are: Access Control List (ACL) and nested categories. Gone are the days of simply having guests, registered users, authors, and editors, without being able to specify what they can and can't do in the frontend. Also, with 1.6 you can have more flexibility of organizing (and therefore displaying) your content with nicely organized categories within categories. No more being restricted to the section >> category structure. Those are all great things to have (especially the ACL), however, for many 1.5 users, it isn't needed. The main point is to decide for yourself.
#: For a massive list of changes from Joomla 1.5 to Joomla 1.6, please see [[What's new in Joomla 1.6]].

==Backup, Backup, Backup==
Skipping this part is perhaps the biggest mistake you can make. If you have a proper backup (or several) you can always revert back if needed. However, if you don't properly backup your site and something goes wrong, you are going to waste a lot of valuable time, and sometimes a lot money, getting things back to the way they were. So please backup!

==== Using Akeeba to backup ====

* Akeeba Backup produces a .jpa file

* The .jpa file contains all the folders/files and database files.

* The .jpa file also contains an installer

* Kickstart.php (from Akeeba) unpacks the .jpa file

* You then run the installer and install your site like a Joomla install.

* The installer has an option to change the configuration for restoring to a different location

After you create the Database for your Joomla download and install Akeeba, it can be download from [http://extensions.joomla.org/extensions/access-a-security/site-security/backup/1606 Joomla extension directory]. There is a link to full instructions there as well.

=Upgrading=
==Download jUpgrade==
Download the [http://www.matware.com.ar/downloads/joomla/jupgrade.html latest version of jUpgrade]. It is highly advisible, especially when development still is progressing, to always use the latest available version!

==Optional Testing Environment==
If you are really nervous by this point and your heart is beating fast, then you should probably set up a testing environment.

=== Install XAMPP ===
XAMPP is an easy-to-install package that bundles the Apache web server, PHP, XDEBUG, and the MySql database. This allows you to create the environment you need to run Joomla! on your local machine. The latest version of XAMPP is available at [http://www.apachefriends.org/en/xampp.html the XAMPP web site]. Downloads are available for Linux, Windows, Mac OS X and Solaris. Download the package for your platform.

''Important Note Regarding XAMPP and Skype:'' Apache and Skype both use port 80 as an alternative for incoming connections. If you use Skype, go into the Tools-Options-Advanced-Connection panel and deselect the "Use 80 and 443 as alternatives for incoming connections" option. If Apache starts as a service, it will take 80 before Skype starts and you will not see a problem. But, to be safe, disable the option in Skype.

'''Update'''

''As of August 5, 2010, XDebug has been updated (to version 2.1) which fixes some important bugs (for example, watching local variables for nesting functions). The latest XAMPP package (1.7.3) now includes this new version of XDebug. If you just want to update XDebug, you can download the latest module from [http://www.xdebug.org]. There is a handy website that tells you which XDebug binary you need, depending on your phpinfo() information [http://xdebug.org/find-binary.php here]. To use it, you just copy the output of your phpinfo() display and paste it into the form on the site.''

===== Installation on Windows =====

Installation for Windows is very simple. You can use the XAMPP installer executable (for example, "xampp-win32-1.7.3-installer.exe"). Detailed installation instructions for Windows are available [http://www.apachefriends.org/en/xampp-windows.html here].

For Windows, it is recommended to install XAMPP in "c:\xampp" (not in "c:\program files"). If you do this, your Joomla! (and any other local web site folders) will go into the folder "c:\xampp\htdocs". (By convention, all web content goes under the "htdocs" folder.)

If you have multiple http servers (like IIS) you can change the xampp listening port. In <xamppDir>\apache\conf\httpd.conf, modify the line Listen 80 to Listen [portnumber] (ex: "Listen 8080").

===== Installation on Linux =====

Install xammp
Open Terminal and enter:
sudo tar xvfz xampp-linux-1.7.3a.tar.gz -C /opt
(replace ''xampp-linux-1.7.3a.tar.gz'' with the version of xammp you downloaded).
It has been reported that the MYSQL database of xampp 1.7.4 does not work with Joomla 1.5.22

This installs ... Apache2, mysql and php5 as well as an ftp server.

''sudo /opt/lampp/lampp start''

and
''sudo /opt/lampp/lampp stop''

starts/stops all the services

==== Test your xammp localhost server ====
Open your Browser and point it to
http://localhost
The index.php will redirect to
http://localhost/xammp

There you will find instructions on how to change default usernames/passwords. On a PC that does not serve files to the Internet or LAN then changing the defaults is personal choice.

== Install jUpgrade ==
Go to your Joomla backend. e.g. www.yoursite.com/administrator

'''Extensions''' >> '''Install/Uninstall'''

[[Image:Installjupgrade.png|alt=Installing jUpgrade]]

'''Browse''' >> '''Select com_jupgrade''' >> '''Upload File & Install'''

[[Image:browse.png|Browse and Upload Component]]

[[Image:Installjupgrade2.png|alt=Installing jUpgrade]]

== Enable Mootools Upgrade Plugin ==
# Go to Extensions | Plugin Manager
# Search for "System - Mootools Upgrade"
# Enable the plugin
It is important that this plugin is installed and that it has been set to enabled, as the proper functioning of jUpgrade depends on it.

== Configure Options ==
As of jUpgrade version 1.1.1, support is present to migrate to Joomla! 1.6, Joomla! 1.7, and an old Molajo build. As well, for jUpgrade to be successful, you must configure your current table prefix prior to beginning the migration. The following are the options that can be configured with jUpgrade:

Global:
* Distribution - Select whether to migrate to Joomla! 1.6, 1.7, or Molajo
* Prefix for old database - Your current table prefix
* Prefix for new database - Your selected table prefix for your migrated site

Skips:
* Skip checks - Skip pre-migration checks
* Skip download - Skip downloading the package (Note: Must have a package already downloaded to your temp folder or set this and Skip Decompress if set to yes)
* Skip decompress - Skip decompressing the downloaded package (Note: Must have a package already downloaded and decompressed to site_root/jupgrade if set to Yes)

Templates:
* Keep original positions - Keep the currently defined positions for modules

Debug:
* Enable Debug - Enable this to have messages displayed below the migration process concerning the progress, helpful if having issues

[[Image:Jupgrade_options.png|alt=jUpgrade 1.1.1 Options]]

== Migration ==
'''Components''' >> '''jUpgrade'''

[[Image:Accessjupgrade.png]]

'''Start Upgrade'''

[[Image:Startjupgrade.png|alt=Start jUpgrade]]

[[Image:Runjupgrade.png|alt=Run jUpgrade]]

'''Do not exit the screen''' until everything has finished loading. Scroll down to check if finished.

[[Image:Jupgradefinished.png|alt=jUpgrade Finished]]

'''Success!!!'''

Please note that jUpgrade currently does not migrate templates, only default templates.

==Behind the Scenes==
As explained in the background information, the changes from Joomla 1.5 and 1.6 are quite significant. The fact that jUpgrade creates a new Joomla 1.6 installation for us is, in my opinion, pure genius. If the migration process was not 100% successful, your Joomla 1.5 is still perfectly intact and none of your users are affected. You have an opportunity to check out your site both in the frontend and the backend to make sure everything is up to par. So what actually happens? jUpgrade downloads the latest version of Joomla 1.6 for you to the jupgrade directory (which it creates) in the root folder of your Joomla 1.5 installation. It then extracts all the files from the download. Once extraction has completed, jUpgrade installs Joomla 1.6 and then proceeds to migrate your old database to the new Joomla 1.6 database which it has created.
Your Joomla 1.6 site will be installed in www.mysites.com/jupgrade assuming that your Joomla 1.5 installation is in your html root.
==Check Your Joomla! 1.6==
Please do a full site review of your Joomla 1.6 installation and make sure everything is set up properly.
Your Joomla 1.6 site will be installed in www.mysites.com/jupgrade assuming that your Joomla 1.5 installation is in your html root.
Here is a general checklist to check:
* Banners
* Categories
* Contacts
* Content
* Menus
* Modules
* Newsfeeds
* Users
* Weblinks
* Templates - Work is currently being done on the template upgrade feature of jUpdate and it is not yet fully functional. Your module positions may have to be adjusted in module manager.
==Backup Joomla! 1.6==
If everything looks good to go, then let's backup the new Joomla 1.6 installation.
==Overview of the Rest of the Process==
Quick overview of what we are going to try to do now:
# Relocate our Joomla 1.5 installation to a subfolder as a "just in case".
# Relocate our Joomla 1.6 installation to the html folder.
'It should happen in this order' If you do it in reverse order, the Joomla 1.6 files will get mixed with the Joomla 1.5 files (many of 1.5 files will be overwritten) and you will have a big mess! Your site will likely still work, but it's a security ticking time bomb waiting to go off.

=Going Live=
Next log onto your host's file manager (e.g. cPanel, Plesk, etc) or an FTP Client, however, preferably a file manager.
The general procedure is (it should take about 30 seconds if you review the steps before you start):
# Create a subfolder (e.g. myoldsite) for the Joomla 1.5 installation in your html root, e.g. public_html/myoldsite
# Select all the folders (***except the jupgrade folder***) and files in the html root and move them into the Joomla 1.5 subfolder (e.g. myoldsite)
# Select all the folders and files in the jupgrade folder and move them to the html root
# Double check the frontend and backend

=How to Manually Upgrade Joomla=
If Jupgrade did not work out for you like many of us, don't worry there is an alternative method to upgrading. Unfortunately it is indeed rather tedious (especially step 6), but works perhaps 99% of the time. So just like the Jupgrade method, you will want to backup your database just in case. Before upgrading you should check to make sure every extension you want is joomla 1.6/1.7 compatible. Also back up your directory files just in case and keep a list of the extensions you used.

Now onto the upgrade:

'''Step 0:''' First of all, as always before big changes, backup all your data; that includes all files as well as exporting all database tables.

'''Step 1:''' If you want, you can convert the prefixes of all the tables in your database. This is especially useful if you would like to keep your 1.5 database in parallel to your 1.6/1.7 installation, at least for the transition period. It is best done using a script, here is one that worked pretty well as seen on [http://www.nilpo.com/2009/01/web-development/mysql-table-prefix-changer-tool/ Nilop]. Beware, however, that executing this script will stop your old site from working because after the prefix conversion, your old installation can't access the database anymore (it will still try to access the tables by their old prefix)! To enable it again, import the database export created in step 0 after the script has finished running. Joomla 1.5 usually has the prefix of "jos" which you can convert to the prefix "jml" or "j16", for example. So using your ftp install the php converter script onto the root of your site. It should be at the url '''Mysite.com'''/prefix.php which all you need to do is fill in the database information. After this you have all the tables nicely converted to the new prefix.

[[File:Changer.JPG|center]]

Notice in the following screen shot that the sql data is "jos":
[[File:Tables.JPG|thumb|center|500px]]

You want it converted to "jml" as seen here:
[[File:Prefix.JPG|thumb|center|500px]]

'''Step 2:''' Export all the database tables you would like to use on your joomla 1.6+ site. Usually this is things like content and components.

[[File:Export.JPG|thumb|center|500px]]

'''Step 3:''' Uninstall your old site including the database, files, and directories that are associated with joomla. Or if you would rather just test the upgrade, skip step this step and create a new directory for your joomla 1.6+ site.

'''Step 4:''' Install the new joomla which is done through a ftp or a cpanel. If you have no database associated with it, install a new database and user.

'''Step 5:''' Install the components and other extensions you would have used before onto your new joomla 1.6+ site. This is done first in order for non of your old database tables to be over written later.

'''Step 6: ''' Convert the .sql file with your 1.5 tables to an sql file compatible with the version you want to upgrade to. That is a very tedious step - you'll have to check the database schema changes between the 1.5 you're upgrading from and the 1.6.+ version you're upgrading to, and adapt the sql file accordingly. '''Note:''' This step could use a more detailed description, if you have ever done a manual Joomla migration, please help and share your experiences and knowledge here!

'''Step 7:''' Import the .sql file from your computer onto your joomla 1.6+ database. It is also possible that some extensions may have the possibility of changes to the sql tables when they upgraded there extension to joomla 1.6+. If this is the case, it is recommended that you ask the developer of that extension for help with knowing what changes to the sql were made.

'''Keep in mind!''' It is possible for settings to be lost based on how the component stored the settings. From personal experience it worked just fine, but you may want to review the settings of each component.

For an easier way to migrate articles, categories/sections, contacts, images, and users, be sure to use [http://extensions.joomla.org/extensions/migration-a-conversion/data-import-a-export/12816 J2XML] for exporting and [http://extensions.joomla.org/extensions/migration-a-conversion/joomla-migration/15807 J2XML Importer] for importing the data.

=Troubleshooting=
* first check, if you have php5 at least. (use phpinfo() or /usr/bin/php --version)
* '''jUpgrade cannot download Joomla 1.6 package?''' - When the download fails (timeouts, javascript issues, etc) you can download it manually here: http://anonymous:@joomlacode.org/svn/joomla/development/branches/jupgrade/pack/joomla16.zip and put this file into your ROOT/tmp directory. Then, in the preferences of jUpgrade, you must set 'Skip Download' to 'Yes'. After that, run the upgrade again.
* '''Are you getting errors with the progress bar in Internet Explorer (Windows XP)?''' - Use Firefox: http://www.mozilla.com/en-US/firefox/
* Go through the Requirements and Before You Get Started sections above and double check everything!
* '''Report Bugs:''' http://matware.com.ar/foros/jupgrade.html
* '''Support:''' http://matware.com.ar/foros/jupgrade.html
==How You can Contribute & Help==
Creating an extension as significant as jUpgrade requires an enormous amount of time and effort considering the major structural changes between Joomla 1.5 and 1.6. Add to this the fact that during each release of Joomla 1.6 betas, the extension would have to be modified to work with the new changes between releases, and all of a sudden it's too hard for any one person to complete in a short period of time (especially when you are not being paid).
With this being said, it's time to step up and make a difference, whether big or small. Have you profited from Joomla in the last year? Are you excited about the future of Joomla? Would you like to contribute back and show your gratitude? Now you can in this project!
We, as part of the Joomla community, are calling on the entire Joomla community to help out in whatever way you can. You don't have to be a master developer, just go through this tutorial on a test site and if you come across any bugs, report it. If you know how to fix it, create a patch for it. If you are a master developer, step up to the challenge.
* You can report bugs here: http://matware.com.ar/foros/jupgrade.html
* You can volunteer and ask questions about volunteering here: http://www.matware.com.ar/forum/projects/jupgrade/volunteer-information.html
[[Category:Joomla! 1.6]]
[[Category:Tutorials]]
[[Category:Migration]]
[[Category:Installation]]

Talk:Migrating from Joomla 1.5 to Joomla 1.6+

2011-10-18T11:00:15Z

Munchkin: note on manual database migration

Please add PHP check to the update script. If version==4, then prompt "Please upgrade your PHP"

Otherwise the error message is "Fatal error: Only variables can be passed by reference in /var/www/html/administrator/components/com_jupgrade/views/cpanel/view.html.php on line 35"

-- THANKS -- [[User:MichaelJanich|MichaelJanich]] 06:41, 19 January 2011 (UTC)

== install mootools plugin, switch to a default template ==

you might want to add two requirements:

# install the mootools plugin
# switch to a default template first

Without mootools the installation process got stuck (from 1.5.2), using a custom made template, too. --[[User:Marek|Marek]] 17:27, 7 February 2011 (UTC)

=== mootols ===

I added the install the mootools plugin section (without screenshots) --[[User:Weissollo|Weissollo]] 22:09, 9 February 2011 (UTC)

I added a section that describes how to manually upgrade joomla. If anyone has anything to add to it, please feel free.

:To the previous poster here: I don't want to play down your efforts - but as far as I can tell, the database part of the migration definitely does NOT work that way. First off, there's actually no need to change the prefix; and second (and far more importantly): you can't simply import a 1.5 table dump into 1.6 tables! They have completely different structures; I can't really tell for 1.6 at the moment, but 1.7 e.g. has no name column in article anymore, but an asset_id... and many more changes to the columns! So you'll definitely need some kind of migration script here! Since I did the migration via JUpgrade, I don't have any working manual upgrade instructions at hand either at the moment, so I unfortunately can't contribute much constructively here, but I'll change the section so that it becomes clear that it still needs work to be complete. [[User:Munchkin|Munchkin]] 06:00, 18 October 2011 (CDT)

J2.5 talk:Supporting SEF URLs in your component

2011-09-06T09:57:53Z

Munchkin: /* BuildRoute not working as expected */

Hi there,
for me the following statement does not really makes sense:

<source lang="php">
function check()
{
jimport( 'joomla.filter.output' );
$alias = JFilterOutput::stringURLSafe( $this->title );
if (empty( $this->alias ) || $this->alias === $alias ) {
$this->alias = $alias;
}
/* All your other checks */
return true;
}
</source>

As I read it, the filtered $alias is only asigned to the table property, if $table->alias is empty OR $table->alias is exactly the same. So in case $this->alias is not empty, the property will not even be checked or reasigned.

What I find more logical is the method used in the Joomla components

<source lang="php">
if(empty($this->alias)) {
$this->alias = $this->title;
}
$this->alias = JFilterOutput::stringURLSafe($this->alias);
</source>

== What is this supposed to mean ==

This sentence is confusing me quite a bit:

"The alias is used in the URL instead of the title (the title is the text you want to have in the url)."

Is this a mistake, or do I just not understand. If so, could anybody explain?

== Explaination does not match with the example ==

The following sentence explains the example:

"In the function [Componentname]BuildRoute we arranged the items in the $query array in a specific sequence. This means that in this example the view is first, the catid is second and the id is third in the array."

In the example this refers to, the route has only two segments. "view" and "id".

== BuildRoute not working as expected ==

I'm having trouble getting the JRoute::_ function working; it should call the [extensionname]BuildRoute function, right? It seems it currently doesn't do that at my system (1.7). Were there maybe any changes between Joomla 1.5 and Joomla 1.7? Any hints?
[[User:Munchkin|Munchkin]] 04:57, 6 September 2011 (CDT)

J2.5 talk:Supporting SEF URLs in your component

2011-09-06T09:57:20Z

Munchkin: JRoute::_/BuildRoute problem

Hi there,
for me the following statement does not really makes sense:

<source lang="php">
function check()
{
jimport( 'joomla.filter.output' );
$alias = JFilterOutput::stringURLSafe( $this->title );
if (empty( $this->alias ) || $this->alias === $alias ) {
$this->alias = $alias;
}
/* All your other checks */
return true;
}
</source>

As I read it, the filtered $alias is only asigned to the table property, if $table->alias is empty OR $table->alias is exactly the same. So in case $this->alias is not empty, the property will not even be checked or reasigned.

What I find more logical is the method used in the Joomla components

<source lang="php">
if(empty($this->alias)) {
$this->alias = $this->title;
}
$this->alias = JFilterOutput::stringURLSafe($this->alias);
</source>

== What is this supposed to mean ==

This sentence is confusing me quite a bit:

"The alias is used in the URL instead of the title (the title is the text you want to have in the url)."

Is this a mistake, or do I just not understand. If so, could anybody explain?

== Explaination does not match with the example ==

The following sentence explains the example:

"In the function [Componentname]BuildRoute we arranged the items in the $query array in a specific sequence. This means that in this example the view is first, the catid is second and the id is third in the array."

In the example this refers to, the route has only two segments. "view" and "id".

== BuildRoute not working as expected ==

I'm having trouble getting the JRoute::_ function working; it should call the [extensionname]BuildRoute function, right? It seems it currently doesn't do that at my system (1.7). Any hints?
[[User:Munchkin|Munchkin]] 04:57, 6 September 2011 (CDT)

J1.5 talk:Using the editor in a component

2011-09-02T12:25:48Z

Munchkin: Documenting some problems while following this HowTo

I used a test site and implemented the editor in the frontend. The edit and display functions worked fine however the Save and Cancel do not execute anything. The Save and Cancel buttons that have been added to the form call a javascript function submitbutton. The submitbutton is executed however the documentation states that the editor's save method will trigger the save function in the controller which in turn calls the model's store method. This is not actually true. I am new to Joomla development so I thought maybe I typed it in wrong so I downloaded the completed example and it does not work either. The editor's save method does not trigger the controller which I believe is necessary. SO I think in order to make it work you need to trigger the controller directly from the button and bypass the javascript -submitbutton. I haven't tried it yet so if there any other suggestions. That would be great.

== The tutorial is not complete ==

Well what is happening is the following. The person who wrote the tutorial forgot one thing.

In order to use the proposed javascripts the library file /includes/js/joomla.javascript.js had to be included. This is standard in de Joomla backend but not in many frontend templates.

You have to manually add the following. This can for example be done view.html.php
$document =& JFactory::getDocument();
$document->addScript('includes/js/joomla.javascript.js');

I have modified the tutorial but I at this point I don't know how to replace the included download files.

== Possible Problems/Pitfalls ==
When following this HowTo, I encountered these problems:
* The string "description" for one reason or the other doesn't seem to work as editor name. In the javascript created by the editor component for saving the editor content, using "description" leads to a javascript error (tinymce.get('description') is undefined). Another, (shorter?) name (desc) worked fine. I didn't check whether it was the length, or if the string itself has some significance...
* The user I tried it with first had CodeMirror configured as its default editor; with that it didn't work, I wrote about what the result looks like here (http://forum.joomla.org/viewtopic.php?f=620&t=644689&p=2604202#p2604202)
* My component is running under Joomla 1.7, here the script (includes/js/joomla.javascript.js) include doesn't seem to be necessary anymore
* The input filtering stuff doesn't work the way I expected; when doing the following, the database afterwards still holds an encoded string (e.g. > for >), instead of the "raw" html string, meaning I have to convert it back when displaying it (funnily enough I can just pass that string to the editor and it will show it formatted again, so it seems to do the back-converting by itself)
$post['content'] = JRequest::getVar('content', '', 'post', 'string', JREQUEST_ALLOWRAW);
[[User:Munchkin|Munchkin]] 07:25, 2 September 2011 (CDT)