Joomla! Documentation - User contributions [en]

Jimport

2012-10-31T23:05:50Z

HobbesPDX: updated link to API docs

The joomla function jimport($path) [http://api.joomla.org/1.5/Joomla-Framework/_loader.php.html#functionjimport (See API)] is a core function used to load joomla library files.

== How it works (short version) ==
The dots (.) in $path are replaced with a directory separator ("/" or "\") and ".php" extension is added at the end of the string. This path is included.

== Examples of use ==
<pre>
jimport('joomla.application.component.controller');
</pre>
- will include the php file "/libraries/joomla/application/component/controller.php". This file holds the class JController.

<pre>
jimport('joomla.application.component.model');
</pre>
- will include the php file "/libraries/joomla/application/component/model.php". This file holds the class JModel.

<pre>
jimport('joomla.application.component.view'); // Includes JView
class RecipeViewIngredients extends JView
{
...
</pre>

Talk:Potential backward compatibility issues in Joomla 3.0 and Joomla Platform 12.1

2012-08-29T17:50:57Z

HobbesPDX: Too Much Information?

== Too Much Information? ==

Starting a discussion to ascertain why so much info was removed in the latest changes to this page. [To me] it makes the most sense to have more (potentially too much) information, than not enough. Developers are going to need to be aware of the changes to the API, and having this information available for search engines to index will only help the community transition to 3.0. IMO.

-- [[User:HobbesPDX|HobbesPDX]] ([[User talk:HobbesPDX|talk]]) 12:50, 29 August 2012 (CDT)

Potential backward compatibility issues in Joomla 3.0 and Joomla Platform 12.1

2012-08-29T17:46:12Z

HobbesPDX: Undo revision 72169 -- why was so much removed?!

{{incomplete}}{{RightTOC}}This document tracks potential backward compatibility issues for Joomla 3.0 and Joomla Platform 12.1, which is included in Joomla 3.0. Listed are issues which potentially break extensions.
Please help make this document complete.

The base of this comparison is Joomla 2.5/Platform 11.4.

Backwards compatibility issues were also tracked for Joomla 2.5: [[Potential backward compatibility issues in Joomla 2.5 and Joomla Platform 11.4]]

= Platform =
The platform removed a larger number of deprecated classes and methods. For most extensions written for Joomla 2.5, the required changes should be reasonably small. Note that there are still deprecated classes in the platform that will be removed in future versions -- developers should stop using them where possible.

== Updated System Requirements ==
The system requirements have changed in the following points:
*PHP 5.3.1
*register_globals must be off
*magic_quotes_gpc must be off

== General changes ==
*Almost all functions, methods, members and classed marked as deprecated in Platform 11.4 have been removed. They won't be listed in this document.
*Appending ?no_html to an URL to get a RAW view is not supported anymore (this was an old Joomla 1.0 feature).
*The DS constant has been removed. If you really need it you can use DIRECTORY_SEPARATOR instead.
*Many more function arguments have been type hinted, including existing classes. Make sure you're always passing values of the correct type.
*The name of modules now have to start with "mod_".
*Extensions need to set the registeredurlparams now, the fall back on the URL has been removed.
*Some cookies are only accessible through HTTP (not via JavaScript). For example; the session cookie.
*Due to upcoming changes to the MVC implementation in the platform, JModel, JView, and JController are re-used as the names of the new interfaces. For now, use JModelLegacy, JViewLegacy and JControllerLegacy instead.
*JFolder and JFile now require you to do your own jimport statement (You always had to do that, just before it was rather likely something else had loaded them before)

== Changes to extension installation ==
*Use of the <install> base tag (from 1.5) is no longer supported; use <extension> instead.
*Suppport for install_script and uninstall_script, and the methods com_install and com_uninstall in these scripts, has been removed; use scriptfile instead.
*In language extensions, support for client="both" has been removed; prepare each client as a separate extension and optionally bundle them as a package extension instead.
*File paths for plugins no longer support the old 1.5 method (i.e. plugins/system/cache.php); each plugin must now be in its own folder (i.e. plugins/system/cache/cache.php).

== Changes to Components ==
*In admin components the admin.*.php and toolbar.*.php are not automatically included anymore (this was a Joomla 1.0 legacy feature).

== Moved files ==
All classes listed here should now be autoloadable. Explicit requires and includes have to be modified or removed.

=== Classes moved to the CMS ===
*JFormFieldHelpsite
*JFormFieldMedia
*JFormFieldMenuitem
*JFormFieldUser
*JHelp
*JTableContent

=== Classes moved within the platform ===
*JDatabaseQuery subclasses
*JInput (and all subclasses)
*JTable (and all subclasses)
*JArchive (and all subclasses)

== Renamed classes ==
*JFTP is now called JClientFtp
*JLDAP is now called JClientLdap
*JWebClient is now called JApplicationWebClient

== Removed classes ==
*JParameter (use JForm instead)
*JElement and its subclasses
*JFormFieldEditors (use JFormFieldPlugins instead)
*JHtmlImage
*JSimpleXML
*JPane

== Changes to classes ==

=== Base classes ===

==== JFactory ====
*JFactory::getXMLParser() has been removed. For RSS and Atom use cases, use JFactory::getFeedParser() instead. To read XML files or strings use JFactory::getXML().
*JFactory::_createConfig() has been removed. Use JFactory::createConfig() instead.
*JFactory::_createSession() has been removed. Use JFactory::createSession() instead.
*JFactory::_createDbo() has been removed. Use JFactory::createDbo() instead.
*JFactory::_createMailer() has been removed. Use JFactory::createMailer() instead.
*JFactory::_createDocument() has been removed. Use JFactory::createDocument() instead.

=== Application ===

==== JApplicationHelper ====
*JApplicationHelper::getPath() has been removed. No replacement.
*JApplicationHelper::_checkPath() has been removed. No replacement.

==== JController ====
*JController::$_acoSection has been removed.
*JController::$_acoSectionValue has been removed.
*JController::authorize() has been removed. Use JController::authorise() instead.
*JController::setAccessControl() has been removed. Use JAccess.

==== JControllerLegacy ====
* JControllerLegacy::display() needs an extra parameter: ($cachable = false, $urlparams = false).

=== Archive ===

==== Adapters ====
*JArchiveBzip2 does not extend JObject anymore. You must not use any of JObject's methods.
*JArchiveGzip does not extend JObject anymore. You must not use any of JObject's methods.
*JArchiveTar does not extend JObject anymore. You must not use any of JObject's methods.
*JArchiveZip does not extend JObject anymore. You must not use any of JObject's methods.

=== Base ===

==== JObject ====
*JObject::toString() has been removed. Use JObject::__toString() instead.

=== Client ===

==== JClientLdap (formerly JLDAP) ====
*JClientLdap does not extend JObject anymore. You must not use any of JObject's methods.

=== Database ===
JDatabase had been renamed JDatabaseDriver. JDatabase is still around (but deprecated) and is the base of JDatabaseDriver, this way type hints and instance of checks keep working.

Due to lazy-connecting, a connection is only opened when running a query or explicitly calling JDatabaseDriver::connected(). Beware of that when checking JDatabaseDriver::connected().

==== JDatabase ====
*JDatabase::$hasQuoted has been removed.
*JDatabase::$quoted has been removed.
*JDatabase::addQuoted() has been removed.
*JDatabase::hasUTF() has been removed.
*JDatabase::debug() has been removed. Use JDatabase::setDebug() instead.
*JDatabase::explain() has been removed.
*JDatabase::getEscaped() has been removed. Use JDatabase::escape() instead.
*JDatabase::getTableFields() has been removed. Use JDatabase::getTableColumns() instead.
*JDatabase::getTicker() has been removed. Use JDatabase::count() instead.
*JDatabase::isQuoted() has been removed.
*JDatabase::loadResultArray() has been removed. Use JDatabase::loadColumn() instead.
*JDatabase::nameQuote() has been removed. Use JDatabase::quoteName() instead.
*JDatabase::queryBatch() has been removed.

=== Document ===

==== JDocument ====
*JDocument::setMetaData() the $sync argument has been removed. It was broken beyond repair.

==== JDocumentRenderer ====
*JDocumentRenderer does not extend JObject anymore. You must not use any of JObject's methods.

==== JDocumentFeed ====
*JFeedItem does not extend JObject anymore. You must not use any of JObject's methods.
*JFeedEnclosure does not extend JObject anymore. You must not use any of JObject's methods.
*JFeedImage does not extend JObject anymore. You must not use any of JObject's methods.

==== JDocumentOpenSearch ====
*JOpenSearchUrl does not extend JObject anymore. You must not use any of JObject's methods.
*JOpenSearchImage does not extend JObject anymore. You must not use any of JObject's methods.

==== JDocumentXml ====
*JDocumentXml::$_name has been renamed to JDocumentXml::$name.

=== Environment ===

==== JBrowser ====
*JBrowser does not extend JObject anymore. You must not use any of JObject's methods.
*JBrowser::setQuirk() has been removed.
*JBrowser::hasQuirk() has been removed.
*JBrowser::getQuirk() has been removed.
*JBrowser::setFeature() has been removed.
*JBrowser::hasFeature() has been removed.
*JBrowser::getFeature() has been removed.
*JBrowser::$_majorVersion has been renamed to JBrowser::$majorVersion.
*JBrowser::$_minorVersion has been renamed to JBrowser::$minorVersion.
*JBrowser::$_browser has been renamed to JBrowser::$browser.
*JBrowser::$_agent has been renamed to JBrowser::$agent.
*JBrowser::$_lowerAgent has been renamed to JBrowser::$lowerAgent.
*JBrowser::$_accept has been renamed to JBrowser::$accept.
*JBrowser::$_accept_parsed has been renamed to JBrowser::$acceptParsed.
*JBrowser::$_platform has been renamed to JBrowser::$platform.
*JBrowser::$_robots has been renamed to JBrowser::$robots.
*JBrowser::$_mobile has been renamed to JBrowser::$mobile.
*JBrowser::$_images has been renamed to JBrowser::$images.

==== JRequest ====
*JRequest::clean() has been removed.
*JRequest::_cleanVar() is now protected.

==== JURI ====
*JURI does not extend JObject anymore. You must not use any of JObject's methods.
*JUri::$_uri has been renamed to JUri::$uri.
*JUri::$_scheme has been renamed to JUri::$scheme.
*JUri::$_host has been renamed to JUri::$host.
*JUri::$_port has been renamed to JUri::$port.
*JUri::$_user has been renamed to JUri::$user.
*JUri::$_pass has been renamed to JUri::$pass.
*JUri::$_path has been renamed to JUri::$path.
*JUri::$_query has been renamed to JUri::$query.
*JUri::$_fragment has been renamed to JUri::$fragment.
*JUri::$_vars has been renamed to JUri::$vars.

=== Error ===

==== JError ====
*JError::isError() has been removed. Use instance of Exception instead.

==== JProfiler ====
*JProfiler does not extend JObject anymore. You must not use any of JObject's methods.
*JProfiler::$_start has been renamed to JProfiler::$start.
*JProfiler::$_prefix has been renamed to JProfiler::$prefix.
*JProfiler::$_buffer has been renamed to JProfiler::$buffer.
*JProfiler::$_previous_time has been renamed to JProfiler::$previousTime.
*JProfiler::$_previous_mem has been renamed to JProfiler::$previousMem.
*JProfiler::$_iswin has been renamed to JProfiler::$isWin.

=== Filesystem ===

==== JStream ====
*JStream::$_fh has been renamed to JStream::$fh.
*JStream::$_filesize has been renamed to JStream::$filesize.
*JStream::$_context has been renamed to JStream::$context.
*JStream::$_contextOptions has been renamed to JStream::$contextOptions.
*JStream::$_openmode has been renamed to JStream::$openmode.

==== JStreamString ====
*JStream::$_currentstring has been renamed to JStream::$currentString.
*JStream::$_path has been renamed to JStream::$path.
*JStream::$_mode has been renamed to JStream::$mode.
*JStream::$_options has been renamed to JStream::$options.
*JStream::$_opened_path has been renamed to JStream::$openedPath.
*JStream::$_pos has been renamed to JStream::$pos.
*JStream::$_len has been renamed to JStream::$len.
*JStream::$_stat has been renamed to JStream::$stat.

=== Filter ===

==== JFilterInput ====
*JFilterInput does not extend JObject anymore. You must not use any of JObject's methods.

=== HTML ===

==== JHtml ====
*JHtml::_includeRelativeFiles() has been removed. Use JHtml::includeRelativeFiles() instead.
*JHtml::core() has been removed. Use JHtmlBehavior::framework() instead.
*JHtml::script() doesn't support a string as the second parameter anymore. This used to be the path to the file in Joomla 1.5 and has been removed now.
*JHtml::stylesheet() doesn't support a string as the second parameter anymore. This used to be the path to the file in Joomla 1.5 and has been removed now.

==== JHtmlAccess ====
*JHtmlAccess::assetgroups() the argument $config has been removed. It was previously unused.

==== JHtmlBehavior ====
*JHtmlBehavior::mootools() has been removed. Use JHtmlBehavior::framework() instead.
*JHtmlBehavior::noframes() the argument $location has been removed. It was previously unused.

==== JHtmlList ====
*JHtmlList::ordering() the argument $chop has been removed. It was previously unused.
*JHtmlList::users(), the argument $reg has been removed.

==== JHtmlSelect ====
*JHtmlSelect::$_optionDefaults has been renamed to JHtmlSelect::$optionDefaults.

==== JToolBar ====
*JToolBar does not extend JObject anymore. You must not use any of JObject's methods.

==== JButton ====
*JButton does not extend JObject anymore. You must not use any of JObject's methods.

==== JPagination ====
*JPagination::$_viewall has been renamed to JPagination::$viewall.
*JPagination::$_additionalUrlParams has been renamed to JPagination::$additionalUrlParams.

=== Installer ===

==== JInstaller ====
*JInstaller::getOverwrite() has been removed. Use JInstaller::isOverwrite() instead.
*JInstaller::getUpgrade() has been removed. Use JInstaller::isUpgrade() instead.
*JInstaller::$_paths has been renamed to JInstaller::$paths.
*JInstaller::$_upgrade has been renamed to JInstaller::$upgrade.
*JInstaller::$_overwrite has been renamed to JInstaller::$overwrite.
*JInstaller::$_stepStack has been renamed to JInstaller::$stepStack.

==== JInstallerLanguage ====
*JInstallerLanguage::$_core as been renamed to JInstallerLanguage::$core.

=== Language ===

==== JLanguage ====
*JLanguage::getPluralSufficesCallback() has been removed. Use JLanguage::getPluralSuffixesCallback() instead.
*JLanguage::_parseLanguageFiles() has been removed. Use JLanguage::parseLanguageFiles() instead.
*JLanguage::_parseXMLLanguageFiles() has been removed. Use JLanguage::parseXMLLanguageFiles() instead.
*JLanguage::_parseXMLLanguageFile() has been removed. Use JLanguage::parseXMLLanguageFile() instead.
*JLanguage::loadLanguage() the argument $overwrite has been removed. It was previously unused.

=== Registry ===

==== JRegistry ====
*JRegistry::loadXML() has been removed. Use JRegistry::loadString() instead.
*JRegistry::loadINI() has been removed. Use JRegistry::loadString() instead.
*JRegistry::loadJSON() has been removed. Use JRegistry::loadString() instead.
*JRegistry::makeNameSpace() has been removed. No replacement.
*JRegistry::getNameSpaces() has been removed. No replacement.
*JRegistry::getValue() has been removed. Use JRegistry::get() instead.
*JRegistry::setValue() has been removed. Use JRegistry::set() instead.
*JRegistry::loadSetupFile() has been removed. No replacement.

==== JRegistryFormatINI ====
*JRegistryFormatINI::stringToObject() the second argument ($option) may not be a boolean anymore.

==== JRegistryFormatJSON ====
*JRegistryFormatJSON::stringToObject() the second argument ($option) may not be a boolean anymore.

=== Session ===

==== JSessionStorageDatabase ====
*JSessionStorageDatabase::$_data has been renamed to JSessionStorageDatabase::$data.

=== Table ===

==== JTable ====
*JTable::canDelete() has been removed.
*JTable::toXML() has been removed.

=== Updater ===

==== JUpdate ====
*JUpdate::$_xml_parser has been renamed to JUpdate::$xmlParser.
*JUpdate::$_stack has been renamed to JUpdate::$stack.
*JUpdate::$_state_store has been renamed to JUpdate::$stateStore.
*JUpdate::$_current_update has been renamed to JUpdate::$currentUpdate.

==== JUpdater ====
*JUpdater::arrayUnique() has been removed. Use JArrayHelper::arrayUnique() instead.

=== User ===

==== JAuthentication ====
*The constant JAUTHENTICATE_STATUS_SUCCESS has been removed. Use JAuthentication::STATUS_SUCCESS instead.
*The constant JAUTHENTICATE_STATUS_CANCEL has been removed. No replacement.
*The constant JAUTHENTICATE_STATUS_FAILURE has been removed. Use JAuthentication::STATUS_FAILURE instead.
*JAuthentication::$_observers has been renamed to JAuthentication::$observers.
*JAuthentication::$_state has been renamed to JAuthentication::$state.
*JAuthentication::$_methods has been renamed to JAuthentication::$methods.

==== JUser ====
*JUser::getParameters() has been removed.
*Juser::authorisedLevels() has been removed. Use JUser::getAuthorisedViewLevels() instead.
*Juser::authorize() has been removed. Use JUser::authorise() instead.
*JUser::$usertype has been removed.

=== Utility ===

==== JBuffer ====
*JBuffer::$_buffers has been renamed to JBuffer::$buffers.

==== JDate ====
*JDate::toMysql() has been removed. Use JDate::toSql() instead.
*JDate::toFormat() has been removed. Use JDate::format() instead.
*JDate::setOffset() has been removed.
*JDate::$offsets has been removed.
*JDate::__construct() doesn't accept an numeric value for $tz anymore.
*JDate::$_tz has been renamed to JDate::$tz.

==== JUtility ====
*JUtility::sendMail() has been removed. Use JMail::sendMail() instead.
*JUtility::sendAdminMail() has been removed. Use JMail::sendAdminMail() instead.
*JUtility::getHash() has been removed. Use JApplication::getHash() instead.
*JUtility::getToken() has been removed. Use JSession::getFormToken() instead.
*JUtility::isWinOS() has been removed. Use JApplication::isWinOS() instead.
*JUtility::dump() has been removed. No replacement.
*JUtility::array_unshift_ref() has been removed. No replacement.
*JUtility::array_unshift_ref() has been removed. No replacement.

==== JXMLElement ====
*JXMLElement::data() has been removed.
*JXMLElement::getAttribute() has been removed. Use SimpleXMLElement::attributes() instead.

== JavaScript ==
*Compatibility with MooTools 1.2 has been removed.
*Forms that have name="adminForm" now also require id="adminForm".
*checkAll() has been removed. Use Joomla.checkAll() instead.
*isChecked() has been removed. Use Joomla.isChecked() instead.
*popupWindow() has been removed. Use Joomla.popupWindow() instead.
*tableOrdering() has been removed. Use Joomla.tableOrdering() instead.

= CMS =

== General changes ==
*JUtility is not always loaded. If you need it you have to add jimport('joomla.utilities.utility'); to your code.

== Changes to classes ==

=== Component Classes ===
*MenusModelItem::getItem() no longer returns a JObject but a stdClass.

=== Help ===

==== JHelp ====
*JHelp::createSiteList() the argument $selected has been removed. It was unused.

[[Category:Compatibility]]
[[Category:Development]]
[[Category:Framework]]

Potential backward compatibility issues in Joomla 3.0 and Joomla Platform 12.1

2012-08-17T07:24:08Z

HobbesPDX: grammar, spelling and punctuation details

{{incomplete}}{{RightTOC}}This document tracks potential backward compatibility issues for Joomla 3.0 and Joomla Platform 12.1, which is included in Joomla 3.0. Listed are issues which potentially break extensions.
Please help make this document complete.

The base of this comparison is Joomla 2.5/Platform 11.4.

Backwards compatibility issues were also tracked for Joomla 2.5: [[Potential backward compatibility issues in Joomla 2.5 and Joomla Platform 11.4]]

= Platform =
The platform removed a larger number of deprecated classes and methods. For most extensions written for Joomla 2.5, the required changes should be reasonably small. Note that there are still deprecated classes in the platform that will be removed in future versions -- developers should stop using them where possible.

== Updated System Requirements ==
The system requirements have changed in the following points:
*PHP 5.3.1
*register_globals must be off
*magic_quotes_gpc must be off

== General changes ==
*Almost all functions, methods, members and classed marked as deprecated in Platform 11.4 have been removed. They won't be listed in this document.
*Appending ?no_html to an URL to get a RAW view is not supported anymore (this was an old Joomla 1.0 feature).
*The DS constant has been removed. If you really need it you can use DIRECTORY_SEPARATOR instead.
*Many more function arguments have been type hinted, including existing classes. Make sure you're always passing values of the correct type.
*The name of modules now have to start with "mod_".
*Extensions need to set the registeredurlparams now, the fall back on the URL has been removed.
*Some cookies are only accessible through HTTP (not via JavaScript). For example; the session cookie.
*Due to upcoming changes to the MVC implementation in the platform, JModel, JView, and JController are re-used as the names of the new interfaces. For now, use JModelLegacy, JViewLegacy and JControllerLegacy instead.

== Changes to extension installation ==
*Use of the <install> base tag (from 1.5) is no longer supported; use <extension> instead.
*Suppport for install_script and uninstall_script, and the methods com_install and com_uninstall in these scripts, has been removed; use scriptfile instead.
*In language extensions, support for client="both" has been removed; prepare each client as a separate extension and optionally bundle them as a package extension instead.
*File paths for plugins no longer support the old 1.5 method (i.e. plugins/system/cache.php); each plugin must now be in its own folder (i.e. plugins/system/cache/cache.php).

== Changes to Components ==
*In admin components the admin.*.php and toolbar.*.php are not automatically included anymore (this was a Joomla 1.0 legacy feature).

== Moved files ==
All classes listed here should now be autoloadable. Explicit requires and includes have to be modified or removed.

=== Classes moved to the CMS ===
*JFormFieldHelpsite
*JFormFieldMedia
*JFormFieldMenuitem
*JFormFieldUser
*JHelp
*JTableContent

=== Classes moved within the platform ===
*JDatabaseQuery subclasses
*JInput (and all subclasses)
*JTable (and all subclasses)
*JArchive (and all subclasses)

== Renamed classes ==
*JFTP is now called JClientFtp
*JLDAP is now called JClientLdap
*JWebClient is now called JApplicationWebClient

== Removed classes ==
*JParameter (use JForm instead)
*JElement and its subclasses
*JFormFieldEditors (use JFormFieldPlugins instead)
*JHtmlImage
*JSimpleXML
*JPane

== Changes to classes ==

=== Base classes ===

==== JFactory ====
*JFactory::getXMLParser() has been removed. For RSS and Atom use cases, use JFactory::getFeedParser() instead. To read XML files or strings use JFactory::getXML().
*JFactory::_createConfig() has been removed. Use JFactory::createConfig() instead.
*JFactory::_createSession() has been removed. Use JFactory::createSession() instead.
*JFactory::_createDbo() has been removed. Use JFactory::createDbo() instead.
*JFactory::_createMailer() has been removed. Use JFactory::createMailer() instead.
*JFactory::_createDocument() has been removed. Use JFactory::createDocument() instead.

=== Application ===

==== JApplicationHelper ====
*JApplicationHelper::getPath() has been removed. No replacement.
*JApplicationHelper::_checkPath() has been removed. No replacement.

==== JController ====
*JController::$_acoSection has been removed.
*JController::$_acoSectionValue has been removed.
*JController::authorize() has been removed. Use JController::authorise() instead.
*JController::setAccessControl() has been removed. Use JAccess.

==== JControllerLegacy ====
* JControllerLegacy::display() needs an extra parameter: ($cachable = false, $urlparams = false).

=== Archive ===

==== Adapters ====
*JArchiveBzip2 does not extend JObject anymore. You must not use any of JObject's methods.
*JArchiveGzip does not extend JObject anymore. You must not use any of JObject's methods.
*JArchiveTar does not extend JObject anymore. You must not use any of JObject's methods.
*JArchiveZip does not extend JObject anymore. You must not use any of JObject's methods.

=== Base ===

==== JObject ====
*JObject::toString() has been removed. Use JObject::__toString() instead.

=== Client ===

==== JClientLdap (formerly JLDAP) ====
*JClientLdap does not extend JObject anymore. You must not use any of JObject's methods.

=== Database ===
JDatabase had been renamed JDatabaseDriver. JDatabase is still around (but deprecated) and is the base of JDatabaseDriver, this way type hints and instance of checks keep working.

Due to lazy-connecting, a connection is only opened when running a query or explicitly calling JDatabaseDriver::connected(). Beware of that when checking JDatabaseDriver::connected().

==== JDatabase ====
*JDatabase::$hasQuoted has been removed.
*JDatabase::$quoted has been removed.
*JDatabase::addQuoted() has been removed.
*JDatabase::hasUTF() has been removed.
*JDatabase::debug() has been removed. Use JDatabase::setDebug() instead.
*JDatabase::explain() has been removed.
*JDatabase::getEscaped() has been removed. Use JDatabase::escape() instead.
*JDatabase::getTableFields() has been removed. Use JDatabase::getTableColumns() instead.
*JDatabase::getTicker() has been removed. Use JDatabase::count() instead.
*JDatabase::isQuoted() has been removed.
*JDatabase::loadResultArray() has been removed. Use JDatabase::loadColumn() instead.
*JDatabase::nameQuote() has been removed. Use JDatabase::quoteName() instead.
*JDatabase::queryBatch() has been removed.

=== Document ===

==== JDocument ====
*JDocument::setMetaData() the $sync argument has been removed. It was broken beyond repair.

==== JDocumentRenderer ====
*JDocumentRenderer does not extend JObject anymore. You must not use any of JObject's methods.

==== JDocumentFeed ====
*JFeedItem does not extend JObject anymore. You must not use any of JObject's methods.
*JFeedEnclosure does not extend JObject anymore. You must not use any of JObject's methods.
*JFeedImage does not extend JObject anymore. You must not use any of JObject's methods.

==== JDocumentOpenSearch ====
*JOpenSearchUrl does not extend JObject anymore. You must not use any of JObject's methods.
*JOpenSearchImage does not extend JObject anymore. You must not use any of JObject's methods.

==== JDocumentXml ====
*JDocumentXml::$_name has been renamed to JDocumentXml::$name.

=== Environment ===

==== JBrowser ====
*JBrowser does not extend JObject anymore. You must not use any of JObject's methods.
*JBrowser::setQuirk() has been removed.
*JBrowser::hasQuirk() has been removed.
*JBrowser::getQuirk() has been removed.
*JBrowser::setFeature() has been removed.
*JBrowser::hasFeature() has been removed.
*JBrowser::getFeature() has been removed.
*JBrowser::$_majorVersion has been renamed to JBrowser::$majorVersion.
*JBrowser::$_minorVersion has been renamed to JBrowser::$minorVersion.
*JBrowser::$_browser has been renamed to JBrowser::$browser.
*JBrowser::$_agent has been renamed to JBrowser::$agent.
*JBrowser::$_lowerAgent has been renamed to JBrowser::$lowerAgent.
*JBrowser::$_accept has been renamed to JBrowser::$accept.
*JBrowser::$_accept_parsed has been renamed to JBrowser::$acceptParsed.
*JBrowser::$_platform has been renamed to JBrowser::$platform.
*JBrowser::$_robots has been renamed to JBrowser::$robots.
*JBrowser::$_mobile has been renamed to JBrowser::$mobile.
*JBrowser::$_images has been renamed to JBrowser::$images.

==== JRequest ====
*JRequest::clean() has been removed.
*JRequest::_cleanVar() is now protected.

==== JURI ====
*JURI does not extend JObject anymore. You must not use any of JObject's methods.
*JUri::$_uri has been renamed to JUri::$uri.
*JUri::$_scheme has been renamed to JUri::$scheme.
*JUri::$_host has been renamed to JUri::$host.
*JUri::$_port has been renamed to JUri::$port.
*JUri::$_user has been renamed to JUri::$user.
*JUri::$_pass has been renamed to JUri::$pass.
*JUri::$_path has been renamed to JUri::$path.
*JUri::$_query has been renamed to JUri::$query.
*JUri::$_fragment has been renamed to JUri::$fragment.
*JUri::$_vars has been renamed to JUri::$vars.

=== Error ===

==== JError ====
*JError::isError() has been removed. Use instance of Exception instead.

==== JProfiler ====
*JProfiler does not extend JObject anymore. You must not use any of JObject's methods.
*JProfiler::$_start has been renamed to JProfiler::$start.
*JProfiler::$_prefix has been renamed to JProfiler::$prefix.
*JProfiler::$_buffer has been renamed to JProfiler::$buffer.
*JProfiler::$_previous_time has been renamed to JProfiler::$previousTime.
*JProfiler::$_previous_mem has been renamed to JProfiler::$previousMem.
*JProfiler::$_iswin has been renamed to JProfiler::$isWin.

=== Filesystem ===

==== JStream ====
*JStream::$_fh has been renamed to JStream::$fh.
*JStream::$_filesize has been renamed to JStream::$filesize.
*JStream::$_context has been renamed to JStream::$context.
*JStream::$_contextOptions has been renamed to JStream::$contextOptions.
*JStream::$_openmode has been renamed to JStream::$openmode.

==== JStreamString ====
*JStream::$_currentstring has been renamed to JStream::$currentString.
*JStream::$_path has been renamed to JStream::$path.
*JStream::$_mode has been renamed to JStream::$mode.
*JStream::$_options has been renamed to JStream::$options.
*JStream::$_opened_path has been renamed to JStream::$openedPath.
*JStream::$_pos has been renamed to JStream::$pos.
*JStream::$_len has been renamed to JStream::$len.
*JStream::$_stat has been renamed to JStream::$stat.

=== Filter ===

==== JFilterInput ====
*JFilterInput does not extend JObject anymore. You must not use any of JObject's methods.

=== HTML ===

==== JHtml ====
*JHtml::_includeRelativeFiles() has been removed. Use JHtml::includeRelativeFiles() instead.
*JHtml::core() has been removed. Use JHtmlBehavior::framework() instead.
*JHtml::script() doesn't support a string as the second parameter anymore. This used to be the path to the file in Joomla 1.5 and has been removed now.
*JHtml::stylesheet() doesn't support a string as the second parameter anymore. This used to be the path to the file in Joomla 1.5 and has been removed now.

==== JHtmlAccess ====
*JHtmlAccess::assetgroups() the argument $config has been removed. It was previously unused.

==== JHtmlBehavior ====
*JHtmlBehavior::mootools() has been removed. Use JHtmlBehavior::framework() instead.
*JHtmlBehavior::noframes() the argument $location has been removed. It was previously unused.

==== JHtmlList ====
*JHtmlList::ordering() the argument $chop has been removed. It was previously unused.
*JHtmlList::users(), the argument $reg has been removed.

==== JHtmlSelect ====
*JHtmlSelect::$_optionDefaults has been renamed to JHtmlSelect::$optionDefaults.

==== JToolBar ====
*JToolBar does not extend JObject anymore. You must not use any of JObject's methods.

==== JButton ====
*JButton does not extend JObject anymore. You must not use any of JObject's methods.

==== JPagination ====
*JPagination::$_viewall has been renamed to JPagination::$viewall.
*JPagination::$_additionalUrlParams has been renamed to JPagination::$additionalUrlParams.

=== Installer ===

==== JInstaller ====
*JInstaller::getOverwrite() has been removed. Use JInstaller::isOverwrite() instead.
*JInstaller::getUpgrade() has been removed. Use JInstaller::isUpgrade() instead.
*JInstaller::$_paths has been renamed to JInstaller::$paths.
*JInstaller::$_upgrade has been renamed to JInstaller::$upgrade.
*JInstaller::$_overwrite has been renamed to JInstaller::$overwrite.
*JInstaller::$_stepStack has been renamed to JInstaller::$stepStack.

==== JInstallerLanguage ====
*JInstallerLanguage::$_core as been renamed to JInstallerLanguage::$core.

=== Language ===

==== JLanguage ====
*JLanguage::getPluralSufficesCallback() has been removed. Use JLanguage::getPluralSuffixesCallback() instead.
*JLanguage::_parseLanguageFiles() has been removed. Use JLanguage::parseLanguageFiles() instead.
*JLanguage::_parseXMLLanguageFiles() has been removed. Use JLanguage::parseXMLLanguageFiles() instead.
*JLanguage::_parseXMLLanguageFile() has been removed. Use JLanguage::parseXMLLanguageFile() instead.
*JLanguage::loadLanguage() the argument $overwrite has been removed. It was previously unused.

=== Registry ===

==== JRegistry ====
*JRegistry::loadXML() has been removed. Use JRegistry::loadString() instead.
*JRegistry::loadINI() has been removed. Use JRegistry::loadString() instead.
*JRegistry::loadJSON() has been removed. Use JRegistry::loadString() instead.
*JRegistry::makeNameSpace() has been removed. No replacement.
*JRegistry::getNameSpaces() has been removed. No replacement.
*JRegistry::getValue() has been removed. Use JRegistry::get() instead.
*JRegistry::setValue() has been removed. Use JRegistry::set() instead.
*JRegistry::loadSetupFile() has been removed. No replacement.

==== JRegistryFormatINI ====
*JRegistryFormatINI::stringToObject() the second argument ($option) may not be a boolean anymore.

==== JRegistryFormatJSON ====
*JRegistryFormatJSON::stringToObject() the second argument ($option) may not be a boolean anymore.

=== Session ===

==== JSessionStorageDatabase ====
*JSessionStorageDatabase::$_data has been renamed to JSessionStorageDatabase::$data.

=== Table ===

==== JTable ====
*JTable::canDelete() has been removed.
*JTable::toXML() has been removed.

=== Updater ===

==== JUpdate ====
*JUpdate::$_xml_parser has been renamed to JUpdate::$xmlParser.
*JUpdate::$_stack has been renamed to JUpdate::$stack.
*JUpdate::$_state_store has been renamed to JUpdate::$stateStore.
*JUpdate::$_current_update has been renamed to JUpdate::$currentUpdate.

==== JUpdater ====
*JUpdater::arrayUnique() has been removed. Use JArrayHelper::arrayUnique() instead.

=== User ===

==== JAuthentication ====
*The constant JAUTHENTICATE_STATUS_SUCCESS has been removed. Use JAuthentication::STATUS_SUCCESS instead.
*The constant JAUTHENTICATE_STATUS_CANCEL has been removed. No replacement.
*The constant JAUTHENTICATE_STATUS_FAILURE has been removed. Use JAuthentication::STATUS_FAILURE instead.
*JAuthentication::$_observers has been renamed to JAuthentication::$observers.
*JAuthentication::$_state has been renamed to JAuthentication::$state.
*JAuthentication::$_methods has been renamed to JAuthentication::$methods.

==== JUser ====
*JUser::getParameters() has been removed.
*Juser::authorisedLevels() has been removed. Use JUser::getAuthorisedViewLevels() instead.
*Juser::authorize() has been removed. Use JUser::authorise() instead.
*JUser::$usertype has been removed.

=== Utility ===

==== JBuffer ====
*JBuffer::$_buffers has been renamed to JBuffer::$buffers.

==== JDate ====
*JDate::toMysql() has been removed. Use JDate::toSql() instead.
*JDate::toFormat() has been removed. Use JDate::format() instead.
*JDate::setOffset() has been removed.
*JDate::$offsets has been removed.
*JDate::__construct() doesn't accept an numeric value for $tz anymore.
*JDate::$_tz has been renamed to JDate::$tz.

==== JUtility ====
*JUtility::sendMail() has been removed. Use JMail::sendMail() instead.
*JUtility::sendAdminMail() has been removed. Use JMail::sendAdminMail() instead.
*JUtility::getHash() has been removed. Use JApplication::getHash() instead.
*JUtility::getToken() has been removed. Use JSession::getFormToken() instead.
*JUtility::isWinOS() has been removed. Use JApplication::isWinOS() instead.
*JUtility::dump() has been removed. No replacement.
*JUtility::array_unshift_ref() has been removed. No replacement.
*JUtility::array_unshift_ref() has been removed. No replacement.

==== JXMLElement ====
*JXMLElement::data() has been removed.
*JXMLElement::getAttribute() has been removed. Use SimpleXMLElement::attributes() instead.

== JavaScript ==
*Compatibility with MooTools 1.2 has been removed.
*Forms that have name="adminForm" now also require id="adminForm".
*checkAll() has been removed. Use Joomla.checkAll() instead.
*isChecked() has been removed. Use Joomla.isChecked() instead.
*popupWindow() has been removed. Use Joomla.popupWindow() instead.
*tableOrdering() has been removed. Use Joomla.tableOrdering() instead.

= CMS =

== General changes ==
*JUtility is not always loaded. If you need it you have to add jimport('joomla.utilities.utility'); to your code.

== Changes to classes ==

=== Component Classes ===
*MenusModelItem::getItem() no longer returns a JObject but a stdClass.

=== Help ===

==== JHelp ====
*JHelp::createSiteList() the argument $selected has been removed. It was unused.

[[Category:Compatibility]]
[[Category:Development]]
[[Category:Framework]]

Potential backward compatibility issues in Joomla 3.0 and Joomla Platform 12.1

2012-08-17T06:49:03Z

HobbesPDX:

{{incomplete}}{{RightTOC}}This documents track potential backward compatibility issues for Joomla 3.0 and Joomla Platform 12.1 which is included in Joomla 3.0. Listed are issues which potentially break extensions.
Please help making this document complete.

The base of this comparison is Joomla 2.5/Platform 11.4.

Backwards compatibility issues were also tracked for Joomla 2.5: [[Potential backward compatibility issues in Joomla 2.5 and Joomla Platform 11.4]]

= Platform =
The platform removed a larger number of deprecated classes and methods. For most extensions written for Joomla 2.5 the required changes should be reasonably small. Note that there are still deprecated classes in the platform that will be removed in future versions, developers should stop using them where possible.

== Updated System Requirements ==
The system requirements have changed in the following points:
*PHP 5.3.1
*register_globals must be off
*magic_quotes_gpc must be off

== General changes ==
*Almost all functions, methods, members and classed marked as deprecated in 12.1 have been removed. They won't be listed in this document.
*Appending ?no_html to an URL to get a RAW view is not supported anymore (this was an old Joomla 1.0 feature)
*The DS constant has been removed. If you really need it you can use DIRECTORY_SEPARATOR instead
*Many more function arguments have been type hinted, including existing classes. Make sure you're always passing values of the correct type.
*The name of modules now have to start with mod_
*Extensions need to set the registeredurlparams now, the fall back on the URL has been removed.
*Some cookies are only accessible trough HTTP (not via JavaScript). For example the session cookie.
*Due to upcoming changes to the MVC implementation in the platform, JModel, JView, and JController are re-used as the names of the new interfaces. For now use JModelLegacy, JViewLegacy and JControllerLegacy instead.

== Changes to extension installation ==
*Use of the <install> base tag (from 1.5) is no longer supported; use <extension> instead
*Suppport for install_script and uninstall_script, and the methods com_install and com_uninstall in these scripts, has been removed; use scriptfile instead
*In language extensions, support for client="both" has been removed; package each client as a separate extension and optionally bundle them as a package extension instead
*File paths for plugins no longer support the old 1.5 method (i.e. plugins/system/cache.php); each plugin must be in its own folder (i.e. plugins/system/cache/cache.php)

== Changes to Components ==
*In admin components the admin.*.php and toolbar.*.php are not automatically included anymore. This was a Joomla 1.0 legacy feature.

== Moved files ==
All classes listed here should now be autoloadable. Explicit requires and includes have to be modified or removed.

=== Classes moved to the CMS ===
*JFormFieldHelpsite
*JFormFieldMedia
*JFormFieldMenuitem
*JFormFieldUser
*JHelp
*JTableContent

=== Classes moved within the platform ===
*JDatabaseQuery subclasses
*JInput (and all subclasses)
*JTable (and all subclasses)
*JArchive (and all subclasses)

== Renamed classes ==
*JFTP is now called JClientFtp
*JLDAP is now called JClientLdap
*JWebClient is now called JApplicationWebClient

== Removed classes ==
*JParameter (use JForm instead)
*JElement and its subclasses
*JFormFieldEditors (use JFormFieldPlugins instead)
*JHtmlImage
*JSimpleXML
*JPane

== Changes to classes ==

=== Base classes ===

==== JFactory ====
*JFactory::getXMLParser() has been removed. For RSS and Atom use cases, use JFactory::getFeedParser() instead. To read XML files or strings use JFactory::getXML().
*JFactory::_createConfig() has been removed. Use JFactory::createConfig() instead.
*JFactory::_createSession() has been removed. Use JFactory::createSession() instead.
*JFactory::_createDbo() has been removed. Use JFactory::createDbo() instead.
*JFactory::_createMailer() has been removed. Use JFactory::createMailer() instead.
*JFactory::_createDocument() has been removed. Use JFactory::createDocument() instead.

=== Application ===

==== JApplicationHelper ====
*JApplicationHelper::getPath() has been removed. No replacement.
*JApplicationHelper::_checkPath() has been removed. No replacement.

==== JController ====
*JController::$_acoSection has been removed.
*JController::$_acoSectionValue has been removed.
*JController::authorize() has been removed. Use JController::authorise() instead.
*JController:: setAccessControl() has been removed. Use JAccess.

==== JControllerLegacy ====
* JControllerLegacy::display() needs an extra parameter: ($cachable = false, $urlparams = false).

=== Archive ===

==== Adapters ====
*JArchiveBzip2 does not extend JObject anymore. You must not use any of JObject's methods.
*JArchiveGzip does not extend JObject anymore. You must not use any of JObject's methods.
*JArchiveTar does not extend JObject anymore. You must not use any of JObject's methods.
*JArchiveZip does not extend JObject anymore. You must not use any of JObject's methods.

=== Base ===

==== JObject ====
*JObject::toString() has been removed. Use JObject::__toString() instead.

=== Client ===

==== JClientLdap (formerly JLDAP) ====
*JClientLdap does not extend JObject anymore. You must not use any of JObject's methods.

=== Database ===
JDatabase had been renamed JDatabaseDriver. JDatabase is still around (but deprecated) and is the base of JDatabaseDriver, this way type hints and instance of checks keep working.

Due to lazy-connecting a connection is only opened when running a query or explicitly calling JDatabseDriver::connected(). Beware of that when checking JDatabaseDriver::connected().

==== JDatabase ====
*JDatabase::$hasQuoted has been removed.
*JDatabase::$quoted has been removed.
*JDatabase::addQuoted() has been removed.
*JDatabase::hasUTF() has been removed.
*JDatabase::debug() has been removed. Use JDatabase::setDebug() instead.
*JDatabase::explain() has been removed.
*JDatabase::getEscaped() has been removed. Use JDatabase::escape() instead.
*JDatabase::getTableFields() has been removed. Use JDatabase::getTableColumns() instead.
*JDatabase::getTicker() has been removed. Use JDatabase::count() instead.
*JDatabase::isQuoted() has been removed.
*JDatabase::loadResultArray() has been removed. Use JDatabase::loadColumn() instead.
*JDatabase::nameQuote() has been removed. Use JDatabase::quoteName() instead.
*JDatabase::queryBatch() has been removed.

=== Document ===

==== JDocument ====
*JDocument::setMetaData() the $sync argument has been removed. It was broken beyond repair.

==== JDocumentRenderer ====
*JDocumentRenderer does not extend JObject anymore. You must not use any of JObject's methods.

==== JDocumentFeed ====
*JFeedItem does not extend JObject anymore. You must not use any of JObject's methods.
*JFeedEnclosure does not extend JObject anymore. You must not use any of JObject's methods.
*JFeedImage does not extend JObject anymore. You must not use any of JObject's methods.

==== JDocumentOpenSearch ====
*JOpenSearchUrl does not extend JObject anymore. You must not use any of JObject's methods.
*JOpenSearchImage does not extend JObject anymore. You must not use any of JObject's methods.

==== JDocumentXml ====
*JDocumentXml::_name has been renamed to JDocumentXml::name

=== Environment ===

==== JBrowser ====
*JBrowser does not extend JObject anymore. You must not use any of JObject's methods.
*JBrowser::setQuirk() has been removed.
*JBrowser::hasQuirk() has been removed.
*JBrowser::getQuirk() has been removed.
*JBrowser::setFeature() has been removed.
*JBrowser::hasFeature() has been removed.
*JBrowser::getFeature() has been removed.
*JBrowser::_majorVersion has been renamed to JBrowser::majorVersion
*JBrowser::_minorVersion has been renamed to JBrowser::minorVersion
*JBrowser::_browser has been renamed to JBrowser::browser
*JBrowser::_agent has been renamed to JBrowser::agent
*JBrowser::_lowerAgent has been renamed to JBrowser::lowerAgent
*JBrowser::_accept has been renamed to JBrowser::accept
*JBrowser::_accept_parsed has been renamed to JBrowser::acceptParsed
*JBrowser::_platform has been renamed to JBrowser::platform
*JBrowser::_robots has been renamed to JBrowser::robots
*JBrowser::_mobile has been renamed to JBrowser::mobile
*JBrowser::_images has been renamed to JBrowser::images

==== JRequest ====
*JRequest::clean() has been removed.
*JRequest::_cleanVar() is now protected.

==== JURI ====
*JURI does not extend JObject anymore. You must not use any of JObject's methods.
*JUri::_uri has been renamed to JUri::uri
*JUri::_scheme has been renamed to JUri::scheme
*JUri::_host has been renamed to JUri::host
*JUri::_port has been renamed to JUri::port
*JUri::_user has been renamed to JUri::user
*JUri::_pass has been renamed to JUri::pass
*JUri::_path has been renamed to JUri::path
*JUri::_query has been renamed to JUri::query
*JUri::_fragment has been renamed to JUri::fragment
*JUri::_vars has been renamed to JUri::vars

=== Error ===

==== JError ====
*JError::isError() has been removed. Use instance of Exception instead.

==== JProfiler ====
*JProfiler does not extend JObject anymore. You must not use any of JObject's methods.
*JProfiler::_start has been renamed to JProfiler::start
*JProfiler::_prefix has been renamed to JProfiler::prefix
*JProfiler::_buffer has been renamed to JProfiler::buffer
*JProfiler::_previous_time has been renamed to JProfiler::previousTime
*JProfiler::_previous_mem has been renamed to JProfiler::previousMem
*JProfiler::_iswin has been renamed to JProfiler::isWin

=== Filesystem ===

==== JStream ====
*JStream::_fh has been renamed to JStream::fh
*JStream::_filesize has been renamed to JStream::filesize
*JStream::_context has been renamed to JStream::context
*JStream::_contextOptions has been renamed to JStream::contextOptions
*JStream::_openmode has been renamed to JStream::openmode

==== JStreamString ====
*JStream::_currentstring has been renamed to JStream::currentString
*JStream::_path has been renamed to JStream::path
*JStream::_mode has been renamed to JStream::mode
*JStream::_options has been renamed to JStream::options
*JStream::_opened_path has been renamed to JStream::openedPath
*JStream::_pos has been renamed to JStream::pos
*JStream::_len has been renamed to JStream::len
*JStream::_stat has been renamed to JStream::stat

=== Filter ===

==== JFilterInput ====
*JFilterInput does not extend JObject anymore. You must not use any of JObject's methods.

=== HTML ===

==== JHtml ====
*JHtml::_includeRelativeFiles() has been removed. Use JHtml::includeRelativeFiles() instead.
*JHtml::core() has been removed. Use JHtmlBehavior::framework() instead.
*JHtml::script() doesn't support a string as the second parameter anymore. This used to be the path to the file in Joomla 1.5 and has been removed now.
*JHtml::stylesheet() doesn't support a string as the second parameter anymore. This used to be the path to the file in Joomla 1.5 and has been removed now.

==== JHtmlAccess ====
*JHtmlAccess::assetgroups() the argument $config has been removed. It was previously unused.

==== JHtmlBehavior ====
*JHtmlBehavior::mootools() has been removed. Use JHtmlBehavior::framework instead.
*JHtmlBehavior::noframes() the argument $location has been removed. It was previously unused.

==== JHtmlList ====
*JHtmlList::ordering() the argument $chop has been removed. It was previously unused.
*JHtmlList::users(), the argument $reg has been removed.

==== JHtmlSelect ====
*JHtmlSelect::_optionDefaults has been renamed to JHtmlSelect::optionDefaults

==== JToolBar ====
*JToolBar does not extend JObject anymore. You must not use any of JObject's methods.

==== JButton ====
*JButton does not extend JObject anymore. You must not use any of JObject's methods.

==== JPagination ====
*JPagination::_viewall has been renamed to JPagination::viewall
*JPagination::_additionalUrlParams has been renamed to JPagination::additionalUrlParams

=== Installer ===

==== JInstaller ====
*JInstaller::getOverwrite() has been removed. Use JInstaller::isOverwrite() instead.
*JInstaller::getUpgrade() has been removed. Use JInstaller::isUpgrade() instead.
*JInstaller::_paths has been renamed to JInstaller::paths
*JInstaller::_upgrade has been renamed to JInstaller::upgrade
*JInstaller::_overwrite has been renamed to JInstaller::overwrite
*JInstaller::_stepStack has been renamed to JInstaller::stepStack

==== JInstallerLanguage ====
*JInstallerLanguage::_core as been renamed to JInstallerLanguage::core

=== Language ===

==== JLanguage ====
*JLanguage::getPluralSufficesCallback() has been removed. Use JLanguage::getPluralSuffixesCallback() instead.
*JLanguage::_parseLanguageFiles() has been removed. Use JLanguage::parseLanguageFiles() instead.
*JLanguage::_parseXMLLanguageFiles() has been removed. Use JLanguage::parseXMLLanguageFiles() instead.
*JLanguage::_parseXMLLanguageFile() has been removed. Use JLanguage::parseXMLLanguageFile() instead.
*JLanguage::loadLanguage() the argument $overwrite has been removed. It was previously unused.

=== Registry ===

==== JRegistry ====
*JRegistry::loadXML() has been removed. Use JRegistry::loadString() instead.
*JRegistry::loadINI() has been removed. Use JRegistry::loadString() instead.
*JRegistry::loadJSON() has been removed. Use JRegistry::loadString() instead.
*JRegistry::makeNameSpace() has been removed. No replacement.
*JRegistry::getNameSpaces() has been removed. No replacement.
*JRegistry::getValue() has been removed. Use JRegistry::get() instead.
*JRegistry::setValue() has been removed. Use JRegistry::set() instead.
*JRegistry::loadSetupFile() has been removed. No replacement.

==== JRegistryFormatINI ====
* JRegistryFormatINI::stringToObject() the second argument ($option) may not be a boolean anymore.

==== JRegistryFormatJSON ====
*JRegistryFormatJSON::stringToObject() the second argument ($option) may not be a boolean anymore.

=== Session ===

==== JSessionStorageDatabase ====
*JSessionStorageDatabase::_data has been renamed to JSessionStorageDatabase::data

=== Table ===

==== JTable ====
*JTable::canDelete() has been removed.
*JTable::toXML() has been removed.

=== Updater ===

==== JUpdate ====
*JUpdate::_xml_parser has been renamed to JUpdate::xmlParser
*JUpdate::_stack has been renamed to JUpdate::stack
*JUpdate::_state_store has been renamed to JUpdate::stateStore
*JUpdate::_current_update has been renamed to JUpdate::currentUpdate

==== JUpdater ====
*JUpdater::arrayUnique() has been removed. Use JArrayHelper::arrayUnique() instead.

=== User ===

==== JAuthentication ====
*The constant JAUTHENTICATE_STATUS_SUCCESS has been removed. Use JAuthentication::STATUS_SUCCESS instead.
*The constant JAUTHENTICATE_STATUS_CANCEL has been removed. No replacement.
*The constant JAUTHENTICATE_STATUS_FAILURE has been removed. Use JAuthentication:: STATUS_FAILURE instead.
*JAuthentication::_observers has been renamed to JAuthentication::observers
*JAuthentication::_state has been renamed to JAuthentication::state
*JAuthentication::_methods has been renamed to JAuthentication::methods

==== JUser ====
*JUser::getParameters() has been removed.
*Juser::authorisedLevels() has been removed. Use JUser::getAuthorisedViewLevels() instead.
*Juser::authorize() has been removed. Use JUser::authorise() instead.
*JUser::$usertype has been removed.

=== Utility ===

==== JBuffer ====
*JBuffer::_buffers has been renamed to JBuffer::buffers

==== JDate ====
*JDate::toMysql() has been removed. Use JDate::toSql() instead.
*JDate::toFormat() has been removed. Use JDate::format() instead.
*JDate::setOffset() has been removed.
*JDate::$offsets has been removed.
*JDate__construct() doesn't accept an numeric value for $tz anymore.
*JDate::_tz has been renamed to JDate::tz.

==== JUtility ====
*JUtility::sendMail() has been removed. Use JMail::sendMail() instead.
*JUtility::sendAdminMail() has been removed. Use JMail:: sendAdminMail() instead.
*JUtility::getHash() has been removed. Use JApplication::getHash() instead.
*JUtility::getToken() has been removed. Use JSession::getFormToken() instead.
*JUtility::isWinOS() has been removed. Use JApplication::isWinOS() instead.
*JUtility::dump() has been removed. No replacement.
*JUtility::array_unshift_ref() has been removed. No replacement.
*JUtility:: array_unshift_ref() has been removed. No replacement.

==== JXMLElement ====
*JXMLElement::data() has been removed
*JXMLElement::getAttribute() has been removed. Use SimpleXMLElement::attributes() instead.

== JavaScript ==
*Compatibility with MooTools 1.2 has been removed
*Forms that have name="adminForm" now also require id="adminForm"
*checkAll() has been removed. Use Joomla.checkAll() instead.
*isChecked() has been removed. Use Joomla.isChecked() instead.
*popupWindow() has been removed. Use Joomla.popupWindow() instead.
*tableOrdering() has been removed. Use Joomla.tableOrdering() instead.

= CMS =

== General changes ==
*JUtility is not always loaded. If you need it you have to add jimport('joomla.utilities.utility'); to your code.

== Changes to classes ==

=== Component Classes ===
*MenusModelItem::getItem() no longer returns a JObject but a stdClass.

=== Help ===

==== JHelp ====
*JHelp::createSiteList() the argument $selected has been removed. It was unused.

[[Category:Compatibility]]
[[Category:Development]]
[[Category:Framework]]

IIS

2012-04-05T22:20:39Z

HobbesPDX:

Whilst IIS (Internet Information Services, a Microsoft web server) accounts for relatively few users, compared to Apache, there are enough to warrant providing information which is unique.

PHP can run on IIS, so a Joomla! web site also can run on IIS.

The PHP.net website should be referenced, regarding the installation of PHP on Windows and the configuration of IIS to process PHP webpages and scripts.

To get started, here are some helpful links for developers who want to install PHP and Joomla! on IIS.

* Install Joomla for Windows and IIS using the Web Platform Installer - http://www.microsoft.com/web/joomla
* PHP on Windows and IIS; building an IIS-optimized PHP - http://www.microsoft.com/web/php

The two most common problems encountered by Joomla! admins whose sites are on IIS webservers are:
* Setting the website's directory/filesystem permissions correctly
* Enabling SEF URLs

==Setting the filesystem permissions==

===Conceptual Overview===
Windows filesystem permissions are more complex than the 3-level, 3-value Unix-style <code>rw-r--r--</code> conventions.

Windows servers have a user called <code>IUSR</code>, which corresponds to the <code>apache</code> user on many Linux systems. PHP scripts run under the IUSR account.
(For IIS 7.5, this may be the group WEB\Users)

====Levels====
A directory or file does have an <code>owner</code>, and Windows does have <code>group</code>s, but there is no <code>"everyone else"</code> under Windows.

There is a group called <code>Users</code>. This corresponds to all accounts used by human beings to deliberately interact with the server. But accounts for services, system operations, and software user permisions do not belong to that group, and in fact '''no''' accounts at all (human or otherwise) have '''any''' privileges which aren't explicitly granted either directly to the user or by membership in some group.

====Values====
Beyond <code>Read</code>, <code>Write</code> and <code>Execute</code>, Windows permissions include additional values. The important ones to know about for a Joomla website are <code>Read</code> and <code>Write</code>.

===HowTo configure the permissions===
When logged in to the Windows server, run Windows Explorer, and navigate to inetpub.

Right-click the directory which holds your Joomla site.<br />
Get Properties, tab to Security.<br />
Click ADD.<br />
Make sure that the LOCATION field is set to the local computer, not a domain controller.<br />
Type iis_iusrs into the field for identifying the user/group you are granting access to.<br />
Confirm.<br />
Highlight the iis_iusrs entry in the access control list.<br />
Check the boxes for Read & Execute, List Folder Contents, Read, and Write<br />
Confirm, put the security window away now.<br />
Open Start -. Administrator -> Computer Management.<br />
Navigate to Local Users and Groups -> Groups.<br />
Find or create the group iis_iusrs<br />
Add a member to the group:<br />
again, make sure that the LOCATION field is set to the local computer, not a domain controller.<br />
Type IUSR into the field for identifying the user/group you are granting access to.<br />
Confirm.<br />
Save.<br />

Run the Joomla installer again, and enjoy your PHP user's write privileges in your website folder.

==[[Search Engine Friendly URLs]]==
The functioning of SEF URLs depends on "URL rewriting" - matching patterns in incoming HTTP requests, and passing the request to the webserver in a different format. Joomla can only understand the parameters present in the "ugly" request, so the human-readable path in the incoming HTTP request needs to be re-written for Joomla.

===Apache's mod_rewrite===
<code>mod_rewrite</code> is the familiar way by which many webmasters translate nice human-readable, spider-friendly URL requests like <code>/about_us/contact_information</code> into the "ugly" internal server path like <code>/index.php?option=com_content&view=article&id=999&Itemid=23</code> that makes Joomla serve up some content. A text file called .htaccess contains the rewrite rules, which are written according to a specific syntax.

===IIS===
Before Windows Server 2008 and IIS7, only third-party add-ons could add URL rewriting functionality to an IIS webserver. For servers today still running IIS6 or earlier, these are still available. CodePlex is a website and code-sharing developer forge associated with Microsoft, and it hosts at least two good-quality URL rewrite solutions for IIS6. At least one of these modules will parse and execute the same rewrite rules which work in Apache .htaccess files.

Windows Server 2008 comes with IIS7, which is the first webserver for which Microsoft provides a native module which provides URL rewriting functionality.

The module is called "IIS URL Rewrite Module" and is free to download and install on your IIS7 webserver.

The IIS7 module configures and stores its rules in a very different way than the format Apache provides via .htaccess. The rules are stored as XML data in the web.config file in a website's root. The IIS Management Console provides a GUI and wizard for creating and testing rules. The wizard is capable of reading a text file with .htaccess-type rules and converting them to the native format.

See [[Enabling Search Engine Friendly (SEF) URLs on IIS]] for instructions.

==[[Restricting access to the backend by IP address]]==

You can utilise server based IP protection.
If you're running IIS 7.5 on Windows Server 2008, you can use the IP and
Domain Security option. Go to the Server Manager MMC panel and select
"Roles" and then "Web Server (IIS). From here select "Add Role Services" and
in the window that pops up, scroll down to security and select the "IP And
Domain Security Option" (see screenshot below)
[[File:IPrestrictionIIS.jpg]]
and then hit next to install.
Once you've got it installed, open up the IIS Manager MMC panel (if you have
it open already, you will need to restart it for the appropriate panel to
appear; this also means the server manager one might not be useful to you)
and navigate down to the administrator directory of the site. Click on the
"IPv4 Address and Domain Restrictions". You can change the default behaviour
by clicking "Edit Feature Settings" and setting the default value for
unspecified clients to deny. Then add allow entries for your trusted IP
addresses or subnets.
Check out the following article for details as well:
[[http://www.iis.net/ConfigReference/system.webServer/security/ipSecurity]]
(thanks to Sam Moffat for above info)

<noinclude>[[Category:IIS]][[Category:FAQ]]</noinclude>

Pizza Bugs and Fun March 3, 2012

2012-02-22T17:20:53Z

HobbesPDX: Removing Portland event. Couldn't get anyone other than myself involved.... :(

[[Category:Bug Squad]]
[[Category:Development]]
[[Image:pbf.png|right]]
{{RightTOC}}

We are announcing a Joomla! Pizza, Bugs and Fun event scheduled for Saturday, March 3, 2012. The event is global for virtual participants with local venues where ever they are organized. We squashed a lot of bugs last month, but as more people use a new release, we always find more. We'll also have documentation ready to be worked on.

'''See the section [http://docs.joomla.org/Pizza_Bugs_and_Fun_March_3,_2012#General_Instructions General Instructions] below for instructions.'''

This wiki will be used as the central resource for coordinating efforts and accumulating results from this event.

The '''twitter''' hash tag is #jpbf12.

== Goals ==

* '''Bugs''' : We will be working through the [http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemBrowse&tracker_id=8103 CMS Issue Tracker] where there are bug reports needing patches and/or testing.

* '''Documentation''' : We still have documentation that needs to be done. If you want to help out writing documentation, you're also more than welcome.

== Organization, logistics and communications ==

=== Communication ===
We have set up a Skype chat for all attendees of the PBF. Skype is invitation only and you are all invited. This is the same chat we used for the PBF in December. To get an invitation, email your Skype name to Andy Tarr (andrea.tarr@joomla.org). To make sure you can get in, get your invitation and log in before the day of the PBF. This Skype chat will be in English, but other languages can set up their own chat groups as well.

=== General Instructions ===

These instructions may change as we get closer to the event.

==== If you want to code bug fixes ====
* Look for issues with a status of Confirmed
* Before you start coding, find the issue in the [https://docs.google.com/spreadsheet/ccc?key=0AuHNF8-wsi3tdGtOU0lqSThaLXB4NDJCUTBMNkxzcXc#gid=0 CMS Issues Google doc] and put your name on the issue so people know someone is working on it. You can sign things out to a group if a group is working on any issue. Remember that everyone is seeing the same document, so please don't hide rows.
* Use the [http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemBrowse&tracker_id=8103 CMS Issue Tracker] as usual, which means you download the patch from the tracker and apply it to a current SVN copy of Joomla.
* When you have a patch, add it to the tracker and change the status to Pending if you are able to.
* Go back into the Google doc and change the status there to Pending as well and remove your name and add a comment with your name that you added a patch. If the tracker still needs to be changed to pending, you can mention it there.
Helpful documentation:
* [[Setting up your workstation for Joomla! development]]. A step-by-step guide to installing the Eclipse IDE on your local workstation for Joomla! development.
* [http://community.joomla.org/blogs/community/828-webinar-using-eclipse-for-joomla-development.html Using Eclipse for Joomla! Development] Video webinar demonstrating overview of Eclipse features for Joomla! development
* [[Tortoise SVN]]
* [[Secure coding guidelines]]
* [[Development Best Practices]]

==== If you want to test and you have or can set up SVN and XAMPP/MAMP ====
* Look for issues with a status of Pending. We want at least 2 testers and more on complex issues, so you can test what others have tested already.
* Use the [http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemBrowse&tracker_id=8103 CMS Issue Tracker] as usual, which means you download the patch from the tracker and apply it to a current SVN copy of Joomla.
* Most of the issues should have test instructions with them.
* Once you have tested, add comments to the tracker on your results. Start your comment with @test so you will get counted in the stats as a tester.
Helpful Documentation:
* [[Tortoise SVN]] Freestanding Windows based SVN. This may be all you need, if you have a Windows PC
* [http://www.adobe.com/devnet/dreamweaver/articles/using_subversion_pt1.html Dreamweaver CS5 with SVN] Start of tutorials on how to use SVN in Dreamweaver
* [[Setting up your workstation for Joomla! development]]. A step-by-step guide to installing the Eclipse IDE on your local workstation for Joomla! development. This also guides you through installing XAMPP/MAMP on your computer.
* [http://community.joomla.org/blogs/community/828-webinar-using-eclipse-for-joomla-development.html Using Eclipse for Joomla! Development] Video webinar demonstrating overview of Eclipse features for Joomla! development

==== If you want to work on Documentation ====
* To edit this Documentation Wiki, you will need a user account. If you don't already have one, you may register on [[Special:UserLogin]]. While a brand new user account won't give you all the permissions you'd get with a confirmed and "elevated" account, you will be able to edit most pages.
* Get your user account a few days before and make sure that you are able to sign in since the automatic authorization system can lock some people out.
* If you'd like something to be edited, but you're not sure what to write exactly, use talk pages to add comments to pages.
* During the PBF, several experienced Wiki editors will be available in the Skype chat to help you.
{{:Documentation wiki}}

===== Help Screens =====
* There are help screens that still need to be made for 2.5 [[Help17:Help screens]]

=== Pizza ===
We are offering pizza and soda for pre-registered groups. We aren’t setting a specific maximum, but please don’t go crazy with it. Get enough so there’s plenty for everyone, but not a week’s worth of pizza and soda leftovers for everyone. Contact Andrea Tarr (andrea.tarr@joomla.org) before the event to register and get details.

== Locations ==

If you want to get people together and have a venue to share, please add it below. Share as much as possible details like exact location, url for more information about the venue, ways to register, date and time the venue is available etc.

If you set up a location please send contact information to Andy Tarr (andrea.tarr@joomla.org). Feel free to contact her with any questions.

=== Europe ===

=== North America ===

[http://www.joomlanewengland.org Joomla User Group New England]
Marlboro College Graduate School
28 Vernon Street
Brattleboro, VT 05301
Contact: Andrea Tarr

=== South America ===

=== Asia/Pacific ===
<pre>
Sydney, Australia 3pm-9pm
Hosted by Tim Plummer - Tweet @bfsurvey
InterfaceFLOR (usual Sydney JUG venue)
101 Chalmers Street, Surry Hills, NSW
http://www.meetup.com/Joomla-User-Group-Sydney/events/53020132/
</pre>

=== Africa ===

=== Middle East ===

===Virtual===
====Skype Chat====
We have set up a Skype chat for all attendees of the PBF. Skype is invitation only. This is the same Skype chat we used in December. To get an invitation, email your Skype name to Andy Tarr (andrea.tarr@joomla.org). To make sure you can get in, get your invitation and log in before the day of the PBF.

If you don't already have Skype, you can download it for free from [http://skype.com Skype].

== Registration ==
=== For write access to this wiki ===
To get write access to this wiki you will need to [[Special:Userlogin|register here first]]. Please be aware that the registration process requires a valid email address. This is the same login for updating Joomla documentation.

=== At a physical location ===
If you wish to be present at one of the physical locations listed above then you must register in advance because space most likely is limited. Registrations are the responsibility of the individual location organizers and you should click on the appropriate link above for more information.

=== Taking bugs, tasks and pizza ===

Please check the [http://docs.joomla.org/Pizza_Bugs_and_Fun_March_3,_2012#Organization.2C_logistics_and_communications Organization, logistics and communications section] for detail on how to get involved in working on tasks.

==Requirements==
* All code must be made available under the [http://www.gnu.org/licenses/gpl-2.0.html General Public Licence version 2].
* All documentation contributions must be made available under the [[JEDL|Joomla! Electronic Documentation License]]. Further information on the JEDL is available in the [[JEDL/FAQ|JEDL Frequently Asked Questions]]
* No advertising or self-promotion will be allowed. This includes back links to your website or anyone else's. The one exception is that if you have made a contribution then feel free to add your name and an optional link to your website to the [[Pizza Bugs and Fun 2011/Contributors List|Contributors List]]
* All contributions must be in English. Note that the official language of the Joomla! project is British English.

== FAQ ==
Q: Where is the SVN for Joomla?

A: http://joomlacode.org/svn/joomla/development/trunk

Q: Which one is 2.5?

A: It is the main trunk

Q: Any known issues with JForge and Chrome on Windows?

A: It have been seen that browsing the JForge tracker, Chrome may ask for a missing plugin (windows media player). No workaround for this is yet known.

==Contributors==
{{:Pizza Bugs and Fun March 3, 2012/Contributors List}}

Pizza Bugs and Fun March 3, 2012

2012-02-10T06:35:38Z

HobbesPDX: /* North America */

[[Category:Bug Squad]]
[[Category:Development]]
[[Image:pbf.png|right]]
{{RightTOC}}

We are announcing a Joomla! Pizza, Bugs and Fun event scheduled for Saturday, March 3, 2012. The event is global for virtual participants with local venues where ever they are organized. We squashed a lot of bugs last month, but as more people use a new release, we always find more. We'll also have documentation ready to be worked on.

'''See the section [http://docs.joomla.org/Pizza_Bugs_and_Fun_March_3,_2012#General_Instructions General Instructions] below for instructions.'''

This wiki will be used as the central resource for coordinating efforts and accumulating results from this event.

The '''twitter''' hash tag is #jpbf12.

== Goals ==

* '''Bugs''' : We will be working through the [http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemBrowse&tracker_id=8103 CMS Issue Tracker] where there are bug reports needing patches and/or testing.

* '''Documentation''' : We still have documentation that needs to be done. If you want to help out writing documentation, you're also more than welcome.

== Organization, logistics and communications ==

=== Communication ===
We have set up a Skype chat for all attendees of the PBF. Skype is invitation only and you are all invited. This is the same chat we used for the PBF in December. To get an invitation, email your Skype name to Andy Tarr (andrea.tarr@joomla.org). To make sure you can get in, get your invitation and log in before the day of the PBF. This Skype chat will be in English, but other languages can set up their own chat groups as well.

=== General Instructions ===

These instructions may change as we get closer to the event.

==== If you want to code bug fixes ====
* Look for issues with a status of Confirmed
* Before you start coding, find the issue in the [https://docs.google.com/spreadsheet/ccc?key=0AuHNF8-wsi3tdGtOU0lqSThaLXB4NDJCUTBMNkxzcXc#gid=0 CMS Issues Google doc] and put your name on the issue so people know someone is working on it. You can sign things out to a group if a group is working on any issue. Remember that everyone is seeing the same document, so please don't hide rows.
* Use the [http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemBrowse&tracker_id=8103 CMS Issue Tracker] as usual, which means you download the patch from the tracker and apply it to a current SVN copy of Joomla.
* When you have a patch, add it to the tracker and change the status to Pending if you are able to.
* Go back into the Google doc and change the status there to Pending as well and remove your name and add a comment with your name that you added a patch. If the tracker still needs to be changed to pending, you can mention it there.
Helpful documentation:
* [[Setting up your workstation for Joomla! development]]. A step-by-step guide to installing the Eclipse IDE on your local workstation for Joomla! development.
* [http://community.joomla.org/blogs/community/828-webinar-using-eclipse-for-joomla-development.html Using Eclipse for Joomla! Development] Video webinar demonstrating overview of Eclipse features for Joomla! development
* [[Tortoise SVN]]
* [[Secure coding guidelines]]
* [[Development Best Practices]]

==== If you want to test and you have or can set up SVN and XAMPP/MAMP ====
* Look for issues with a status of Pending. We want at least 2 testers and more on complex issues, so you can test what others have tested already.
* Use the [http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemBrowse&tracker_id=8103 CMS Issue Tracker] as usual, which means you download the patch from the tracker and apply it to a current SVN copy of Joomla.
* Most of the issues should have test instructions with them.
* Once you have tested, add comments to the tracker on your results. Start your comment with @test so you will get counted in the stats as a tester.
Helpful Documentation:
* [[Tortoise SVN]] Freestanding Windows based SVN. This may be all you need, if you have a Windows PC
* [http://www.adobe.com/devnet/dreamweaver/articles/using_subversion_pt1.html Dreamweaver CS5 with SVN] Start of tutorials on how to use SVN in Dreamweaver
* [[Setting up your workstation for Joomla! development]]. A step-by-step guide to installing the Eclipse IDE on your local workstation for Joomla! development. This also guides you through installing XAMPP/MAMP on your computer.
* [http://community.joomla.org/blogs/community/828-webinar-using-eclipse-for-joomla-development.html Using Eclipse for Joomla! Development] Video webinar demonstrating overview of Eclipse features for Joomla! development

==== If you want to work on Documentation ====
* To edit this Documentation Wiki, you will need a user account. If you don't already have one, you may register on [[Special:UserLogin]]. While a brand new user account won't give you all the permissions you'd get with a confirmed and "elevated" account, you will be able to edit most pages.
* Get your user account a few days before and make sure that you are able to sign in since the automatic authorization system can lock some people out.
* If you'd like something to be edited, but you're not sure what to write exactly, use talk pages to add comments to pages.
* During the PBF, several experienced Wiki editors will be available in the Skype chat to help you.
{{:Documentation wiki}}

===== Help Screens =====
* There are help screens that still need to be made for 2.5 [[Help17:Help screens]]

=== Pizza ===
We are offering pizza and soda for pre-registered groups. We aren’t setting a specific maximum, but please don’t go crazy with it. Get enough so there’s plenty for everyone, but not a week’s worth of pizza and soda leftovers for everyone. Contact Andrea Tarr (andrea.tarr@joomla.org) before the event to register and get details.

== Locations ==

If you want to get people together and have a venue to share, please add it below. Share as much as possible details like exact location, url for more information about the venue, ways to register, date and time the venue is available etc.

If you set up a location please send contact information to Andy Tarr (andrea.tarr@joomla.org). Feel free to contact her with any questions.

=== Europe ===

=== North America ===

[http://www.joomlanewengland.org Joomla User Group New England]
Marlboro College Graduate School
28 Vernon Street
Brattleboro, VT 05301
Contact: Andrea Tarr

[http://www.joomlapdx.com/ Portland Joomla! User Group]
Location: TBD
Contact: Ben Sandberg

=== South America ===

=== Asia/Pacific ===

=== Africa ===

=== Middle East ===

===Virtual===
====Skype Chat====
We have set up a Skype chat for all attendees of the PBF. Skype is invitation only. This is the same Skype chat we used in December. To get an invitation, email your Skype name to Andy Tarr (andrea.tarr@joomla.org). To make sure you can get in, get your invitation and log in before the day of the PBF.

If you don't already have Skype, you can download it for free from [http://skype.com Skype].

== Registration ==
=== For write access to this wiki ===
To get write access to this wiki you will need to [[Special:Userlogin|register here first]]. Please be aware that the registration process requires a valid email address. This is the same login for updating Joomla documentation.

=== At a physical location ===
If you wish to be present at one of the physical locations listed above then you must register in advance because space most likely is limited. Registrations are the responsibility of the individual location organizers and you should click on the appropriate link above for more information.

=== Taking bugs, tasks and pizza ===

Please check the [http://docs.joomla.org/Pizza_Bugs_and_Fun_March_3,_2012#Organization.2C_logistics_and_communications Organization, logistics and communications section] for detail on how to get involved in working on tasks.

==Requirements==
* All code must be made available under the [http://www.gnu.org/licenses/gpl-2.0.html General Public Licence version 2].
* All documentation contributions must be made available under the [[JEDL|Joomla! Electronic Documentation License]]. Further information on the JEDL is available in the [[JEDL/FAQ|JEDL Frequently Asked Questions]]
* No advertising or self-promotion will be allowed. This includes back links to your website or anyone else's. The one exception is that if you have made a contribution then feel free to add your name and an optional link to your website to the [[Pizza Bugs and Fun 2011/Contributors List|Contributors List]]
* All contributions must be in English. Note that the official language of the Joomla! project is British English.

== FAQ ==
Q: Where is the SVN for Joomla?

A: http://joomlacode.org/svn/joomla/development/trunk

Q: Which one is 2.5?

A: It is the main trunk

Q: Any known issues with JForge and Chrome on Windows?

A: It have been seen that browsing the JForge tracker, Chrome may ask for a missing plugin (windows media player). No workaround for this is yet known.

==Contributors==
{{:Pizza Bugs and Fun March 3, 2012/Contributors List}}

Pizza Bugs and Fun March 3, 2012

2012-02-10T06:35:30Z

HobbesPDX: refinement

[[Category:Bug Squad]]
[[Category:Development]]
[[Image:pbf.png|right]]
{{RightTOC}}

We are announcing a Joomla! Pizza, Bugs and Fun event scheduled for Saturday, March 3, 2012. The event is global for virtual participants with local venues where ever they are organized. We squashed a lot of bugs last month, but as more people use a new release, we always find more. We'll also have documentation ready to be worked on.

'''See the section [http://docs.joomla.org/Pizza_Bugs_and_Fun_March_3,_2012#General_Instructions General Instructions] below for instructions.'''

This wiki will be used as the central resource for coordinating efforts and accumulating results from this event.

The '''twitter''' hash tag is #jpbf12.

== Goals ==

* '''Bugs''' : We will be working through the [http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemBrowse&tracker_id=8103 CMS Issue Tracker] where there are bug reports needing patches and/or testing.

* '''Documentation''' : We still have documentation that needs to be done. If you want to help out writing documentation, you're also more than welcome.

== Organization, logistics and communications ==

=== Communication ===
We have set up a Skype chat for all attendees of the PBF. Skype is invitation only and you are all invited. This is the same chat we used for the PBF in December. To get an invitation, email your Skype name to Andy Tarr (andrea.tarr@joomla.org). To make sure you can get in, get your invitation and log in before the day of the PBF. This Skype chat will be in English, but other languages can set up their own chat groups as well.

=== General Instructions ===

These instructions may change as we get closer to the event.

==== If you want to code bug fixes ====
* Look for issues with a status of Confirmed
* Before you start coding, find the issue in the [https://docs.google.com/spreadsheet/ccc?key=0AuHNF8-wsi3tdGtOU0lqSThaLXB4NDJCUTBMNkxzcXc#gid=0 CMS Issues Google doc] and put your name on the issue so people know someone is working on it. You can sign things out to a group if a group is working on any issue. Remember that everyone is seeing the same document, so please don't hide rows.
* Use the [http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemBrowse&tracker_id=8103 CMS Issue Tracker] as usual, which means you download the patch from the tracker and apply it to a current SVN copy of Joomla.
* When you have a patch, add it to the tracker and change the status to Pending if you are able to.
* Go back into the Google doc and change the status there to Pending as well and remove your name and add a comment with your name that you added a patch. If the tracker still needs to be changed to pending, you can mention it there.
Helpful documentation:
* [[Setting up your workstation for Joomla! development]]. A step-by-step guide to installing the Eclipse IDE on your local workstation for Joomla! development.
* [http://community.joomla.org/blogs/community/828-webinar-using-eclipse-for-joomla-development.html Using Eclipse for Joomla! Development] Video webinar demonstrating overview of Eclipse features for Joomla! development
* [[Tortoise SVN]]
* [[Secure coding guidelines]]
* [[Development Best Practices]]

==== If you want to test and you have or can set up SVN and XAMPP/MAMP ====
* Look for issues with a status of Pending. We want at least 2 testers and more on complex issues, so you can test what others have tested already.
* Use the [http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemBrowse&tracker_id=8103 CMS Issue Tracker] as usual, which means you download the patch from the tracker and apply it to a current SVN copy of Joomla.
* Most of the issues should have test instructions with them.
* Once you have tested, add comments to the tracker on your results. Start your comment with @test so you will get counted in the stats as a tester.
Helpful Documentation:
* [[Tortoise SVN]] Freestanding Windows based SVN. This may be all you need, if you have a Windows PC
* [http://www.adobe.com/devnet/dreamweaver/articles/using_subversion_pt1.html Dreamweaver CS5 with SVN] Start of tutorials on how to use SVN in Dreamweaver
* [[Setting up your workstation for Joomla! development]]. A step-by-step guide to installing the Eclipse IDE on your local workstation for Joomla! development. This also guides you through installing XAMPP/MAMP on your computer.
* [http://community.joomla.org/blogs/community/828-webinar-using-eclipse-for-joomla-development.html Using Eclipse for Joomla! Development] Video webinar demonstrating overview of Eclipse features for Joomla! development

==== If you want to work on Documentation ====
* To edit this Documentation Wiki, you will need a user account. If you don't already have one, you may register on [[Special:UserLogin]]. While a brand new user account won't give you all the permissions you'd get with a confirmed and "elevated" account, you will be able to edit most pages.
* Get your user account a few days before and make sure that you are able to sign in since the automatic authorization system can lock some people out.
* If you'd like something to be edited, but you're not sure what to write exactly, use talk pages to add comments to pages.
* During the PBF, several experienced Wiki editors will be available in the Skype chat to help you.
{{:Documentation wiki}}

===== Help Screens =====
* There are help screens that still need to be made for 2.5 [[Help17:Help screens]]

=== Pizza ===
We are offering pizza and soda for pre-registered groups. We aren’t setting a specific maximum, but please don’t go crazy with it. Get enough so there’s plenty for everyone, but not a week’s worth of pizza and soda leftovers for everyone. Contact Andrea Tarr (andrea.tarr@joomla.org) before the event to register and get details.

== Locations ==

If you want to get people together and have a venue to share, please add it below. Share as much as possible details like exact location, url for more information about the venue, ways to register, date and time the venue is available etc.

If you set up a location please send contact information to Andy Tarr (andrea.tarr@joomla.org). Feel free to contact her with any questions.

=== Europe ===

=== North America ===

[http://www.joomlanewengland.org Joomla User Group New England]
Marlboro College Graduate School
28 Vernon Street
Brattleboro, VT 05301
Contact: Andrea Tarr

[http://www.joomlapdx.com/ Portland Joomla! User Group]
Location: TBD
Contact: Ben Sandberg

=== South America ===

=== Asia/Pacific ===

=== Africa ===

=== Middle East ===

===Virtual===
====Skype Chat====
We have set up a Skype chat for all attendees of the PBF. Skype is invitation only. This is the same Skype chat we used in December. To get an invitation, email your Skype name to Andy Tarr (andrea.tarr@joomla.org). To make sure you can get in, get your invitation and log in before the day of the PBF.

If you don't already have Skype, you can download it for free from [http://skype.com Skype].

== Registration ==
=== For write access to this wiki ===
To get write access to this wiki you will need to [[Special:Userlogin|register here first]]. Please be aware that the registration process requires a valid email address. This is the same login for updating Joomla documentation.

=== At a physical location ===
If you wish to be present at one of the physical locations listed above then you must register in advance because space most likely is limited. Registrations are the responsibility of the individual location organizers and you should click on the appropriate link above for more information.

=== Taking bugs, tasks and pizza ===

Please check the [http://docs.joomla.org/Pizza_Bugs_and_Fun_March_3,_2012#Organization.2C_logistics_and_communications Organization, logistics and communications section] for detail on how to get involved in working on tasks.

==Requirements==
* All code must be made available under the [http://www.gnu.org/licenses/gpl-2.0.html General Public Licence version 2].
* All documentation contributions must be made available under the [[JEDL|Joomla! Electronic Documentation License]]. Further information on the JEDL is available in the [[JEDL/FAQ|JEDL Frequently Asked Questions]]
* No advertising or self-promotion will be allowed. This includes back links to your website or anyone else's. The one exception is that if you have made a contribution then feel free to add your name and an optional link to your website to the [[Pizza Bugs and Fun 2011/Contributors List|Contributors List]]
* All contributions must be in English. Note that the official language of the Joomla! project is British English.

== FAQ ==
Q: Where is the SVN for Joomla?

A: http://joomlacode.org/svn/joomla/development/trunk

Q: Which one is 2.5?

A: It is the main trunk

Q: Any known issues with JForge and Chrome on Windows?

A: It have been seen that browsing the JForge tracker, Chrome may ask for a missing plugin (windows media player). No workaround for this is yet known.

==Contributors==
{{:Pizza Bugs and Fun March 3, 2012/Contributors List}}

Pizza Bugs and Fun March 3, 2012

2012-02-10T06:34:57Z

HobbesPDX: adding Portland!!

[[Category:Bug Squad]]
[[Category:Development]]
[[Image:pbf.png|right]]
{{RightTOC}}

We are announcing a Joomla! Pizza, Bugs and Fun event scheduled for Saturday, March 3, 2012. The event is global for virtual participants with local venues where ever they are organized. We squashed a lot of bugs last month, but as more people use a new release, we always find more. We'll also have documentation ready to be worked on.

'''See the section [http://docs.joomla.org/Pizza_Bugs_and_Fun_March_3,_2012#General_Instructions General Instructions] below for instructions.'''

This wiki will be used as the central resource for coordinating efforts and accumulating results from this event.

The '''twitter''' hash tag is #jpbf12.

== Goals ==

* '''Bugs''' : We will be working through the [http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemBrowse&tracker_id=8103 CMS Issue Tracker] where there are bug reports needing patches and/or testing.

* '''Documentation''' : We still have documentation that needs to be done. If you want to help out writing documentation, you're also more than welcome.

== Organization, logistics and communications ==

=== Communication ===
We have set up a Skype chat for all attendees of the PBF. Skype is invitation only and you are all invited. This is the same chat we used for the PBF in December. To get an invitation, email your Skype name to Andy Tarr (andrea.tarr@joomla.org). To make sure you can get in, get your invitation and log in before the day of the PBF. This Skype chat will be in English, but other languages can set up their own chat groups as well.

=== General Instructions ===

These instructions may change as we get closer to the event.

==== If you want to code bug fixes ====
* Look for issues with a status of Confirmed
* Before you start coding, find the issue in the [https://docs.google.com/spreadsheet/ccc?key=0AuHNF8-wsi3tdGtOU0lqSThaLXB4NDJCUTBMNkxzcXc#gid=0 CMS Issues Google doc] and put your name on the issue so people know someone is working on it. You can sign things out to a group if a group is working on any issue. Remember that everyone is seeing the same document, so please don't hide rows.
* Use the [http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemBrowse&tracker_id=8103 CMS Issue Tracker] as usual, which means you download the patch from the tracker and apply it to a current SVN copy of Joomla.
* When you have a patch, add it to the tracker and change the status to Pending if you are able to.
* Go back into the Google doc and change the status there to Pending as well and remove your name and add a comment with your name that you added a patch. If the tracker still needs to be changed to pending, you can mention it there.
Helpful documentation:
* [[Setting up your workstation for Joomla! development]]. A step-by-step guide to installing the Eclipse IDE on your local workstation for Joomla! development.
* [http://community.joomla.org/blogs/community/828-webinar-using-eclipse-for-joomla-development.html Using Eclipse for Joomla! Development] Video webinar demonstrating overview of Eclipse features for Joomla! development
* [[Tortoise SVN]]
* [[Secure coding guidelines]]
* [[Development Best Practices]]

==== If you want to test and you have or can set up SVN and XAMPP/MAMP ====
* Look for issues with a status of Pending. We want at least 2 testers and more on complex issues, so you can test what others have tested already.
* Use the [http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemBrowse&tracker_id=8103 CMS Issue Tracker] as usual, which means you download the patch from the tracker and apply it to a current SVN copy of Joomla.
* Most of the issues should have test instructions with them.
* Once you have tested, add comments to the tracker on your results. Start your comment with @test so you will get counted in the stats as a tester.
Helpful Documentation:
* [[Tortoise SVN]] Freestanding Windows based SVN. This may be all you need, if you have a Windows PC
* [http://www.adobe.com/devnet/dreamweaver/articles/using_subversion_pt1.html Dreamweaver CS5 with SVN] Start of tutorials on how to use SVN in Dreamweaver
* [[Setting up your workstation for Joomla! development]]. A step-by-step guide to installing the Eclipse IDE on your local workstation for Joomla! development. This also guides you through installing XAMPP/MAMP on your computer.
* [http://community.joomla.org/blogs/community/828-webinar-using-eclipse-for-joomla-development.html Using Eclipse for Joomla! Development] Video webinar demonstrating overview of Eclipse features for Joomla! development

==== If you want to work on Documentation ====
* To edit this Documentation Wiki, you will need a user account. If you don't already have one, you may register on [[Special:UserLogin]]. While a brand new user account won't give you all the permissions you'd get with a confirmed and "elevated" account, you will be able to edit most pages.
* Get your user account a few days before and make sure that you are able to sign in since the automatic authorization system can lock some people out.
* If you'd like something to be edited, but you're not sure what to write exactly, use talk pages to add comments to pages.
* During the PBF, several experienced Wiki editors will be available in the Skype chat to help you.
{{:Documentation wiki}}

===== Help Screens =====
* There are help screens that still need to be made for 2.5 [[Help17:Help screens]]

=== Pizza ===
We are offering pizza and soda for pre-registered groups. We aren’t setting a specific maximum, but please don’t go crazy with it. Get enough so there’s plenty for everyone, but not a week’s worth of pizza and soda leftovers for everyone. Contact Andrea Tarr (andrea.tarr@joomla.org) before the event to register and get details.

== Locations ==

If you want to get people together and have a venue to share, please add it below. Share as much as possible details like exact location, url for more information about the venue, ways to register, date and time the venue is available etc.

If you set up a location please send contact information to Andy Tarr (andrea.tarr@joomla.org). Feel free to contact her with any questions.

=== Europe ===

=== North America ===

[http://www.joomlanewengland.org Joomla User Group New England]
Marlboro College Graduate School
28 Vernon Street
Brattleboro, VT 05301
Contact: Andrea Tarr

[http://www.joomlapdx.com/ Portland Joomla! User Group]
Location: TBD
Contact: Ben Sandberg

=== South America ===

=== Asia/Pacific ===

=== Africa ===

=== Middle East ===

===Virtual===
====Skype Chat====
We have set up a Skype chat for all attendees of the PBF. Skype is invitation only. This is the same Skype chat we used in December. To get an invitation, email your Skype name to Andy Tarr (andrea.tarr@joomla.org). To make sure you can get in, get your invitation and log in before the day of the PBF.

If you don't already have Skype, you can download it for free from [http://skype.com Skype].

== Registration ==
=== For write access to this wiki ===
To get write access to this wiki you will need to [[Special:Userlogin|register here first]]. Please be aware that the registration process requires a valid email address. This is the same login for updating Joomla documentation.

=== At a physical location ===
If you wish to be present at one of the physical locations listed above then you must register in advance because space most likely is limited. Registrations are the responsibility of the individual location organizers and you should click on the appropriate link above for more information.

=== Taking bugs, tasks and pizza ===

Please check the [http://docs.joomla.org/Pizza_Bugs_and_Fun_March_3,_2012#Organization.2C_logistics_and_communications Organization, logistics and communications section] for detail on how to get involved in working on tasks.

==Requirements==
* All code must be made available under the [http://www.gnu.org/licenses/gpl-2.0.html General Public Licence version 2].
* All documentation contributions must be made available under the [[JEDL|Joomla! Electronic Documentation License]]. Further information on the JEDL is available in the [[JEDL/FAQ|JEDL Frequently Asked Questions]]
* No advertising or self-promotion will be allowed. This includes back links to your website or anyone else's. The one exception is that if you have made a contribution then feel free to add your name and an optional link to your website to the [[Pizza Bugs and Fun 2011/Contributors List|Contributors List]]
* All contributions must be in English. Note that the official language of the Joomla! project is British English.

== FAQ ==
Q: Where is the SVN for Joomla?

A: http://joomlacode.org/svn/joomla/development/trunk

Q: Which one is 2.5?

A: It is the main trunk

Q: Any known issues with JForge and Chrome on Windows?

A: It have been seen that browsing the JForge tracker, Chrome may ask for a missing plugin (windows media player). No workaround for this is yet known.

==Contributors==
{{:Pizza Bugs and Fun March 3, 2012/Contributors List}}

J2.5:Developing a MVC Component/Adding an update server

2011-12-08T19:39:29Z

HobbesPDX: /* Zips */

This tutorial is for {{JVer|1.6}} and {{JVer|1.7}} and {{JVer|2.5}}

== Articles in this series ==
{{Chunk:Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Contents}}

== Introduction ==
This tutorial is part of the [[Developing a Model-View-Controller (MVC) Component for Joomla!1.6]] tutorial. You are encouraged to read the previous parts of the tutorial before reading this.

== Adding a updateserver definition ==
To add a updateserver functionality adjust the helloworld.xml to look like this.

<span id="helloworld.xml">
''helloworld.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="1.6.0" method="upgrade">

<name>COM_HELLOWORLD</name>

<creationDate>November 2009</creationDate>
<author>John Doe</author>
<authorEmail>john.doe@example.org</authorEmail>
<authorUrl>http://www.example.org</authorUrl>
<copyright>Copyright Info</copyright>
<license>License Info</license>

<version>0.0.15</version>

<description>COM_HELLOWORLD_DESCRIPTION</description>


<scriptfile>script.php</scriptfile>

<install> 
<sql>
<file driver="mysql" charset="utf8">sql/install.mysql.utf8.sql</file>
</sql>
</install>
<uninstall> 
<sql>
<file driver="mysql" charset="utf8">sql/uninstall.mysql.utf8.sql</file>
</sql>
</uninstall>
<update> 
<schemas>
<schemapath type="mysql">sql/updates/mysql</schemapath>
</schemas>
</update>



<files folder="site">
<filename>index.html</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>
<folder>views</folder>
<folder>models</folder>
<folder>language</folder>
</files>

<media destination="com_helloworld" folder="media">
<filename>index.html</filename>
<folder>images</folder>
</media>

<administration>

<menu img="../media/com_helloworld/images/tux-16x16.png">COM_HELLOWORLD_MENU</menu>


<files folder="admin">

<filename>index.html</filename>
<filename>config.xml</filename>
<filename>access.xml</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>

<folder>sql</folder>

<folder>tables</folder>

<folder>models</folder>

<folder>views</folder>

<folder>controllers</folder>

<folder>helpers</folder>
</files>

<languages folder="admin">
<language tag="en-GB">language/en-GB/en-GB.com_helloworld.ini</language>
<language tag="en-GB">language/en-GB/en-GB.com_helloworld.sys.ini</language>
</languages>
</administration>


<updateservers>

<server type="extension" priority="1" name="HelloWorld Update Site">http://yourdomain.com/update/helloworld-update.xml</server>
</updateservers>

</extension>
</source>
</span>

You also need to put a XML-file on your server which contains all update-informations.

<span id="helloworld-update.xml">
''helloworld-update.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<updates>
<update>
<name>HelloWorld</name>
<description>HelloWorld Component</description>
<element>com_helloworld</element>
<type>component</type>
<version>1.5.0</version>

<infourl title="HalloWorld URL">http://yourdomain.com</infourl>
<downloads>
<downloadurl type="full" format="zip">http://yourdomain.com/files/com_helloworld-1.5.0-final.zip</downloadurl>
</downloads>
<tags>
<tag>some-tag</tag>
</tags>

<maintainer>HelloWorld Inc.</maintainer>
<maintainerurl>http://yourdomain.com</maintainerurl>
<section>some-section</section>
<targetplatform name="joomla" version="1.6" />
</update>
<update>
<name>HelloWorld</name>
<description>HelloWorld Component</description>
<element>com_helloworld</element>
<type>component</type>
<version>1.5.0</version>

<infourl title="HalloWorld URL">http://yourdomain.com</infourl>
<downloads>
<downloadurl type="full" format="zip">http://yourdomain.com/files/com_helloworld-1.5.0-final.zip</downloadurl>
</downloads>
<tags>
<tag>some-tag</tag>
</tags>

<maintainer>HelloWorld Inc.</maintainer>
<maintainerurl>http://yourdomain.com</maintainerurl>
<section>some-section</section>
<targetplatform name="joomla" version="1.7" />
</update>
<update>
<name>HelloWorld</name>
<description>HelloWorld Component</description>
<element>com_helloworld</element>
<type>component</type>
<version>1.5.0</version>

<infourl title="HalloWorld URL">http://yourdomain.com</infourl>
<downloads>
<downloadurl type="full" format="zip">http://yourdomain.com/files/com_helloworld-1.5.0-final.zip</downloadurl>
</downloads>
<tags>
<tag>some-tag</tag>
</tags>

<maintainer>HelloWorld Inc.</maintainer>
<maintainerurl>http://yourdomain.com</maintainerurl>
<section>some-section</section>
<targetplatform name="joomla" version="2.5" />
</update>

<update>
<name>HelloWorld</name>
<description>HelloWorld Component</description>
<element>com_helloworld</element>
<type>component</type>
<version>1.5.1</version>

<infourl title="HelloWorld URL">http://yourdomain.com</infourl>
<downloads>
<downloadurl type="full" format="zip">http://yourdomain.com/files/com_helloworld-1.5.1-final.zip</downloadurl>
</downloads>
<tags>
<tag>some-tag</tag>
</tags>

<maintainer>HelloWorld Inc.</maintainer>
<maintainerurl>http://yourdomain.com</maintainerurl>
<section>some-section</section>
<targetplatform name="joomla" version="1.6" />
</update>
<update>
<name>HelloWorld</name>
<description>HelloWorld Component</description>
<element>com_helloworld</element>
<type>component</type>
<version>1.5.1</version>

<infourl title="HelloWorld URL">http://yourdomain.com</infourl>
<downloads>
<downloadurl type="full" format="zip">http://yourdomain.com/files/com_helloworld-1.5.1-final.zip</downloadurl>
</downloads>
<tags>
<tag>some-tag</tag>
</tags>

<maintainer>HelloWorld Inc.</maintainer>
<maintainerurl>http://yourdomain.com</maintainerurl>
<section>some-section</section>
<targetplatform name="joomla" version="1.7" />
</update>
<update>
<name>HelloWorld</name>
<description>HelloWorld Component</description>
<element>com_helloworld</element>
<type>component</type>
<version>1.5.1</version>

<infourl title="HelloWorld URL">http://yourdomain.com</infourl>
<downloads>
<downloadurl type="full" format="zip">http://yourdomain.com/files/com_helloworld-1.5.1-final.zip</downloadurl>
</downloads>
<tags>
<tag>some-tag</tag>
</tags>

<maintainer>HelloWorld Inc.</maintainer>
<maintainerurl>http://yourdomain.com</maintainerurl>
<section>some-section</section>
<targetplatform name="joomla" version="2.5" />
</update>

</updates>

</source>
</span>

You need to add a new update-node every time you publish a new release, as well as for each Joomla! version. (you will need a distinct update node for each targetplatform)

== Zips ==
Download the zip file for this Part:
[http://www.leyar.com/joomlaorg/part17.zip] (NOTE: This package is designed for Joomla! 1.6 only.)

== See Also ==
*[[Deploying an Update Server]]

== Contributors ==
*[[User:Cdemko|Christophe Demko]]
*[[User:oaksu|Ozgur Aksu]]
*[[User:HobbesPDX|Ben Sandberg]]

J2.5:Developing a MVC Component/Adding an update server

2011-12-08T19:38:11Z

HobbesPDX: adding 2.5!

This tutorial is for {{JVer|1.6}} and {{JVer|1.7}} and {{JVer|2.5}}

== Articles in this series ==
{{Chunk:Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Contents}}

== Introduction ==
This tutorial is part of the [[Developing a Model-View-Controller (MVC) Component for Joomla!1.6]] tutorial. You are encouraged to read the previous parts of the tutorial before reading this.

== Adding a updateserver definition ==
To add a updateserver functionality adjust the helloworld.xml to look like this.

<span id="helloworld.xml">
''helloworld.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="1.6.0" method="upgrade">

<name>COM_HELLOWORLD</name>

<creationDate>November 2009</creationDate>
<author>John Doe</author>
<authorEmail>john.doe@example.org</authorEmail>
<authorUrl>http://www.example.org</authorUrl>
<copyright>Copyright Info</copyright>
<license>License Info</license>

<version>0.0.15</version>

<description>COM_HELLOWORLD_DESCRIPTION</description>


<scriptfile>script.php</scriptfile>

<install> 
<sql>
<file driver="mysql" charset="utf8">sql/install.mysql.utf8.sql</file>
</sql>
</install>
<uninstall> 
<sql>
<file driver="mysql" charset="utf8">sql/uninstall.mysql.utf8.sql</file>
</sql>
</uninstall>
<update> 
<schemas>
<schemapath type="mysql">sql/updates/mysql</schemapath>
</schemas>
</update>



<files folder="site">
<filename>index.html</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>
<folder>views</folder>
<folder>models</folder>
<folder>language</folder>
</files>

<media destination="com_helloworld" folder="media">
<filename>index.html</filename>
<folder>images</folder>
</media>

<administration>

<menu img="../media/com_helloworld/images/tux-16x16.png">COM_HELLOWORLD_MENU</menu>


<files folder="admin">

<filename>index.html</filename>
<filename>config.xml</filename>
<filename>access.xml</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>

<folder>sql</folder>

<folder>tables</folder>

<folder>models</folder>

<folder>views</folder>

<folder>controllers</folder>

<folder>helpers</folder>
</files>

<languages folder="admin">
<language tag="en-GB">language/en-GB/en-GB.com_helloworld.ini</language>
<language tag="en-GB">language/en-GB/en-GB.com_helloworld.sys.ini</language>
</languages>
</administration>


<updateservers>

<server type="extension" priority="1" name="HelloWorld Update Site">http://yourdomain.com/update/helloworld-update.xml</server>
</updateservers>

</extension>
</source>
</span>

You also need to put a XML-file on your server which contains all update-informations.

<span id="helloworld-update.xml">
''helloworld-update.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<updates>
<update>
<name>HelloWorld</name>
<description>HelloWorld Component</description>
<element>com_helloworld</element>
<type>component</type>
<version>1.5.0</version>

<infourl title="HalloWorld URL">http://yourdomain.com</infourl>
<downloads>
<downloadurl type="full" format="zip">http://yourdomain.com/files/com_helloworld-1.5.0-final.zip</downloadurl>
</downloads>
<tags>
<tag>some-tag</tag>
</tags>

<maintainer>HelloWorld Inc.</maintainer>
<maintainerurl>http://yourdomain.com</maintainerurl>
<section>some-section</section>
<targetplatform name="joomla" version="1.6" />
</update>
<update>
<name>HelloWorld</name>
<description>HelloWorld Component</description>
<element>com_helloworld</element>
<type>component</type>
<version>1.5.0</version>

<infourl title="HalloWorld URL">http://yourdomain.com</infourl>
<downloads>
<downloadurl type="full" format="zip">http://yourdomain.com/files/com_helloworld-1.5.0-final.zip</downloadurl>
</downloads>
<tags>
<tag>some-tag</tag>
</tags>

<maintainer>HelloWorld Inc.</maintainer>
<maintainerurl>http://yourdomain.com</maintainerurl>
<section>some-section</section>
<targetplatform name="joomla" version="1.7" />
</update>
<update>
<name>HelloWorld</name>
<description>HelloWorld Component</description>
<element>com_helloworld</element>
<type>component</type>
<version>1.5.0</version>

<infourl title="HalloWorld URL">http://yourdomain.com</infourl>
<downloads>
<downloadurl type="full" format="zip">http://yourdomain.com/files/com_helloworld-1.5.0-final.zip</downloadurl>
</downloads>
<tags>
<tag>some-tag</tag>
</tags>

<maintainer>HelloWorld Inc.</maintainer>
<maintainerurl>http://yourdomain.com</maintainerurl>
<section>some-section</section>
<targetplatform name="joomla" version="2.5" />
</update>

<update>
<name>HelloWorld</name>
<description>HelloWorld Component</description>
<element>com_helloworld</element>
<type>component</type>
<version>1.5.1</version>

<infourl title="HelloWorld URL">http://yourdomain.com</infourl>
<downloads>
<downloadurl type="full" format="zip">http://yourdomain.com/files/com_helloworld-1.5.1-final.zip</downloadurl>
</downloads>
<tags>
<tag>some-tag</tag>
</tags>

<maintainer>HelloWorld Inc.</maintainer>
<maintainerurl>http://yourdomain.com</maintainerurl>
<section>some-section</section>
<targetplatform name="joomla" version="1.6" />
</update>
<update>
<name>HelloWorld</name>
<description>HelloWorld Component</description>
<element>com_helloworld</element>
<type>component</type>
<version>1.5.1</version>

<infourl title="HelloWorld URL">http://yourdomain.com</infourl>
<downloads>
<downloadurl type="full" format="zip">http://yourdomain.com/files/com_helloworld-1.5.1-final.zip</downloadurl>
</downloads>
<tags>
<tag>some-tag</tag>
</tags>

<maintainer>HelloWorld Inc.</maintainer>
<maintainerurl>http://yourdomain.com</maintainerurl>
<section>some-section</section>
<targetplatform name="joomla" version="1.7" />
</update>
<update>
<name>HelloWorld</name>
<description>HelloWorld Component</description>
<element>com_helloworld</element>
<type>component</type>
<version>1.5.1</version>

<infourl title="HelloWorld URL">http://yourdomain.com</infourl>
<downloads>
<downloadurl type="full" format="zip">http://yourdomain.com/files/com_helloworld-1.5.1-final.zip</downloadurl>
</downloads>
<tags>
<tag>some-tag</tag>
</tags>

<maintainer>HelloWorld Inc.</maintainer>
<maintainerurl>http://yourdomain.com</maintainerurl>
<section>some-section</section>
<targetplatform name="joomla" version="2.5" />
</update>

</updates>

</source>
</span>

You need to add a new update-node every time you publish a new release, as well as for each Joomla! version. (you will need a distinct update node for each targetplatform)

== Zips ==
Download the zip file for this Part:
[http://www.leyar.com/joomlaorg/part17.zip] (NOTE: The package has not been updated with the above Joomla! 1.7 compatibility)

== See Also ==
*[[Deploying an Update Server]]

== Contributors ==
*[[User:Cdemko|Christophe Demko]]
*[[User:oaksu|Ozgur Aksu]]
*[[User:HobbesPDX|Ben Sandberg]]

J2.5:Developing a MVC Component/Adding an update server

2011-10-02T19:30:41Z

HobbesPDX: Removed errant comment.

This tutorial is for {{JVer|1.6}} and {{JVer|1.7}}

== Articles in this series ==
{{Chunk:Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Contents}}

== Introduction ==
This tutorial is part of the [[Developing a Model-View-Controller (MVC) Component for Joomla!1.6]] tutorial. You are encouraged to read the previous parts of the tutorial before reading this.

== Adding a updateserver definition ==
To add a updateserver functionality adjust the helloworld.xml to look like this.

<span id="helloworld.xml">
''helloworld.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="1.6.0" method="upgrade">

<name>COM_HELLOWORLD</name>

<creationDate>November 2009</creationDate>
<author>John Doe</author>
<authorEmail>john.doe@example.org</authorEmail>
<authorUrl>http://www.example.org</authorUrl>
<copyright>Copyright Info</copyright>
<license>License Info</license>

<version>0.0.15</version>

<description>COM_HELLOWORLD_DESCRIPTION</description>


<scriptfile>script.php</scriptfile>

<install> 
<sql>
<file driver="mysql" charset="utf8">sql/install.mysql.utf8.sql</file>
</sql>
</install>
<uninstall> 
<sql>
<file driver="mysql" charset="utf8">sql/uninstall.mysql.utf8.sql</file>
</sql>
</uninstall>
<update> 
<schemas>
<schemapath type="mysql">sql/updates/mysql</schemapath>
</schemas>
</update>



<files folder="site">
<filename>index.html</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>
<folder>views</folder>
<folder>models</folder>
<folder>language</folder>
</files>

<media destination="com_helloworld" folder="media">
<filename>index.html</filename>
<folder>images</folder>
</media>

<administration>

<menu img="../media/com_helloworld/images/tux-16x16.png">COM_HELLOWORLD_MENU</menu>


<files folder="admin">

<filename>index.html</filename>
<filename>config.xml</filename>
<filename>access.xml</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>

<folder>sql</folder>

<folder>tables</folder>

<folder>models</folder>

<folder>views</folder>

<folder>controllers</folder>

<folder>helpers</folder>
</files>

<languages folder="admin">
<language tag="en-GB">language/en-GB/en-GB.com_helloworld.ini</language>
<language tag="en-GB">language/en-GB/en-GB.com_helloworld.sys.ini</language>
</languages>
</administration>


<updateservers>

<server type="extension" priority="1" name="HelloWorld Update Site">http://yourdomain.com/update/helloworld-update.xml</server>
</updateservers>

</extension>
</source>
</span>

You also need to put a XML-file on your server which contains all update-informations.

<span id="helloworld-update.xml">
''helloworld-update.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<updates>
<update>
<name>HelloWorld</name>
<description>HelloWorld Component</description>
<element>com_helloworld</element>
<type>component</type>
<version>1.5.0</version>

<infourl title="HalloWorld URL">http://yourdomain.com</infourl>
<downloads>
<downloadurl type="full" format="zip">http://yourdomain.com/files/com_helloworld-1.5.0-final.zip</downloadurl>
</downloads>
<tags>
<tag>some-tag</tag>
</tags>

<maintainer>HelloWorld Inc.</maintainer>
<maintainerurl>http://yourdomain.com</maintainerurl>
<section>some-section</section>
<targetplatform name="joomla" version="1.6" />
</update>
<update>
<name>HelloWorld</name>
<description>HelloWorld Component</description>
<element>com_helloworld</element>
<type>component</type>
<version>1.5.0</version>

<infourl title="HalloWorld URL">http://yourdomain.com</infourl>
<downloads>
<downloadurl type="full" format="zip">http://yourdomain.com/files/com_helloworld-1.5.0-final.zip</downloadurl>
</downloads>
<tags>
<tag>some-tag</tag>
</tags>

<maintainer>HelloWorld Inc.</maintainer>
<maintainerurl>http://yourdomain.com</maintainerurl>
<section>some-section</section>
<targetplatform name="joomla" version="1.7" />
</update>

<update>
<name>HelloWorld</name>
<description>HelloWorld Component</description>
<element>com_helloworld</element>
<type>component</type>
<version>1.5.1</version>

<infourl title="HalloWorld URL">http://yourdomain.com</infourl>
<downloads>
<downloadurl type="full" format="zip">http://yourdomain.com/files/com_helloworld-1.5.1-final.zip</downloadurl>
</downloads>
<tags>
<tag>some-tag</tag>
</tags>

<maintainer>HelloWorld Inc.</maintainer>
<maintainerurl>http://yourdomain.com</maintainerurl>
<section>some-section</section>
<targetplatform name="joomla" version="1.6" />
</update>
<update>
<name>HelloWorld</name>
<description>HelloWorld Component</description>
<element>com_helloworld</element>
<type>component</type>
<version>1.5.1</version>

<infourl title="HalloWorld URL">http://yourdomain.com</infourl>
<downloads>
<downloadurl type="full" format="zip">http://yourdomain.com/files/com_helloworld-1.5.1-final.zip</downloadurl>
</downloads>
<tags>
<tag>some-tag</tag>
</tags>

<maintainer>HelloWorld Inc.</maintainer>
<maintainerurl>http://yourdomain.com</maintainerurl>
<section>some-section</section>
<targetplatform name="joomla" version="1.7" />
</update>

</updates>

</source>
</span>

You need to add a new update-node every time you publish a new release, as well as for each Joomla! version. (you will need a distinct update node for each targetplatform)

== Zips ==
Download the zip file for this Part:
[http://www.leyar.com/joomlaorg/part17.zip] (NOTE: The package has not been updated with the above Joomla! 1.7 compatibility)

== See Also ==
*[[Deploying an Update Server]]

== Contributors ==
*[[User:Cdemko|Christophe Demko]]
*[[User:oaksu|Ozgur Aksu]]
*[[User:HobbesPDX|Ben Sandberg]]

J2.5:Developing a MVC Component/Adding an update server

2011-10-02T19:29:34Z

HobbesPDX: added myself to the list of contributors. ;-)

User:HobbesPDX

2011-10-02T19:27:00Z

HobbesPDX:

Hi. I'm Ben, a Joomla! Evangelist.

[http://www.pdxfixit.com/ PDXfixIT]

User:HobbesPDX

2011-10-02T19:26:20Z

HobbesPDX: Created page with "Hi. I'm Ben, a Joomla! Evangelist. [http://www.pdxfixit.com/]"

Hi. I'm Ben, a Joomla! Evangelist.

[http://www.pdxfixit.com/]

J2.5:Developing a MVC Component/Adding an update server

2011-10-02T19:25:16Z

HobbesPDX: fixed package type, added note to Zips section, to let user know not to expect the visible code.

J2.5:Developing a MVC Component/Adding an update server

2011-10-02T19:23:11Z

HobbesPDX: updated to include 1.7 icon, added update nodes for each Joomla! version, and added See Also section with a link

This tutorial is for {{JVer|1.6}} and {{JVer|1.7}}

== Articles in this series ==
{{Chunk:Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Contents}}

== Introduction ==
This tutorial is part of the [[Developing a Model-View-Controller (MVC) Component for Joomla!1.6]] tutorial. You are encouraged to read the previous parts of the tutorial before reading this.

== Adding a updateserver definition ==
To add a updateserver functionality adjust the helloworld.xml to look like this.

<span id="helloworld.xml">
''helloworld.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="1.6.0" method="upgrade">

<name>COM_HELLOWORLD</name>

<creationDate>November 2009</creationDate>
<author>John Doe</author>
<authorEmail>john.doe@example.org</authorEmail>
<authorUrl>http://www.example.org</authorUrl>
<copyright>Copyright Info</copyright>
<license>License Info</license>

<version>0.0.15</version>

<description>COM_HELLOWORLD_DESCRIPTION</description>


<scriptfile>script.php</scriptfile>

<install> 
<sql>
<file driver="mysql" charset="utf8">sql/install.mysql.utf8.sql</file>
</sql>
</install>
<uninstall> 
<sql>
<file driver="mysql" charset="utf8">sql/uninstall.mysql.utf8.sql</file>
</sql>
</uninstall>
<update> 
<schemas>
<schemapath type="mysql">sql/updates/mysql</schemapath>
</schemas>
</update>



<files folder="site">
<filename>index.html</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>
<folder>views</folder>
<folder>models</folder>
<folder>language</folder>
</files>

<media destination="com_helloworld" folder="media">
<filename>index.html</filename>
<folder>images</folder>
</media>

<administration>

<menu img="../media/com_helloworld/images/tux-16x16.png">COM_HELLOWORLD_MENU</menu>


<files folder="admin">

<filename>index.html</filename>
<filename>config.xml</filename>
<filename>access.xml</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>

<folder>sql</folder>

<folder>tables</folder>

<folder>models</folder>

<folder>views</folder>

<folder>controllers</folder>

<folder>helpers</folder>
</files>

<languages folder="admin">
<language tag="en-GB">language/en-GB/en-GB.com_helloworld.ini</language>
<language tag="en-GB">language/en-GB/en-GB.com_helloworld.sys.ini</language>
</languages>
</administration>


<updateservers>

<server type="extension" priority="1" name="HelloWorld Update Site">http://yourdomain.com/update/helloworld-update.xml</server>
</updateservers>

</extension>
</source>
</span>

You also need to put a XML-file on your server which contains all update-informations.

<span id="helloworld-update.xml">
''helloworld-update.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<updates>
<update>
<name>HelloWorld</name>
<description>HelloWorld Component</description>
<element>com_helloworld</element>
<type>component</type>
<version>1.5.0</version>

<infourl title="HalloWorld URL">http://yourdomain.com</infourl>
<downloads>
<downloadurl type="full" format="tgz">http://yourdomain.com/files/com_helloworld-1.5.0-final.zip</downloadurl>
</downloads>
<tags>
<tag>some-tag</tag>
</tags>

<maintainer>HelloWorld Inc.</maintainer>
<maintainerurl>http://yourdomain.com</maintainerurl>
<section>some-section</section>
<targetplatform name="joomla" version="1.6" />
</update>
<update>
<name>HelloWorld</name>
<description>HelloWorld Component</description>
<element>com_helloworld</element>
<type>component</type>
<version>1.5.0</version>

<infourl title="HalloWorld URL">http://yourdomain.com</infourl>
<downloads>
<downloadurl type="full" format="tgz">http://yourdomain.com/files/com_helloworld-1.5.0-final.zip</downloadurl>
</downloads>
<tags>
<tag>some-tag</tag>
</tags>

<maintainer>HelloWorld Inc.</maintainer>
<maintainerurl>http://yourdomain.com</maintainerurl>
<section>some-section</section>
<targetplatform name="joomla" version="1.7" />
</update>

<update>
<name>HelloWorld</name>
<description>HelloWorld Component</description>
<element>com_helloworld</element>
<type>component</type>
<version>1.5.1</version>

<infourl title="HalloWorld URL">http://yourdomain.com</infourl>
<downloads>
<downloadurl type="full" format="tgz">http://yourdomain.com/files/com_helloworld-1.5.1-final.zip</downloadurl>
</downloads>
<tags>
<tag>some-tag</tag>
</tags>

<maintainer>HelloWorld Inc.</maintainer>
<maintainerurl>http://yourdomain.com</maintainerurl>
<section>some-section</section>
<targetplatform name="joomla" version="1.6" />
</update>
<update>
<name>HelloWorld</name>
<description>HelloWorld Component</description>
<element>com_helloworld</element>
<type>component</type>
<version>1.5.1</version>

<infourl title="HalloWorld URL">http://yourdomain.com</infourl>
<downloads>
<downloadurl type="full" format="tgz">http://yourdomain.com/files/com_helloworld-1.5.1-final.zip</downloadurl>
</downloads>
<tags>
<tag>some-tag</tag>
</tags>

<maintainer>HelloWorld Inc.</maintainer>
<maintainerurl>http://yourdomain.com</maintainerurl>
<section>some-section</section>
<targetplatform name="joomla" version="1.7" />
</update>

</updates>

</source>
</span>

You need to add a new update-node every time you publish a new release, as well as for each Joomla! version. (you will need a distinct update node for each targetplatform)

== Zips ==
Download the zip file for this Part:
[http://www.leyar.com/joomlaorg/part17.zip]

== See Also ==
*[[Deploying an Update Server]]

== Contributors ==
*[[User:Cdemko|Christophe Demko]]
*[[User:oaksu|Ozgur Aksu]]
On Installation of that component, the "Error Building Admin Menus" warning message is getting appear...

Deploying an Update Server

2011-10-02T19:17:02Z

HobbesPDX: CDATA clarification for descriptions.

{{RightTOC}}

This tutorial is for {{JVer|1.6}} and {{JVer|1.7}}

= Introduction =
This tutorial is designed to teach developers how to create an update server for integration with the update system introduced in Joomla! 1.6. By adding an update server listing to your extension's manifest, developers enable users to update their extensions via the [[Help16:Extensions Extension Manager Update|Extension Manager's Update]] view with only a few clicks.

= Defining an update server =
In order to use this feature, an update server must be defined in your extension's manifest. This definition can be used in all Joomla! 1.6 and 1.7 compatible extensions but is not available for templates. You can use two options for your server type; collection or extension. These will be explained in detail shortly. The update server is defined as follows for each type:

<code>
<updateservers>
<server type="collection">http://example.com/list.xml</server>
<server type="extension" priority="2" name="My Extension's Updates">http://example.com/extension.xml</server>
</updateservers>
</code>

Multiple servers can be defined within the <updateservers> tag.

= Server types =
== Collection ==
The collection server type allows developers to define an extension's manifest to pull updates from a collection. This type of server can be used if the developer wants to define all of their extension's updates in a single file (not recommended) or if their extension has multiple sub-extensions which are not distributed or updated at the same time (such as a package extension type). The below example is the collection definition used by the updater when processing core Joomla! updates:

<code>
<extensionset name="Joomla Core" description="Joomla! Core">
<extension name="Joomla" element="joomla" type="file" version="1.7.0" detailsurl="http://update.joomla.org/core/extension.xml"/>
</extensionset>
</code>

All definitions must be defined between <extensionset> tags in your collection manifest. The <extensionset> tag has two optional parameters; name and description. For each extension that this collection references, a separate <extension> tag is required. The <extension> tag has the following parameters, all of which are required for updates to properly process:

* '''name''' - The name of the extension
* '''element''' - The untranslated extension name i.e. mod_custom
* '''type''' - The extension type (component, module, plugin, etc.)
* '''version''' - The latest version of the extension
* '''detailsurl''' - The URL of the XML file which contains that extension's individual update definitions

== Extension ==
The extension server type allows developers to define an extension's manifest to pull updates from a single extension's manifest. All collection manifests eventually point to this XML file. All updates in this file must be defined after an <updates> tag at the beginning of the file. The below example is the update definition for the Joomla! 1.7.0 release:

<code>
<update>
<name>Joomla! 1.7</name>
<description>Joomla! 1.7 CMS</description>
<element>joomla</element>
<type>file</type>
<version>1.7.0</version>
<infourl title="Joomla!">http://www.joomla.org/</infourl>
<downloads>
<downloadurl type="full" format="zip">http://joomlacode.org/gf/download/frsrelease/15279/66552/Joomla_1.6.5_to_1.7.0_Package.zip</downloadurl>
</downloads>
<tags>
<tag>stable</tag>
</tags>
<maintainer>Sam Moffatt</maintainer>
<maintainerurl>http://sammoffatt.com.au</maintainerurl>
<section>Testing</section>
<targetplatform name="joomla" version="1.6"/>
</update>
</code>

The following section describes the elements of a single update entity.

* '''name''' - The name of the extension, this name will appear in the Name column of the Extension Manager's Update view (required)
* '''description''' - A short description of the extension (optional) -- if you choose to use <![CDATA[]]>, double-quotes will break the HTML formatting. Use single quotes with your HTML entities.
* '''element''' - The installed name of the extension (required)
* '''type''' - The type of extension (component, module, plugin, etc.) (required)
* '''folder''' - Specific to plugins, this tag describes the type of plugin being updated (content, system, etc.) (required for plugins)
* '''client_id''' - The client_id of the extension; 0 for site and 1 for administrator (optional)
* '''version''' - The version of the release (required)
* '''infourl''' - A URL to point users to containing information about the update (optional)
* '''downloads''' - The section which lists all download locations
** '''downloadurl''' - The URL to download the extension from; the <downloadurl> tag has two required parameters:
*** '''type''' - The type of package (full or upgrade)
*** '''format''' - The format of the package (zip, tar, etc.)
* '''tags''' - Optional (unknown use)
* '''maintainer''' - The name of the extension maintainer (similar to the <author> tag in a manifest) (optional)
* '''maintainerurl''' - The website of the extension maintainer (similar to the <authorUrl> tag in a manifest) (optional)
* '''section''' - Optional (unknown use)
* '''targetplatform''' - A tag to define platform requirements, requires the following elements
** '''name''' - The name of the platform dependency; as of this writing, it should ONLY be "joomla"
** '''version''' - The version of Joomla! the extension supports
*** '''Note:''' If your extension is both Joomla! 1.6 and 1.7 compatible, you will be required to have two <update> definitions; one with the targetplaform being 1.6 and the other being 1.7 due to the manner in which the updater checks the version

A separate <update> definition will be required for each version of your extension you release.

= Supporting Tools =
Maintaining your update server files can be difficult depending on the manner in which you set up your files. An extension which can help you to maintain this is the Akeeba Release System, available free of charge from https://www.akeebabackup.com

= Contributors =
*[[User:mbabker|Michael Babker]]

J1.5 talk:Developing a MVC Component/Creating an Administrator Interface

2010-03-06T23:22:57Z

HobbesPDX: whoops.

== Renaming Part 4 ==
I checked out the comment below. ;-) Certainly, the multitude of hello(s) is confusing. What I did is to rename most everything.

Whenever there's something like HelloWhateverHello, the first Hello represents the component front-end, and the second represents the view/model. By the way, each view has its own model, which I think is pretty much standard MVC architecture. On the other hand, one controller can control several views, although this example doesn't do so.

Conversely, if you see HellosWhateverHello or HellosWhateverHellos, the first Hellos represents the adminstrative back-end, and the Hello or Hellos at the end refers to the view for editing one greeting or for listing all greetings, respectively. (Replace *Whatever* with Model, View, or Controller as appropriate.)

So, I renamed all this to look like FrontWhateverContent, AdminWhateverEdit, AdminWhateverList, and so on. Then I had to rename directories and files as well, so that models/hello.php became models/content.php in the front-end and models/edit.php in the back-end. Likewise, views/hello/ becomes views/content/ in the front-end and views/edit in the back-end. Also, in the back-end only, models/hellos.php & views/hellos/ become models/list.php & views/list. Lastly, I changed controllers/hello.php to controllers/edit.php, to reflect the change from HellosControllerHello to AdminControllerEdit.

Hope this clears things up a bit. It's a tedious refactoring exercise to do all this renaming, but it *is* doable. Good luck.

== "Hello" Overloaded ==

I'm not sure if anybody checks this, but I'm having a difficult time making my own component out of this document.

The first three chapters of this documentation are great. They are simple and to the point. The fourth, this page, is very confusing.

First off, the word "hello" is way over loaded. In the Creating an Admin Interface there are two models and two views:
Hello and Hellos

It's impossible to know why we need two different models. Why cant we use one model and two views?
Its totally impossible to understand which one gets called when.

I have discovered there are a lot of name conventions used here, but after reading this document over and over, it's still very difficult to know what the conventions are. This is probably stemming from "hello" being way too overloaded.

The method "get()" in JView is called in both views. It is supposed to automatically know which model to use, and which method to call. However, I don't think I followed the naming convention correctly, as it simply is not working (I get empty data with no error).

I think I could untangle the naming conventions myself, but with "hello" so overloaded in this example, I am having no luck guessing.

== Great up to chapter 3 ==

The documentation was great upto chapter 3. Got confused in 4th chapter.

Also, this doesn't cover how to create sub menus for a component [http://www.vojtechovsky.net/joomla/component/tutorial-joomla-1.5-free-component.png See example]

== Suggestions for improvement ==

*This is a really long and tedious tutorial with a lot of very useful information in it. I think it would help to break it down into parts or creating separate tutorials covering this material.
[[Link title]]

== REALLY GOOD DOCUMENTATION ==

Apart from a small error in part 4 which I have now corrected

did read:

$row =& $this->items[$i];
$checked = JHTML::_( 'grid.id', $i, $row->id );
$link = JRoute::_( 'index.php?option=com_hello>controller=hello>task=edit>cid[]='. $row->id );

now reads:

$row =& $this->items[$i];
$checked = JHTML::_( 'grid.id', $i, $row->id );
$link = JRoute::_( 'index.php?option=com_hello&controller=hello&task=edit&cid[]='. $row->id );

[[User:Jamesconroyuk|James Conroy]] 16:29, 16 February 2009 (UTC)

== Excellent documentation, but could use a slight extension ==

Have been able to create components using this set of tutorials, but am missing how to use non-string based data in the administrator interface.

The admin form only has one field (a string) and it might be useful to have either examples of, or a link to some other examples of how to view / capture other types of data such as :

Checkboxes (boolean)
Dropdown menus / radio button (int or string)

While it is easy to add the HTML form components (and even populate them with the values from the model), it isn't immediately clear how to recapture the data of these alternative types.

There is another tutorial I have seen on this wiki that has the "build in a rich editor" function, could use a link from this page.

[[User:craigmoore|Craig Moore]] 13:06, 09 May 2009 (UTC)

== Really a great tutorial ... but too many hello.php's ==

First of all, great tutorial, a very good effort to explain the basics.

Maybe just my problem:
I personally prefer to edit several files at a time, what means, i have 10-20 tabs open in my editor (UltraEdit).
In my case that means, that my editor tab-bar looks like:

hello.php - controller.php - hello.php - hello.php - hello.php - controller.php - hellos.php - and so on ...

I would kiss the shoes of everyone who would:

1.) precisely explain naming conventions for files of components (which file may, which file must be called hello.php)

2.) resolve the hello.php-maze in this tutorial with more speaking filenames

Thanks to the authors, best regards and a hello to everyone

Jochen

== Good Tutorial ==

Suggestion for improvement.

I also found Part 4 hard to follow and lacking explanation of why various names/paths/parameters were chosen. For a beginner trying to understand Joomla! MVC conventions I found another component backend howto that gave more of the details I was looking for: [http://www.scribd.com/doc/11515210/Joomla-Component-Development-Backend]

Hope this helps someone else.
-Mike
[[User:M3t00|M3t00]] 15:55, 10 June 2009 (UTC)

== RE: Renaming Part 4 ==

I'm actually even more confused now.

Only by reading through this discussion did it occur to me that you need to use multiple views to handle the various tasks in the controller. That seems like an important concept that is not entirely obvious to someone trying to learn the joomla framework. And yet now that I recognize the concept, it's not obvious what the best practices would be to implement multiple views. I'll work on it.

Despite that, this is still an extremely valuable tutorial -- especially considering that much of the rest of the API documentation is sparse at best. The entire joomla documentation in general could definitely benefit from a bit of a re-org.

EDIT: OK. So after reading through part 4 of the tutorial again, it is clear to me about the multiple views. So, looking back, it would have been valuable to explain that in the introduction. Something like:

"Now we will create an administrator section to create the greetings. It uses 2 views. The first view, called Hellos, will present a list of greetings with the ability to add new ones or remove old ones. The second view will allow the user to edit each greeting."

That would have helped tremendously. In any case, I got it now. I feel a little stupid for missing that the first time around, but maybe it was because it was late at night.

== Component Hello, Site Hello, Admin Hellos, Admin Hello ==

Chapters 1 and 2 were easy to follow. Chapter 3 contains some glitches that took me some time to understand but reading this chapter made everything really confusing. It took me a time to realise the Hello's, just my subject with only the focus clarifies already some impact. After re- and re-re reading it becomes clear to me what is meant. After re-reading the reason for using Hellos (as an Admin List) became clear and re-re- reading made the Admin single view/tmpl Hello obvious again. Why not rename these to:

* Manage_Hello_List
* Manage_Hello_Item

This would make everything much more readable, would set a clear context and increase the ease of understanding.<br>
--[[User:M.A.S.H|M.A.S.H]] 12:37, 3 August 2009 (UTC)

== Splitting up article into two articles ==

If the writers have no objection I propose to split this chapter into two. There are multiple good reasons for doing so but the most important three are the following:
*This chapter is huge making reading a tedious job, overwhelming and scaring away the once that this article is intended for.
*This article has two logical section so braking it at '''Adding Functionality''' doesn't harm any body and helps newbies in achieving results. Being able to check a chapter and visually see the intermediate result is always the best motivation.
*Technically the same split at '''Adding Functionality''' is making a difference in know-how. the first part is not really new when you followed the ''site'' part examples '''Developing a Model-View-Controller Component 1, 2 and 3'''. Old wine in new bottles. The second part really goes into depth and requires good basic programming skills and a general understanding of HTML form handling.
If no objections I will initiate this spilt soon.<br>
--[[User:M.A.S.H|M.A.S.H]] 07:34, 10 August 2009 (UTC)

I think splitting it is a good idea and should improve readability. I look forward to seeing your improvements. [[User:Chris Davenport|Chris Davenport]] 08:51, 10 August 2009 (UTC)

== Confusing ==

I agree Part 4 gets confusing. I see what it is attempting to demonstrate but it is confusing to jump into a completely new example rather than use an example from the onset that could cover the details of the controls in the Admin area.

Maybe choosing a slightly more complex example than 'Hello world!' from the beginning?

Will be good to see this article when it's been updated!
----
I have to add my agreement to this -- the Hello World was a fine, basic example -- no need to crummy up the lesson with this sudden deviation into an entirely different example.

This article should be moved to its' own section, IMHO.
--[[User:HobbesPDX|HobbesPDX]] 23:21, 6 March 2010 (UTC)

== Hint in 'Mapping' section ==

I'm removing the so-called hint from the section titled 'Mapping a Joomla! MVC component from the example.'

I've never seen the 'registered' method, and I think it's bogus.

Please respond if I'm wrong.

[[User:HobbesPDX|HobbesPDX]] 20:19, 6 March 2010 (UTC)

== Move 'sharing template parts' note to another article? ==

I'd like to suggest to the community, that the expansive note, in section 3.2.3, regarding sharing template/view elements, using include/require, should be moved to another article.

It's a very helpful point, but I feel it adds unnecessary and extra information to an already complex document.

Discuss. :-)

--[[User:HobbesPDX|HobbesPDX]] 21:00, 6 March 2010 (UTC)

J1.5 talk:Developing a MVC Component/Creating an Administrator Interface

2010-03-06T23:21:50Z

HobbesPDX: Article should be moved.

== Renaming Part 4 ==
I checked out the comment below. ;-) Certainly, the multitude of hello(s) is confusing. What I did is to rename most everything.

Whenever there's something like HelloWhateverHello, the first Hello represents the component front-end, and the second represents the view/model. By the way, each view has its own model, which I think is pretty much standard MVC architecture. On the other hand, one controller can control several views, although this example doesn't do so.

Conversely, if you see HellosWhateverHello or HellosWhateverHellos, the first Hellos represents the adminstrative back-end, and the Hello or Hellos at the end refers to the view for editing one greeting or for listing all greetings, respectively. (Replace *Whatever* with Model, View, or Controller as appropriate.)

So, I renamed all this to look like FrontWhateverContent, AdminWhateverEdit, AdminWhateverList, and so on. Then I had to rename directories and files as well, so that models/hello.php became models/content.php in the front-end and models/edit.php in the back-end. Likewise, views/hello/ becomes views/content/ in the front-end and views/edit in the back-end. Also, in the back-end only, models/hellos.php & views/hellos/ become models/list.php & views/list. Lastly, I changed controllers/hello.php to controllers/edit.php, to reflect the change from HellosControllerHello to AdminControllerEdit.

Hope this clears things up a bit. It's a tedious refactoring exercise to do all this renaming, but it *is* doable. Good luck.

== "Hello" Overloaded ==

I'm not sure if anybody checks this, but I'm having a difficult time making my own component out of this document.

The first three chapters of this documentation are great. They are simple and to the point. The fourth, this page, is very confusing.

First off, the word "hello" is way over loaded. In the Creating an Admin Interface there are two models and two views:
Hello and Hellos

It's impossible to know why we need two different models. Why cant we use one model and two views?
Its totally impossible to understand which one gets called when.

I have discovered there are a lot of name conventions used here, but after reading this document over and over, it's still very difficult to know what the conventions are. This is probably stemming from "hello" being way too overloaded.

The method "get()" in JView is called in both views. It is supposed to automatically know which model to use, and which method to call. However, I don't think I followed the naming convention correctly, as it simply is not working (I get empty data with no error).

I think I could untangle the naming conventions myself, but with "hello" so overloaded in this example, I am having no luck guessing.

== Great up to chapter 3 ==

The documentation was great upto chapter 3. Got confused in 4th chapter.

Also, this doesn't cover how to create sub menus for a component [http://www.vojtechovsky.net/joomla/component/tutorial-joomla-1.5-free-component.png See example]

== Suggestions for improvement ==

*This is a really long and tedious tutorial with a lot of very useful information in it. I think it would help to break it down into parts or creating separate tutorials covering this material.
[[Link title]]

== REALLY GOOD DOCUMENTATION ==

Apart from a small error in part 4 which I have now corrected

did read:

$row =& $this->items[$i];
$checked = JHTML::_( 'grid.id', $i, $row->id );
$link = JRoute::_( 'index.php?option=com_hello>controller=hello>task=edit>cid[]='. $row->id );

now reads:

$row =& $this->items[$i];
$checked = JHTML::_( 'grid.id', $i, $row->id );
$link = JRoute::_( 'index.php?option=com_hello&controller=hello&task=edit&cid[]='. $row->id );

[[User:Jamesconroyuk|James Conroy]] 16:29, 16 February 2009 (UTC)

== Excellent documentation, but could use a slight extension ==

Have been able to create components using this set of tutorials, but am missing how to use non-string based data in the administrator interface.

The admin form only has one field (a string) and it might be useful to have either examples of, or a link to some other examples of how to view / capture other types of data such as :

Checkboxes (boolean)
Dropdown menus / radio button (int or string)

While it is easy to add the HTML form components (and even populate them with the values from the model), it isn't immediately clear how to recapture the data of these alternative types.

There is another tutorial I have seen on this wiki that has the "build in a rich editor" function, could use a link from this page.

[[User:craigmoore|Craig Moore]] 13:06, 09 May 2009 (UTC)

== Really a great tutorial ... but too many hello.php's ==

First of all, great tutorial, a very good effort to explain the basics.

Maybe just my problem:
I personally prefer to edit several files at a time, what means, i have 10-20 tabs open in my editor (UltraEdit).
In my case that means, that my editor tab-bar looks like:

hello.php - controller.php - hello.php - hello.php - hello.php - controller.php - hellos.php - and so on ...

I would kiss the shoes of everyone who would:

1.) precisely explain naming conventions for files of components (which file may, which file must be called hello.php)

2.) resolve the hello.php-maze in this tutorial with more speaking filenames

Thanks to the authors, best regards and a hello to everyone

Jochen

== Good Tutorial ==

Suggestion for improvement.

I also found Part 4 hard to follow and lacking explanation of why various names/paths/parameters were chosen. For a beginner trying to understand Joomla! MVC conventions I found another component backend howto that gave more of the details I was looking for: [http://www.scribd.com/doc/11515210/Joomla-Component-Development-Backend]

Hope this helps someone else.
-Mike
[[User:M3t00|M3t00]] 15:55, 10 June 2009 (UTC)

== RE: Renaming Part 4 ==

I'm actually even more confused now.

Only by reading through this discussion did it occur to me that you need to use multiple views to handle the various tasks in the controller. That seems like an important concept that is not entirely obvious to someone trying to learn the joomla framework. And yet now that I recognize the concept, it's not obvious what the best practices would be to implement multiple views. I'll work on it.

Despite that, this is still an extremely valuable tutorial -- especially considering that much of the rest of the API documentation is sparse at best. The entire joomla documentation in general could definitely benefit from a bit of a re-org.

EDIT: OK. So after reading through part 4 of the tutorial again, it is clear to me about the multiple views. So, looking back, it would have been valuable to explain that in the introduction. Something like:

"Now we will create an administrator section to create the greetings. It uses 2 views. The first view, called Hellos, will present a list of greetings with the ability to add new ones or remove old ones. The second view will allow the user to edit each greeting."

That would have helped tremendously. In any case, I got it now. I feel a little stupid for missing that the first time around, but maybe it was because it was late at night.

== Component Hello, Site Hello, Admin Hellos, Admin Hello ==

Chapters 1 and 2 were easy to follow. Chapter 3 contains some glitches that took me some time to understand but reading this chapter made everything really confusing. It took me a time to realise the Hello's, just my subject with only the focus clarifies already some impact. After re- and re-re reading it becomes clear to me what is meant. After re-reading the reason for using Hellos (as an Admin List) became clear and re-re- reading made the Admin single view/tmpl Hello obvious again. Why not rename these to:

* Manage_Hello_List
* Manage_Hello_Item

This would make everything much more readable, would set a clear context and increase the ease of understanding.<br>
--[[User:M.A.S.H|M.A.S.H]] 12:37, 3 August 2009 (UTC)

== Splitting up article into two articles ==

If the writers have no objection I propose to split this chapter into two. There are multiple good reasons for doing so but the most important three are the following:
*This chapter is huge making reading a tedious job, overwhelming and scaring away the once that this article is intended for.
*This article has two logical section so braking it at '''Adding Functionality''' doesn't harm any body and helps newbies in achieving results. Being able to check a chapter and visually see the intermediate result is always the best motivation.
*Technically the same split at '''Adding Functionality''' is making a difference in know-how. the first part is not really new when you followed the ''site'' part examples '''Developing a Model-View-Controller Component 1, 2 and 3'''. Old wine in new bottles. The second part really goes into depth and requires good basic programming skills and a general understanding of HTML form handling.
If no objections I will initiate this spilt soon.<br>
--[[User:M.A.S.H|M.A.S.H]] 07:34, 10 August 2009 (UTC)

I think splitting it is a good idea and should improve readability. I look forward to seeing your improvements. [[User:Chris Davenport|Chris Davenport]] 08:51, 10 August 2009 (UTC)

== Confusing ==

I agree Part 4 gets confusing. I see what it is attempting to demonstrate but it is confusing to jump into a completely new example rather than use an example from the onset that could cover the details of the controls in the Admin area.

Maybe choosing a slightly more complex example than 'Hello world!' from the beginning?

Will be good to see this article when it's been updated!
----
I have to add my agreement to this -- the Hello World was a fine, basic example -- no need to crummy up the lesson with this sudden deviation into an entirely different example.

This article should be moved to it's own section, IMHO.
--[[User:HobbesPDX|HobbesPDX]] 23:21, 6 March 2010 (UTC)

== Hint in 'Mapping' section ==

I'm removing the so-called hint from the section titled 'Mapping a Joomla! MVC component from the example.'

I've never seen the 'registered' method, and I think it's bogus.

Please respond if I'm wrong.

[[User:HobbesPDX|HobbesPDX]] 20:19, 6 March 2010 (UTC)

== Move 'sharing template parts' note to another article? ==

I'd like to suggest to the community, that the expansive note, in section 3.2.3, regarding sharing template/view elements, using include/require, should be moved to another article.

It's a very helpful point, but I feel it adds unnecessary and extra information to an already complex document.

Discuss. :-)

--[[User:HobbesPDX|HobbesPDX]] 21:00, 6 March 2010 (UTC)

J1.5:Developing a MVC Component/Basic Backend Framework

2010-03-06T22:53:37Z

HobbesPDX: cleanup

== Introduction ==
This article focuses on the entry page/article for the administrator. Whilst the MVC pattern is the same as for the frontend user, this chapter will rapidly go though all steps and setup the backend counter part in the admin section. This article will only focus on setting up the Basic Framework with a list of all the ''Hellos'' but without user interaction. The actual user interaction is added in the succeeding article [[Developing a Model-View-Controller Component - Part 6 - Adding Backend Actions]].

== Tutorial specific naming ==
Within the next articles the explanation of this administrator section we will keep as close as possible to the component name. For the general overview, lists from the database, we will use ''Hellos'' as identification. The ''Hellos'' naming will be used for viewing and controlling multiple Hellos at once from the database. When selecting a single Hello for Editing or Adding we will use the singular ''Hello'' as naming for the Controller and View. This ''Admin Hello'' has no functional relation with the ''Site Hello'' (the only dependency is the database content of cause).

Where parts 1,2 and 3 of the MVC explanation were working in the site directory tree of com_hello, part 5 and 6 will focus on the admin directory tree. Part 5 and 6 will not add or change files in the site directory tree. Look at the XML file in the attached example of the full com_hello implementation. The XML configuration file will help you with the exact location of the different files being used in this and the following chapter.

== Creating the Basic Framework ==

The basic framework of the administrator panel is very similar to the site portion. The main entry point for the administrator section of the component is hello.php. This file is identical to the hello.php file that was used in the site portion except the name of the controller it loads will be changed to HellosController. The default controller is also called controller.php and this file is identical to the default controller in the site portion, with the exception that the controller is named HellosController instead of HelloController. This difference is so that JController will by default load the hellos view, which will display a list of our greetings.

Here is the listing for hello.php:

<source lang="php"><?php
/**
* @package Joomla.Tutorials
* @subpackage Components
* @link http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_4
* @license GNU/GPL
*/

// No direct access

defined( '_JEXEC' ) or die( 'Restricted access' );

// Require the base controller

require_once( JPATH_COMPONENT.DS.'controller.php' );

// Require specific controller if requested
if($controller = JRequest::getWord('controller')) {
$path = JPATH_COMPONENT.DS.'controllers'.DS.$controller.'.php';
if (file_exists($path)) {
require_once $path;
} else {
$controller = '';
}
}

// Create the controller
$classname = 'HellosController'.$controller;
$controller = new $classname( );

// Perform the Request task
$controller->execute( JRequest::getVar( 'task' ) );

// Redirect if set by the controller
$controller->redirect();</source>

The view and model that we will start with is the hellos view and the hellos model. We will start with the model.

==== The Hellos Model ====

The Hellos Model will be very simple. The only operation that we currently need is the ability to retrieve the list of hellos from the database. This operation will be implemented in a method called getData().

The JModel class has a built in protected method called _getList(). This method can be used to simplify the task of retrieving a list of records from the database. We simply need to pass it the query and it will return the list of records.

At a later point in time, we might want to use our query from within another method. Therefore, we will create a private method called _buildQuery() which will return the query that will be passed to _getList(). This makes it easier to change the query as well since it is localized in one place.

Therefore we need two methods in our class: getData() and _buildQuery().

_buildQuery() simply returns the query. It looks like:

<source lang="php">/**
* Returns the query
* @return string The query to be used to retrieve the rows from the database
*/
function _buildQuery()
{
$query = ' SELECT * '
. ' FROM #__hello '
;

return $query;
}</source>

getData() will obtain the query and retrieve the records from the database. Now it might happen that we need to retrieve this list of data twice in one page load. It would be a waste to have to query the database twice. Therefore, we will have this method store the data in a protected property so that on subsequent requests it can simply return the data it has already retrieved. This property will be called _data. (''<-- Naming convention conflict. Private or Protected data should be preceded with a '_' but as this reference is returned to the view where this data is directly accessed, this data can only be considered as public.'')

Here is the getData() method:

<source lang="php">/**
* Retrieves the hello data
* @return array Array of objects containing the data from the database
*/
function getData()
{
// Lets load the data if it doesn't already exist
if (empty( $this->_data ))
{
$query = $this->_buildQuery();
$this->_data = $this->_getList( $query );
}

return $this->_data;
}</source>

The completed model looks like:

<source lang="php"><?php
/**
* Hellos Model for Hello World Component
*
* @package Joomla.Tutorials
* @subpackage Components
* @link http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_4
* @license GNU/GPL
*/

// Check to ensure this file is included in Joomla!
defined('_JEXEC') or die();

jimport( 'joomla.application.component.model' );

/**
* Hello Model
*
* @package Joomla.Tutorials
* @subpackage Components
*/
class HellosModelHellos extends JModel
{
/**
* Hellos data array
*
* @var array
*/
var $_data;

/**
* Returns the query
* @return string The query to be used to retrieve the rows from the database
*/
function _buildQuery()
{
$query = ' SELECT * '
. ' FROM #__hello '
;
return $query;
}

/**
* Retrieves the hello data
* @return array Array of objects containing the data from the database
*/
function getData()
{
// Lets load the data if it doesn't already exist
if (empty( $this->_data ))
{
$query = $this->_buildQuery();
$this->_data = $this->_getList( $query );
}

return $this->_data;
}
}</source>

This file is saved as models/hellos.php.

==== The Hellos View ====

Now that we have a model to retrieve our data, we need to display it. This view will be fairly similar to the view from the site section as well.

Just as our model was automatically instantiated in the site, so it is in the administrator. Methods that start with "get" [e.g. getData()] in the model can be accessed using the get() method of the JView class. So our view has three lines: one to retrieve the data from the model, one to push the data into the template, and one to invoke the display method to display the output. Thus we have:

<source lang="php"><?php
/**
* Hellos View for Hello World Component
*
* @package Joomla.Tutorials
* @subpackage Components
* @link http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_4
* @license GNU/GPL
*/

// Check to ensure this file is included in Joomla!
defined('_JEXEC') or die();

jimport( 'joomla.application.component.view' );

/**
* Hellos View
*
* @package Joomla.Tutorials
* @subpackage Components
*/
class HellosViewHellos extends JView
{
/**
* Hellos view display method
* @return void
**/
function display($tpl = null)
{
JToolBarHelper::title( JText::_( 'Hello Manager' ), 'generic.png' );
JToolBarHelper::deleteList();
JToolBarHelper::editListX();
JToolBarHelper::addNewX();

// Get data from the model
$items =& $this->get( 'Data');

$this->assignRef( 'items', $items );

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

This file is saved as views/hellos/view.html.php.

Look carefully at the almost hidden differences compared to ''site'' example. The data is stored in a variable that is encapsulated within the model. Because the data amount is huge due to using the very handy _getList(), the need for returning a reference instead of a value is obvious. This is handled in:
$items =& $this->get( 'Data');
Looking again at this line and you will notice another difference with respect to the ''site'' view.html.php. The calling of the model function is done implicitly. The actual model function name is getData(). In the ''site'' example you had to call following two lines:
$model =& $this->getModel();
$greeting = $model->getData();
Both lines are now taken care of by calling: <code>$this->get( 'Data');</code>. Under the surface of this <code>get()</code> the 'Data' is prefixed with 'get' so when using this function make sure the model functions are preceded with 'get'. This function can also be used in the ''site'' section. Keeping the data in the model and accessing it by reference, via <code>get()</code> methods, is the preferred way of getting data from the model.

==== The Hellos Template ====

The template will take the data pushed into it from the view and produce the output. We will display our output in a simple table. While the frontend template was very simple, in the administrator we will need a minimal amount of extra logic to handle looping through the data.

Here is our template:

<source lang="php"><?php defined('_JEXEC') or die('Restricted access'); ?>
<form action="index.php" method="post" name="adminForm">
<div id="editcell">
<table class="adminlist">
<thead>
<tr>
<th width="5">
<?php echo JText::_( 'ID' ); ?>
</th>
<th>
<?php echo JText::_( 'Greeting' ); ?>
</th>
</tr>
</thead>
<?php
$k = 0;
for ($i=0, $n=count( $this->items ); $i < $n; $i++)
{
$row =& $this->items[$i];
?>
<tr class="<?php echo "row$k"; ?>">
<td>
<?php echo $row->id; ?>
</td>
<td>
<?php echo $row->greeting; ?>
</td>
</tr>
<?php
$k = 1 - $k;
}
?>
</table>
</div>

<input type="hidden" name="option" value="com_hello" />
<input type="hidden" name="task" value="" />
<input type="hidden" name="boxchecked" value="0" />
<input type="hidden" name="controller" value="hello" />

</form></source>

This template is saved as views/hellos/tmpl/default.php.

You will notice that our output is enclosed in a form. Though this is not necessary now, it will be soon.

We have now completed the basic part of the first view. We have added five files to the admin section of our component:

* hello.php
* controller.php
* models/hellos.php
* views/hellos/view.html.php
* views/hellos/tmpl/default.php

You can now add these files to the XML install file and give it a try!

== Conclusion ==

We have now implemented a basic framework for the backend admin component. A list where all of the Hellos are displayed. The next chapter will extend this framework and add user interaction / database manipulation.

== Articles in this Series ==
[[Developing a Model-View-Controller Component - Part 1]]

[[Developing a Model-View-Controller Component - Part 2 - Adding a Model]]

[[Developing a Model-View-Controller Component - Part 3 - Using the Database]]

[[Developing a Model-View-Controller Component - Part 4 - Creating an Administrator Interface]]

[[Developing a Model-View-Controller Component - Part 5 - Basic Backend Framework]]

[[Developing a Model-View-Controller Component - Part 6 - Adding Backend Actions]]

== Contributors ==
* staalanden
* jamesconroyuk

== Download ==

The full admin component can be downloaded at: [http://joomlacode.org/gf/download/frsrelease/8111/29436/com_hello4_01.zip com_hello4_01].

[[Category:Development]]

J1.5:Developing a MVC Component/Basic Backend Framework

2010-03-06T22:45:10Z

HobbesPDX: spelling

== Introduction ==
This article focuses on the entry page/article for the administrator. Whilst the MVC pattern is the same as for the frontend user, this chapter will rapidly go though all steps and setup the backend counter part in the admin section. This article will only focus on setting up the Basic Framework with a list of all the ''Hellos'' but without user interaction. The actual user interaction is added in the succeeding article [[Developing a Model-View-Controller Component - Part 6 - Adding Backend Actions]].

== Tutorial specific naming ==
Within the next articles the explanation of this administrator section we will keep as close as possible to the component name. For the general overview, lists from the database, we will use ''Hellos'' as identification. The ''Hellos'' naming will be used for viewing and controlling multiple Hellos at once from the database. When selecting a single Hello for Editing or Adding we will use the singular ''Hello'' as naming for the Controller and View. This ''Admin Hello'' has no functional relation with the ''Site Hello'' (the only dependency is the database content of cause).

Where parts 1,2 and 3 of the MVC explanation were working in the site directory tree of com_hello, part 5 and 6 will focus on the admin directory tree. Part 5 and 6 will not add or change files in the site directory tree. Look at the XML file in the attached example of the full com_hello implementation. The XML configuration file will help you with the exact location of the different files being used in this and the following chapter.

== Creating the Basic Framework ==

The basic framework of the administrator panel is very similar to the site portion. The main entry point for the administrator section of the component is hello.php. This file is identical to the hello.php file that was used in the site portion except the name of the controller it loads will be changed to HellosController. The default controller is also called controller.php and this file is identical to the default controller in the site portion, with the exception that the controller is named HellosController instead of HelloController. This difference is so that JController will by default load the hellos view, which will display a list of our greetings.

Here is the listing for hello.php:

<source lang="php"><?php
/**
* @package Joomla.Tutorials
* @subpackage Components
* @link http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_4
* @license GNU/GPL
*/

// No direct access

defined( '_JEXEC' ) or die( 'Restricted access' );

// Require the base controller

require_once( JPATH_COMPONENT.DS.'controller.php' );

// Require specific controller if requested
if($controller = JRequest::getWord('controller')) {
$path = JPATH_COMPONENT.DS.'controllers'.DS.$controller.'.php';
if (file_exists($path)) {
require_once $path;
} else {
$controller = '';
}
}

// Create the controller
$classname = 'HellosController'.$controller;
$controller = new $classname( );

// Perform the Request task
$controller->execute( JRequest::getVar( 'task' ) );

// Redirect if set by the controller
$controller->redirect();</source>

The view and model that we will start with is the hellos view and the hellos model. We will start with the model.

==== The Hellos Model ====

The Hellos Model will be very simple. The only operation that we currently need is the ability to retrieve the list of hellos from the database. This operation will be implemented in a method called getData().

The JModel class has a built in protected method called _getList(). This method can be used to simplify the task of retrieving a list of records from the database. We simply need to pass it the query and it will return the list of records.

At a later point in time, we might want to use our query from within another method. Therefore, we will create a private method called _buildQuery() which will return the query that will be passed to _getList(). This makes it easier to change the query as well since it is localized in one place.

Therefore we need two methods in our class: getData() and _buildQuery().

_buildQuery() simply returns the query. It looks like:

<source lang="php">/**
* Returns the query
* @return string The query to be used to retrieve the rows from the database
*/
function _buildQuery()
{
$query = ' SELECT * '
. ' FROM #__hello '
;

return $query;
}</source>

getData() will obtain the query and retrieve the records from the database. Now it might happen that we need to retrieve this list of data twice in one page load. It would be a waste to have to query the database twice. Therefore, we will have this method store the data in a protected property so that on subsequent requests it can simply return the data it has already retrieved. This property will be called _data. (''<-- Naming convention conflict. Private or Protected data should be preceded with a '_' but as this reference is returned to the view where this data is directly accessed, this data can only be considered as public.'')

Here is the getData() method:

<source lang="php">/**
* Retrieves the hello data
* @return array Array of objects containing the data from the database
*/
function getData()
{
// Lets load the data if it doesn't already exist
if (empty( $this->_data ))
{
$query = $this->_buildQuery();
$this->_data = $this->_getList( $query );
}

return $this->_data;
}</source>

The completed model looks like:

<source lang="php"><?php
/**
* Hellos Model for Hello World Component
*
* @package Joomla.Tutorials
* @subpackage Components
* @link http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_4
* @license GNU/GPL
*/

// Check to ensure this file is included in Joomla!
defined('_JEXEC') or die();

jimport( 'joomla.application.component.model' );

/**
* Hello Model
*
* @package Joomla.Tutorials
* @subpackage Components
*/
class HellosModelHellos extends JModel
{
/**
* Hellos data array
*
* @var array
*/
var $_data;

/**
* Returns the query
* @return string The query to be used to retrieve the rows from the database
*/
function _buildQuery()
{
$query = ' SELECT * '
. ' FROM #__hello '
;
return $query;
}

/**
* Retrieves the hello data
* @return array Array of objects containing the data from the database
*/
function getData()
{
// Lets load the data if it doesn't already exist
if (empty( $this->_data ))
{
$query = $this->_buildQuery();
$this->_data = $this->_getList( $query );
}

return $this->_data;
}
}</source>

This file is saved as models/hellos.php.

==== The Hellos View ====

Now that we have a model to retrieve our data, we need to display it. This view will be fairly similar to the view from the site section as well.

Just as our model was automatically instantiated in the site, so it is in the administrator. Methods that start with "get" [e.g. getData()] in the model can be accessed using the get() method of the JView class. So our view has three lines: one to retrieve the data from the model, one to push the data into the template, and one to invoke the display method to display the output. Thus we have:

<source lang="php"><?php
/**
* Hellos View for Hello World Component
*
* @package Joomla.Tutorials
* @subpackage Components
* @link http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_4
* @license GNU/GPL
*/

// Check to ensure this file is included in Joomla!
defined('_JEXEC') or die();

jimport( 'joomla.application.component.view' );

/**
* Hellos View
*
* @package Joomla.Tutorials
* @subpackage Components
*/
class HellosViewHellos extends JView
{
/**
* Hellos view display method
* @return void
**/
function display($tpl = null)
{
JToolBarHelper::title( JText::_( 'Hello Manager' ), 'generic.png' );
JToolBarHelper::deleteList();
JToolBarHelper::editListX();
JToolBarHelper::addNewX();

// Get data from the model
$items =& $this->get( 'Data');

$this->assignRef( 'items', $items );

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

This file is saved as views/hellos/view.html.php.

Look carefully at the almost hidden differences compared to ''site'' example. The data is stored in a variable that is encapsulated within the model. Because the data amount is huge due to using the very handy _getList(), the need for returning a reference instead of a value is obvious. This is handled in:
$items =& $this->get( 'Data');
Looking again at this line and you will notice another difference with respect to the ''site'' view.html.php. The calling of the model function is done implicitly. The actual model function name is getData(). In the ''site'' example you had to call following two lines:
$model =& $this->getModel();
$greeting = $model->getData();
Both lines are now taken care of by calling: <code>$this->get( 'Data');</code>. Under the surface of this <code>get()</code> the 'Data' is prefixed with 'get' so when using this function make sure the model functions are preceded with 'get'. This function can also be used in the ''site'' section. It is considered good programming practise to keep the data in the model and access it by reference, <code>get()</code> methods are the preferred way of getting data from the model.

==== The Hellos Template ====

The template will take the data pushed into it from the view and produce the output. We will display our output in a simple table. While the frontend template was very simple, in the administrator we will need a minimal amount of extra logic to handle looping through the data.

Here is our template:

<source lang="php"><?php defined('_JEXEC') or die('Restricted access'); ?>
<form action="index.php" method="post" name="adminForm">
<div id="editcell">
<table class="adminlist">
<thead>
<tr>
<th width="5">
<?php echo JText::_( 'ID' ); ?>
</th>
<th>
<?php echo JText::_( 'Greeting' ); ?>
</th>
</tr>
</thead>
<?php
$k = 0;
for ($i=0, $n=count( $this->items ); $i < $n; $i++)
{
$row =& $this->items[$i];
?>
<tr class="<?php echo "row$k"; ?>">
<td>
<?php echo $row->id; ?>
</td>
<td>
<?php echo $row->greeting; ?>
</td>
</tr>
<?php
$k = 1 - $k;
}
?>
</table>
</div>

<input type="hidden" name="option" value="com_hello" />
<input type="hidden" name="task" value="" />
<input type="hidden" name="boxchecked" value="0" />
<input type="hidden" name="controller" value="hello" />

</form></source>

This template is saved as views/hellos/tmpl/default.php.

You will notice that our output is enclosed in a form. Though this is not necessary now, it will be soon.

We have now completed the basic part of the first view. We have added five files to the admin section of our component:

* hello.php
* controller.php
* models/hellos.php
* views/hellos/view.html.php
* views/hellos/tmpl/default.php

You can now add these files to the XML install file and give it a try!

== Conclusion ==

We have now implemented a basic framework for the backend admin component. A list where all of the Hellos are displayed. The next chapter will extend this framework and add user interaction / database manipulation.

== Articles in this Series ==
[[Developing a Model-View-Controller Component - Part 1]]

[[Developing a Model-View-Controller Component - Part 2 - Adding a Model]]

[[Developing a Model-View-Controller Component - Part 3 - Using the Database]]

[[Developing a Model-View-Controller Component - Part 4 - Creating an Administrator Interface]]

[[Developing a Model-View-Controller Component - Part 5 - Basic Backend Framework]]

[[Developing a Model-View-Controller Component - Part 6 - Adding Backend Actions]]

== Contributors ==
* staalanden
* jamesconroyuk

== Download ==

The full admin component can be downloaded at: [http://joomlacode.org/gf/download/frsrelease/8111/29436/com_hello4_01.zip com_hello4_01].

[[Category:Development]]

J1.5:Developing a MVC Component/Creating an Administrator Interface

2010-03-06T21:35:00Z

HobbesPDX:

{{ambox
| type = notice
| image = notice
| text = This {{thingamabob}} has been divided into three sections, two new articles are added. Especially this page needs a review
<small>(August 2009)</small>}}
== Introduction ==

In the first three tutorials, we have developed a MVC component that retrieves its data from a table in the database. Currently, there is no way to add data to the database except to do it manually using another tool. In the next articles of this tutorial, we will develop an administrator section for our component which will make it possible to manage the entries in the database.

This article, [[Developing a Model-View-Controller Component - Part 4 - Creating an Administrator Interface | Part 4 - Creating an Administrator Interface]], will be an article with no new source code for our Hello component but will describe some basic details of the MVC pattern. In the frontend solution (site section) we developed the first part of our component. The frontend solution is based upon default Controllers, Views and Templates and you were "taken by the hand" and "left to trust" the default handling of the code. This is going to change in the Backend or Administration section of our Hello component - we will have to develop all of the code that manages the application flow.

== Site / Admin ==
Joomla! is a content management system. The '''frontend''' is used for presenting the users with content and allows certain logged in users to manipulate the content. The '''backend''' is responsible for administering the website framework (structuring / managing / controlling / maintaining). This division between (frontend) site-content and (backend) administration is a fundamental aspect of the Joomla! architecture.

=== Entrance points ===
From the XML file of our frontend example it was already obvious that there would be an administration part:
<source lang="xml"><?xml version="1.0" encoding="utf-8"?>
...
<administration>

<menu>Hello World!</menu>

<files folder="admin">
<filename>hello.php</filename>
<filename>index.html</filename>
<filename>install.sql</filename>
<filename>uninstall.sql</filename>
</files>
</administration>
...
</source>
Only the .sql files were of use and only during installation for our frontend view, the other two files have no content besides generating a blank page. Access your websites' file system at your hosting provider (or on your own server) and browse through the directories after installing the frontend com_hello component. You may have noticed that our Hello component is to be found twice:
<root>/components/com_hello
<root>/administrator/components/com_hello

These two sub-directories link to the previously explained site-content and administration. Administrator interactions explicitly go via the administrator sub-directory, where guest or registered users will enter the default entrance on the root:
<root>/index.php
Administrative users will have to log in, and after logging in they will enter your site via:
<root>/administrator/index.php

With the different access points it is easy to grasp that with setting up the administrator section the naming conventions have no dependency with the site section. Whilst the MVC pattern is also applicable for the administrator section this implies that identical Controls, Views and Models naming can (and sometimes must) be used as in the site section.

== MVC pattern interaction ==
[[image:MVC joomla.png|frameless|right]]In [[Developing a Model-View-Controller Component - Part 1]] the figure on the right was used to explain the focus of the first three parts of this ''Developing a Model-View-Controller Component tutorial''. Now we will use this figure to explain how decisions are made on what is going to be displayed and how to manipulate this.

=== Example roll-out ===
For explanation purposes an easy to grasp example will be used. A library has the main function of lending books to registered users. Simply laid out there are three tables:
* users
* books
* relation

Lets keep it all very simple. The users are addressed by Id and Name. The books are identified by Id and Title and the relation contains both Ids and the date of lending.

[[image:Library Example.png|400px|frameless|center]]

The example is carefully chosen and will help in explaining the Joomla! architecture in more detail. The administrative side of our Hello component is not even that complex with only one table to manage. After the explanation of this chapter it should be easy to follow the tutorial in the succeeding chapters

=== Mapping a Joomla! MVC component from the example ===
In this example we will assume that administrative actions (add, edit, delete) are tasks that are to be performed by the administrator. For the frontend user only the view of the Relation table is interesting ("when do I have to bring back the books?"). This example shows the entire list and ignores all privacy stuff that could be taken care of by letting registered users only see their own books.

Just like our frontend Hello component, for this library component only the default view is being used in the frontend. It lists the relational table, left joining the other two tables to obtain a human readable list of books with their corresponding due date.
Alice | One flew over ... | 12-aug-2009
Alice | Celeb talk | 12-aug-2009
Mark | Joomla! | 15-aug-2009

With respect to the administration part it is important to understand that we have one default and three dedicated views, each controlling three tasks:
* <Component name default view>
* User administration
** Add
** Change
** Delete
* Book administration
** Add
** Change
** Delete
* Relation administration
** Add
** Change
** Delete

==== Controllers ====
The main controller of the admin section needs to differentiate between the different Adds, Changes or Deletes that are requested. This is taken care of by creating sub-controllers for each view for handling their specific tasks.
<root>/administrator/controller.php
<root>/administrator/controllers/users.php
<root>/administrator/controllers/books.php
<root>/administrator/controllers/relation.php

The controller is an important part of the MVC pattern. Not only does it take care of the requested tasks, it is also the initiator of instantiating the model with the same name and it is responsible for setting the view and the desired form for that view. The controller really justifies its name.

Within the controller it is good to make a difference between '''activating tasks''' (for example the edit selection from a menu) and '''resulting tasks''' (for example the result of an edit trigger is the posted data).

Typical controller functions look like:
<source lang="php">
function <activating task>() // <-- edit, add, delete
{
JRequest::setVar( 'view', '[<componentname> | users | books | relation ]' );
JRequest::setVar( 'layout', 'default' ); // <-- The default form is named here, but in
// some complex views, multiple layouts might
// be needed.
parent::display();
}

function <resulting task>() // <-- save, remove
{
$model = $this->getModel('[<componentname> | users | books | relation ]');
if(!$model->action() ) { // <-- action could be delete() or store()
$msg = JText::_( 'Error: Could not perform action' );
} else {
$msg = JText::_( 'Action executed' );
}

$this->setRedirect( 'index.php?option=<componentname>', $msg );
}
</source>
A controller takes care of all tasks for that dedicated controller. After completing a resulting task the module will return to the main administration entrance point for that component, the main controller with the default view. Activating tasks enforce a new view with a form to display after first defining it.

The explicit definition of the form within a view might raise some eyebrows but our examples are too simple. For the general understanding and consistency this field should mostly be ''default''. In complex views multiple forms could be defined within one view.

==== Models ====
The Controllers interact with their equally named Model counter part. In the frontend view the Model was only used to retrieve data. The backend has more controllers and thus also more model files. The backend model files not only are responsible for delivering data to the viewer but also take care of tasks initiated from the controller. A good model contains all actions required to manage a single table in the database.
<root>/administrator/models/<componentname>.php
<root>/administrator/models/users.php
<root>/administrator/models/books.php
<root>/administrator/models/relation.php

==== Views ====
Separate views are of course also required. For views and subsequent forms no forced naming conventions are required (linking to views is taken care of in the controller). In the following listing the Administrative tasks are identified as a subset for the different views. This choice is totally random and maybe even non-logical but that doesn't matter for the explanation. Just for example purposes I added also a different view, a delete view, that could be used for all the deletes for all administrative tasks asking an "Are you sure" display.

<root>/administrator/views/<componentname>/view.html.php + .../tmpl/default.php
<root>/administrator/views/users/view.html.php + .../tmpl/default.php
<root>/administrator/views/books/view.html.php + .../tmpl/default.php
<root>/administrator/views/relation/view.html.php + .../tmpl/default.php
 
<root>/administrator/views/delete/view.html.php + .../tmpl/default.php

''Note'': In general it is good practice to maintain one form per view because the view.html.php still has to deliver the content. With some basic logic you can enable, disable certain content but if this logic is becoming too complex start considering splitting up the view.

''Note'': Sharing template parts amongst the different views (for uniform layouting of headers and titles of your component) can be done using the PHP <code>include / require;</code>. There is one slight problem ... how to make the logical reference? In my modules I have a collector bin for general to use sniplets. Because it involved the views and forms I put this general bin in the views directory. The variable $pathToGeneralView needs to be defined somewhere in the first lines of your file and you have to make sure that the logical reference path is correct (the '..'s). In the following example the files marked with a '*' use the following code:

./com_compname/views/general/navigate.header.php <-- sniplet code for the header
./com_compname/views/general/navigate.footer.php <-- sniplet code for the footer
./com_compname/views/mngtable1/view.html.php
./com_compname/views/mngtable1/tmpl/default.php *
./com_compname/views/mngtable2/view.html.php
./com_compname/views/mngtable2/tmpl/default.php *

<source lang=php>
$pathToGeneralView = strchr(dirname(__FILE__), dirname($_SERVER['SCRIPT_NAME']));
$pathToGeneralView = str_replace(dirname($_SERVER['SCRIPT_NAME']),'.',$pathToGeneralView );
$pathToGeneralView = $pathToGeneralView . "/../../general/"; <-- returning path from current position.
...
<?php require_once $pathToGeneralView . 'navigation.header.php'; ?>
<P>Do something
<?php require_once $pathToGeneralView . 'navigation.footer.php'; ?>
</source>
Another Way to do the same thing:
<source lang=php>
$pathToGeneralView = JPATH_COMPONENT_ADMINISTRATOR.DS. "views".DS."general".DS; <-- will return 'path/Joomla/administrator/components/com_example/views/general/
...
<?php require_once $pathToGeneralView . 'navigation.header.php'; ?>
<P>Do something
<?php require_once $pathToGeneralView . 'navigation.footer.php'; ?>
</source>

''Note'': Giving the forms logical instead of the ''default'' naming is of course handy when having a lot of different views. Also, having that many ''default'' forms can make it difficult to determine the context. On the other hand, the view.html.php cannot be renamed, and one is always forced to look at the directory name for the view.

=== Essential Interaction Parameters ===
Everything is in place:
* main and dedicated controllers;
* main and dedicated modules;
* different views and their forms.

Just one big question remains: '''How to use them'''!

Three parameters are mandatory for letting Joomla! do its job:
* option
* controller
* task

These three parameters are almost self explaining ;). The ''option'' part when developing a component is easy, always assign your component name to it. For component development consider this one as a constant, of course the Joomla! engine has more options than only components.

The ''controller'' and ''task'' parameters can be manipulated within your component anyway you want it to.

==== How it all works together ====
Looking at the simplified MVC picture Joomla! the logical flow of interaction goes the following way:
# What is my entrance point?
#*The Joomla! engine discovers a logged in administrator and sets the entrance point to <root>/administrator/index.php otherwise it wil go to the <root>/index.php entrance.
# What option is requested?
#*The Joomla! engine reads the option variable and discovers that a component named <componentname> is requested. The entrance point becomes: <root>/administrator/components/com_<componentname>/<componentname>.php
# Is there need to access a dedicated controller?
#* The Joomla! engine reads the controller variable and discovers that a dedicated controller is required: <root>/administrator/components/com_<componentname>/controllers/<dedicatedcontroller>.php
# Is there a task that needs to be addressed?
#* The identified controller is handed the task value as parameter.
# The Model is derived from the controller and instantiated.
# The View and Form are set in the controller and initiated to become active.

=== How to add interaction ===
Within HTML there are two common ways to interact with Joomla!:
# reference to a link
# form submission post / get

==== Link reference for the Joomla! engine ====
Remember the '''activating tasks''' and '''resulting tasks''' mentioned earlier? Most activating tasks are initiated by a link. In case of the Library example the site section overview could be copied to the admin section. This default view will now be extended and every cell will become a link for editing the specific database element.

Using the Library example, the template PHP code without looping control will contain the following code:
<source lang=php>
$link = JRoute::_( 'index.php?option=com_library&controller=users&task=edit&cid='. $row->idu );
echo "<td><a href=\"".$link."\">$row->name</a></td>";
$link = JRoute::_( 'index.php?option=com_library&controller=books&task=edit&cid='. $row->idb );
echo "<td><a href=\"".$link."\">$row->title</a></td>";
$link = JRoute::_( 'index.php?option=com_library&controller=relation&task=edit&cid='. $row->idr );
echo "<td><a href=\"".$link."\">$row->date</a></td>";
</source>

Within each clickable field the three mandatory parameters to manipulate Joomla! can be identified. In addition there is one user parameter for handling the correct index in the controller task (cid). These parameter are separated by '&'. Do not use spaces in your variables, as this might screw-up parameter handling in certain browsers. After looping, all text entries will be clickable and trigger the corresponding controller with the correct row id in the associated table.

[Alice} | [One flew over ...] | [12-aug-2009]
[Alice] | [Celeb talk] | [12-aug-2009]
[Mark] | [Joomla!] | [15-aug-2009]

==== Posting Form Data to the Joomla! Engine ====
After being initiated by an activating task, an input form view might be the result. The snippet of code below could be the result of clicking the first cell of the default component view that is clicked for editing ([Alice]:cid=3).

<source lang="php">
<form action="index.php" method="post">
<input type="text" name="username" id="username" size="32" maxlength="250" value="<?php echo $this->user->name;?>" />

<input type="submit" name="SubmitButton" value="Save" />

<input type="hidden" name="option" value="com_library" /> // <-- mandatory
<input type="hidden" name="controller" value="hello" /> // <-- mandatory
<input type="hidden" name="task" value="save" /> // <-- mandatory
<input type="hidden" name="id" value="<?php echo $this->user->id; ?>" /> // <-- user parameter, index in database for [Alice]
</form>
</source>

The three Joomla! mandatory parameters are placed as hidden in the form. Hidden parameters are not shown in any way but will be added to the posting data.

''Tip'': when debugging this form, replace in the form tag <code>method="post"</code> temporarily with <code>method="get"</code>. All posted parameters will be shown in the URL of your browser. If the module is working undo this change. For one reason it looks sharper without all the parameters being shown in the URL and you avoid motivating people to manipulate the browser URL themselves. Of course one can look at the source code but using ''Post'' instead of ''Get'', but this eliminates the first 90% of the earth population. The other reason is more technical and the simple explanation is that post methods (i.e. method="post") can contain more (complex) data.

''Remark'': In some developed modules you may notice that developers have also added the ''view'' parameter. This is bad programming whilst the controller(s) should take care of the ''view'' and the ''form''.

== Conclusion ==

The use of the three mandatory parameters and the different access points are clarified. Let's do something with this knowledge and extend the Hello component to the administrative section in the succeeding articles of this tutorial.

== Articles in this Series ==
[[Developing a Model-View-Controller Component - Part 1]]

[[Developing a Model-View-Controller Component - Part 2 - Adding a Model]]

[[Developing a Model-View-Controller Component - Part 3 - Using the Database]]

[[Developing a Model-View-Controller Component - Part 4 - Creating an Administrator Interface]]

[[Developing a Model-View-Controller Component - Part 5 - Basic Backend Framework]]

[[Developing a Model-View-Controller Component - Part 6 - Adding Backend Actions]]

== Contributors ==
* staalanden
* jamesconroyuk

[[Category:Development]]

J1.5:Developing a MVC Component/Creating an Administrator Interface

2010-03-06T21:29:23Z

HobbesPDX: cleanup

{{ambox
| type = notice
| image = notice
| text = This {{thingamabob}} has been divided into three sections, two new articles are added. Especially this page needs a review
<small>(August 2009)</small>}}
== Introduction ==

In the first three tutorials, we have developed a MVC component that retrieves its data from a table in the database. Currently, there is no way to add data to the database except to do it manually using another tool. In the next articles of this tutorial, we will develop an administrator section for our component which will make it possible to manage the entries in the database.

This article, [[Developing a Model-View-Controller Component - Part 4 - Creating an Administrator Interface | Part 4 - Creating an Administrator Interface]], will be an article with no new source code for our Hello component but will describe some basic details of the MVC pattern. In the frontend solution (site section) we developed the first part of our component. The frontend solution is based upon default Controllers, Views and Templates and you were "taken by the hand" and "left to trust" the default handling of the code. This is going to change in the Backend or Administration section of our Hello component - we will have to develop all of the code that manages the application flow.

== Site / Admin ==
Joomla! is a content management system. The '''frontend''' is used for presenting the users with content and allows certain logged in users to manipulate the content. The '''backend''' is responsible for administering the website framework (structuring / managing / controlling / maintaining). This division between (frontend) site-content and (backend) administration is a fundamental aspect of the Joomla! architecture.

=== Entrance points ===
From the XML file of our frontend example it was already obvious that there would be an administration part:
<source lang="xml"><?xml version="1.0" encoding="utf-8"?>
...
<administration>

<menu>Hello World!</menu>

<files folder="admin">
<filename>hello.php</filename>
<filename>index.html</filename>
<filename>install.sql</filename>
<filename>uninstall.sql</filename>
</files>
</administration>
...
</source>
Only the .sql files were of use and only during installation for our frontend view, the other two files have no content besides generating a blank page. Access your websites' file system at your hosting provider (or on your own server) and browse through the directories after installing the frontend com_hello component. You may have noticed that our Hello component is to be found twice:
<root>/components/com_hello
<root>/administrator/components/com_hello

These two sub-directories link to the previously explained site-content and administration. Administrator interactions explicitly go via the administrator sub-directory, where guest or registered users will enter the default entrance on the root:
<root>/index.php
Administrative users will have to log in, and after logging in they will enter your site via:
<root>/administrator/index.php

With the different access points it is easy to grasp that with setting up the administrator section the naming conventions have no dependency with the site section. Whilst the MVC pattern is also applicable for the administrator section this implies that identical Controls, Views and Models naming can (and sometimes must) be used as in the site section.

== MVC pattern interaction ==
[[image:MVC joomla.png|frameless|right]]In [[Developing a Model-View-Controller Component - Part 1]] the figure on the right was used to explain the focus of the first three parts of this ''Developing a Model-View-Controller Component tutorial''. Now we will use this figure to explain how decisions are made on what is going to be displayed and how to manipulate this.

=== Example roll-out ===
For explanation purposes an easy to grasp example will be used. A library has the main function of lending books to registered users. Simply laid out there are three tables:
* users
* books
* relation

Lets keep it all very simple. The users are addressed by Id and Name. The books are identified by Id and Title and the relation contains both Ids and the date of lending.

[[image:Library Example.png|400px|frameless|center]]

The example is carefully chosen and will help in explaining the Joomla! architecture in more detail. The administrative side of our Hello component is not even that complex with only one table to manage. After the explanation of this chapter it should be easy to follow the tutorial in the succeeding chapters

=== Mapping a Joomla! MVC component from the example ===
In this example we will assume that administrative actions (add, edit, delete) are tasks that are to be performed by the administrator. For the frontend user only the view of the Relation table is interesting ("when do I have to bring back the books?"). This example shows the entire list and ignores all privacy stuff that could be taken care of by letting registered users only see their own books.

Just like our frontend Hello component, for this library component only the default view is being used in the frontend. It lists the relational table, left joining the other two tables to obtain a human readable list of books with their corresponding due date.
Alice | One flew over ... | 12-aug-2009
Alice | Celeb talk | 12-aug-2009
Mark | Joomla! | 15-aug-2009

With respect to the administration part it is important to understand that we have one default and three dedicated views, each controlling three tasks:
* <Component name default view>
* User administration
** Add
** Change
** Delete
* Book administration
** Add
** Change
** Delete
* Relation administration
** Add
** Change
** Delete

==== Controllers ====
The main controller of the admin section needs to differentiate between the different Adds, Changes or Deletes that are requested. This is taken care of by creating sub-controllers for each view for handling their specific tasks.
<root>/administrator/controller.php
<root>/administrator/controllers/users.php
<root>/administrator/controllers/books.php
<root>/administrator/controllers/relation.php

The controller is an important part of the MVC pattern. Not only does it take care of the requested tasks, it is also the initiator of instantiating the model with the same name and it is responsible for setting the view and the desired form for that view. The controller really justifies its name.

Within the controller it is good to make a difference between '''activating tasks''' (for example the edit selection from a menu) and '''resulting tasks''' (for example the result of an edit trigger is the posted data).

Typical controller functions look like:
<source lang="php">
function <activating task>() // <-- edit, add, delete
{
JRequest::setVar( 'view', '[<componentname> | users | books | relation ]' );
JRequest::setVar( 'layout', 'default' ); // <-- The default form is named here, but in
// some complex views, multiple layouts might
// be needed.
parent::display();
}

function <resulting task>() // <-- save, remove
{
$model = $this->getModel('[<componentname> | users | books | relation ]');
if(!$model->action() ) { // <-- action could be delete() or store()
$msg = JText::_( 'Error: Could not perform action' );
} else {
$msg = JText::_( 'Action executed' );
}

$this->setRedirect( 'index.php?option=<componentname>', $msg );
}
</source>
A controller takes care of all tasks for that dedicated controller. After completing a resulting task the module will return to the main administration entrance point for that component, the main controller with the default view. Activating tasks enforce a new view with a form to display after first defining it.

The explicit definition of the form within a view might raise some eyebrows but our examples are too simple. For the general understanding and consistency this field should mostly be ''default''. In complex views multiple forms could be defined within one view.

==== Models ====
The Controllers interact with their equally named Model counter part. In the frontend view the Model was only used to retrieve data. The backend has more controllers and thus also more model files. The backend model files not only are responsible for delivering data to the viewer but also take care of tasks initiated from the controller. A good model contains all actions required to manage a single table in the database.
<root>/administrator/models/<componentname>.php
<root>/administrator/models/users.php
<root>/administrator/models/books.php
<root>/administrator/models/relation.php

==== Views ====
Separate views are of course also required. For views and subsequent forms no forced naming conventions are required (linking to views is taken care of in the controller). In the following listing the Administrative tasks are identified as a subset for the different views. This choice is totally random and maybe even non-logical but that doesn't matter for the explanation. Just for example purposes I added also a different view, a delete view, that could be used for all the deletes for all administrative tasks asking an "Are you sure" display.

<root>/administrator/views/<componentname>/view.html.php + .../tmpl/default.php
<root>/administrator/views/users/view.html.php + .../tmpl/default.php
<root>/administrator/views/books/view.html.php + .../tmpl/default.php
<root>/administrator/views/relation/view.html.php + .../tmpl/default.php
 
<root>/administrator/views/delete/view.html.php + .../tmpl/default.php

''Note'': In general it is good practice to maintain one form per view because the view.html.php still has to deliver the content. With some basic logic you can enable, disable certain content but if this logic is becoming too complex start considering splitting up the view.

''Note'': Sharing template parts amongst the different views (for uniform layouting of headers and titles of your component) can be done using the PHP <code>include / require;</code>. There is one slight problem ... how to make the logical reference? In my modules I have a collector bin for general to use sniplets. Because it involved the views and forms I put this general bin in the views directory. The variable $pathToGeneralView needs to be defined somewhere in the first lines of your file and you have to make sure that the logical reference path is correct (the '..'s). In the following example the files marked with a '*' use the following code:

./com_compname/views/general/navigate.header.php <-- sniplet code for the header
./com_compname/views/general/navigate.footer.php <-- sniplet code for the footer
./com_compname/views/mngtable1/view.html.php
./com_compname/views/mngtable1/tmpl/default.php *
./com_compname/views/mngtable2/view.html.php
./com_compname/views/mngtable2/tmpl/default.php *

<source lang=php>
$pathToGeneralView = strchr(dirname(__FILE__), dirname($_SERVER['SCRIPT_NAME']));
$pathToGeneralView = str_replace(dirname($_SERVER['SCRIPT_NAME']),'.',$pathToGeneralView );
$pathToGeneralView = $pathToGeneralView . "/../../general/"; <-- returning path from current position.
...
<?php require_once $pathToGeneralView . 'navigation.header.php'; ?>
<P>Do something
<?php require_once $pathToGeneralView . 'navigation.footer.php'; ?>
</source>
Another Way to do the same thing:
<source lang=php>
$pathToGeneralView = JPATH_COMPONENT_ADMINISTRATOR.DS. "views".DS."general".DS; <-- will return 'path/Joomla/administrator/components/com_example/views/general/
...
<?php require_once $pathToGeneralView . 'navigation.header.php'; ?>
<P>Do something
<?php require_once $pathToGeneralView . 'navigation.footer.php'; ?>
</source>

''Note'': Giving the forms logical instead of the ''default'' naming is of course handy when having a lot of different views. Also, having that many ''default'' forms can make it difficult to determine the context. On the other hand, the view.html.php cannot be renamed, and one is always forced to look at the directory name for the view.

=== Essential Interaction Parameters ===
Everything is in place:
* main and dedicated controllers;
* main and dedicated modules;
* different views and their forms.

Just one big question remains: '''How to use them'''!

Three parameters are mandatory for letting Joomla! do its job:
* option
* controller
* task

These three parameters are almost self explaining ;). The ''option'' part when developing a component is easy, always assign your component name to it. For component development consider this one as a constant, of course the Joomla! engine has more options than only components.

The ''controller'' and ''task'' parameters can be manipulated within your component anyway you want it to.

==== How it all works together ====
Looking at the simplified MVC picture Joomla! the logical flow of interaction goes the following way:
# What is my entrance point?
#*The Joomla! engine discovers a logged in administrator and sets the entrance point to <root>/administrator/index.php otherwise it wil go to the <root>/index.php entrance.
# What option is requested?
#*The Joomla! engine reads the option variable and discovers that a component named <componentname> is requested. The entrance point becomes: <root>/administrator/components/com_<componentname>/<componentname>.php
# Is there need to access a dedicated controller?
#* The Joomla! engine reads the controller variable and discovers that a dedicated controller is required: <root>/administrator/components/com_<componentname>/controllers/<dedicatedcontroller>.php
# Is there a task that needs to be addressed?
#* The identified controller is handed the task value as parameter.
# The Model is derived from the controller and instantiated.
# The View and Form are set in the controller and initiated to become active.

=== How to add interaction ===
Within HTML there are two common ways to interact with Joomla!:
# reference to a link
# form submission post / get

==== Link reference for the Joomla! engine ====
Remember the '''activating tasks''' and '''resulting tasks''' mentioned earlier? Most activating tasks are initiated by a link. In case of the Library example the site section overview could be copied to the admin section. This default view will now be extended and every cell will become a link for editing the specific database element.

Using the Library example, the template PHP code without looping control will contain the following code:
<source lang=php>
$link = JRoute::_( 'index.php?option=com_library&controller=users&task=edit&cid='. $row->idu );
echo "<td><a href=\"".$link."\">$row->name</a></td>";
$link = JRoute::_( 'index.php?option=com_library&controller=books&task=edit&cid='. $row->idb );
echo "<td><a href=\"".$link."\">$row->title</a></td>";
$link = JRoute::_( 'index.php?option=com_library&controller=relation&task=edit&cid='. $row->idr );
echo "<td><a href=\"".$link."\">$row->date</a></td>";
</source>

Within each clickable field the three mandatory parameters to manipulate MVC can be identified. In addition there is one user parameter for handling the correct index in the controller task (cid). These parameter are separated by '&'. Do not use spaces in your variables this might screw-up parameter handling in certain browsers. After looping all text entries will be clickable and trigger the corresponding controller with the correct row id in the associated table.

[Alice} | [One flew over ...] | [12 aug 2009]
[Alice] | [Celeb talk] | [12 aug 2009]
[Mark] | [Joomla!] | [15 aug 2009]

==== Posting Form Data to the Joomla! Engine ====
After being initiated by an activating task, an input form view might be the result. The sniplet code below could be the result of clicking the first cell of the default component view that is clicked for editing ([Alice]:cid=3).

<source lang="php">
<form action="index.php" method="post">
<input type="text" name="username" id="username" size="32" maxlength="250" value="<?php echo $this->user->name;?>" />

<input type="submit" name="SubmitButton" value="Save" />

<input type="hidden" name="option" value="com_library" /> // <-- mandatory
<input type="hidden" name="controller" value="hello" /> // <-- mandatory
<input type="hidden" name="task" value="save" /> // <-- mandatory
<input type="hidden" name="id" value="<?php echo $this->user->id; ?>" /> // <-- user parameter, index in database for [Alice]
</form>
</source>

The three Joomla! mandatory parameters are placed as hidden in the form. Hidden parameters are not shown in any way but will be added to the posting data.

''Tip'': when debugging this form, replace in the form tag <code>method="post"</code> temporarily with <code>method="get"</code>. All posted parameters will be shown in the URL of your browser. If the module is working undo this change. For one reason it looks sharper without all the parameters being shown in the URL and you avoid motivating people to manipulate the browser URL themselves. Of course one can look at the source code but using ''Post'' instead of ''Get'', but this eliminates the first 90% of the earth population. The other reason is more technical and the simple explanation is that post methods (i.e. method="post") can contain more (complex) data.

''Remark'': In some developed modules you may notice that developers have also added the ''view'' parameter. This is bad programming whilst the controller(s) should take care of the ''view'' and the ''form''.

== Conclusion ==

The use of the three mandatory parameters and the different access points are clarified. Let's do something with this knowledge and extend the Hello component to the administrative section in the succeeding articles of this tutorial.

== Articles in this Series ==
[[Developing a Model-View-Controller Component - Part 1]]

[[Developing a Model-View-Controller Component - Part 2 - Adding a Model]]

[[Developing a Model-View-Controller Component - Part 3 - Using the Database]]

[[Developing a Model-View-Controller Component - Part 4 - Creating an Administrator Interface]]

[[Developing a Model-View-Controller Component - Part 5 - Basic Backend Framework]]

[[Developing a Model-View-Controller Component - Part 6 - Adding Backend Actions]]

== Contributors ==
* staalanden
* jamesconroyuk

[[Category:Development]]

J1.5 talk:Developing a MVC Component/Creating an Administrator Interface

2010-03-06T21:00:33Z

HobbesPDX: /* Move 'sharing template parts' note to another article? */ new section

== Renaming Part 4 ==
I checked out the comment below. ;-) Certainly, the multitude of hello(s) is confusing. What I did is to rename most everything.

Whenever there's something like HelloWhateverHello, the first Hello represents the component front-end, and the second represents the view/model. By the way, each view has its own model, which I think is pretty much standard MVC architecture. On the other hand, one controller can control several views, although this example doesn't do so.

Conversely, if you see HellosWhateverHello or HellosWhateverHellos, the first Hellos represents the adminstrative back-end, and the Hello or Hellos at the end refers to the view for editing one greeting or for listing all greetings, respectively. (Replace *Whatever* with Model, View, or Controller as appropriate.)

So, I renamed all this to look like FrontWhateverContent, AdminWhateverEdit, AdminWhateverList, and so on. Then I had to rename directories and files as well, so that models/hello.php became models/content.php in the front-end and models/edit.php in the back-end. Likewise, views/hello/ becomes views/content/ in the front-end and views/edit in the back-end. Also, in the back-end only, models/hellos.php & views/hellos/ become models/list.php & views/list. Lastly, I changed controllers/hello.php to controllers/edit.php, to reflect the change from HellosControllerHello to AdminControllerEdit.

Hope this clears things up a bit. It's a tedious refactoring exercise to do all this renaming, but it *is* doable. Good luck.

== "Hello" Overloaded ==

I'm not sure if anybody checks this, but I'm having a difficult time making my own component out of this document.

The first three chapters of this documentation are great. They are simple and to the point. The fourth, this page, is very confusing.

First off, the word "hello" is way over loaded. In the Creating an Admin Interface there are two models and two views:
Hello and Hellos

It's impossible to know why we need two different models. Why cant we use one model and two views?
Its totally impossible to understand which one gets called when.

I have discovered there are a lot of name conventions used here, but after reading this document over and over, it's still very difficult to know what the conventions are. This is probably stemming from "hello" being way too overloaded.

The method "get()" in JView is called in both views. It is supposed to automatically know which model to use, and which method to call. However, I don't think I followed the naming convention correctly, as it simply is not working (I get empty data with no error).

I think I could untangle the naming conventions myself, but with "hello" so overloaded in this example, I am having no luck guessing.

== Great up to chapter 3 ==

The documentation was great upto chapter 3. Got confused in 4th chapter.

Also, this doesn't cover how to create sub menus for a component [http://www.vojtechovsky.net/joomla/component/tutorial-joomla-1.5-free-component.png See example]

== Suggestions for improvement ==

*This is a really long and tedious tutorial with a lot of very useful information in it. I think it would help to break it down into parts or creating separate tutorials covering this material.
[[Link title]]

== REALLY GOOD DOCUMENTATION ==

Apart from a small error in part 4 which I have now corrected

did read:

$row =& $this->items[$i];
$checked = JHTML::_( 'grid.id', $i, $row->id );
$link = JRoute::_( 'index.php?option=com_hello>controller=hello>task=edit>cid[]='. $row->id );

now reads:

$row =& $this->items[$i];
$checked = JHTML::_( 'grid.id', $i, $row->id );
$link = JRoute::_( 'index.php?option=com_hello&controller=hello&task=edit&cid[]='. $row->id );

[[User:Jamesconroyuk|James Conroy]] 16:29, 16 February 2009 (UTC)

== Excellent documentation, but could use a slight extension ==

Have been able to create components using this set of tutorials, but am missing how to use non-string based data in the administrator interface.

The admin form only has one field (a string) and it might be useful to have either examples of, or a link to some other examples of how to view / capture other types of data such as :

Checkboxes (boolean)
Dropdown menus / radio button (int or string)

While it is easy to add the HTML form components (and even populate them with the values from the model), it isn't immediately clear how to recapture the data of these alternative types.

There is another tutorial I have seen on this wiki that has the "build in a rich editor" function, could use a link from this page.

[[User:craigmoore|Craig Moore]] 13:06, 09 May 2009 (UTC)

== Really a great tutorial ... but too many hello.php's ==

First of all, great tutorial, a very good effort to explain the basics.

Maybe just my problem:
I personally prefer to edit several files at a time, what means, i have 10-20 tabs open in my editor (UltraEdit).
In my case that means, that my editor tab-bar looks like:

hello.php - controller.php - hello.php - hello.php - hello.php - controller.php - hellos.php - and so on ...

I would kiss the shoes of everyone who would:

1.) precisely explain naming conventions for files of components (which file may, which file must be called hello.php)

2.) resolve the hello.php-maze in this tutorial with more speaking filenames

Thanks to the authors, best regards and a hello to everyone

Jochen

== Good Tutorial ==

Suggestion for improvement.

I also found Part 4 hard to follow and lacking explanation of why various names/paths/parameters were chosen. For a beginner trying to understand Joomla! MVC conventions I found another component backend howto that gave more of the details I was looking for: [http://www.scribd.com/doc/11515210/Joomla-Component-Development-Backend]

Hope this helps someone else.
-Mike
[[User:M3t00|M3t00]] 15:55, 10 June 2009 (UTC)

== RE: Renaming Part 4 ==

I'm actually even more confused now.

Only by reading through this discussion did it occur to me that you need to use multiple views to handle the various tasks in the controller. That seems like an important concept that is not entirely obvious to someone trying to learn the joomla framework. And yet now that I recognize the concept, it's not obvious what the best practices would be to implement multiple views. I'll work on it.

Despite that, this is still an extremely valuable tutorial -- especially considering that much of the rest of the API documentation is sparse at best. The entire joomla documentation in general could definitely benefit from a bit of a re-org.

EDIT: OK. So after reading through part 4 of the tutorial again, it is clear to me about the multiple views. So, looking back, it would have been valuable to explain that in the introduction. Something like:

"Now we will create an administrator section to create the greetings. It uses 2 views. The first view, called Hellos, will present a list of greetings with the ability to add new ones or remove old ones. The second view will allow the user to edit each greeting."

That would have helped tremendously. In any case, I got it now. I feel a little stupid for missing that the first time around, but maybe it was because it was late at night.

== Component Hello, Site Hello, Admin Hellos, Admin Hello ==

Chapters 1 and 2 were easy to follow. Chapter 3 contains some glitches that took me some time to understand but reading this chapter made everything really confusing. It took me a time to realise the Hello's, just my subject with only the focus clarifies already some impact. After re- and re-re reading it becomes clear to me what is meant. After re-reading the reason for using Hellos (as an Admin List) became clear and re-re- reading made the Admin single view/tmpl Hello obvious again. Why not rename these to:

* Manage_Hello_List
* Manage_Hello_Item

This would make everything much more readable, would set a clear context and increase the ease of understanding.<br>
--[[User:M.A.S.H|M.A.S.H]] 12:37, 3 August 2009 (UTC)

== Splitting up article into two articles ==

If the writers have no objection I propose to split this chapter into two. There are multiple good reasons for doing so but the most important three are the following:
*This chapter is huge making reading a tedious job, overwhelming and scaring away the once that this article is intended for.
*This article has two logical section so braking it at '''Adding Functionality''' doesn't harm any body and helps newbies in achieving results. Being able to check a chapter and visually see the intermediate result is always the best motivation.
*Technically the same split at '''Adding Functionality''' is making a difference in know-how. the first part is not really new when you followed the ''site'' part examples '''Developing a Model-View-Controller Component 1, 2 and 3'''. Old wine in new bottles. The second part really goes into depth and requires good basic programming skills and a general understanding of HTML form handling.
If no objections I will initiate this spilt soon.<br>
--[[User:M.A.S.H|M.A.S.H]] 07:34, 10 August 2009 (UTC)

I think splitting it is a good idea and should improve readability. I look forward to seeing your improvements. [[User:Chris Davenport|Chris Davenport]] 08:51, 10 August 2009 (UTC)

== Confusing ==

I agree Part 4 gets confusing. I see what it is attempting to demonstrate but it is confusing to jump into a completely new example rather than use an example from the onset that could cover the details of the controls in the Admin area.

Maybe choosing a slightly more complex example than 'Hello world!' from the beginning?

Will be good to see this article when it's been updated!

== Hint in 'Mapping' section ==

I'm removing the so-called hint from the section titled 'Mapping a Joomla! MVC component from the example.'

I've never seen the 'registered' method, and I think it's bogus.

Please respond if I'm wrong.

[[User:HobbesPDX|HobbesPDX]] 20:19, 6 March 2010 (UTC)

== Move 'sharing template parts' note to another article? ==

I'd like to suggest to the community, that the expansive note, in section 3.2.3, regarding sharing template/view elements, using include/require, should be moved to another article.

It's a very helpful point, but I feel it adds unnecessary and extra information to an already complex document.

Discuss. :-)

--[[User:HobbesPDX|HobbesPDX]] 21:00, 6 March 2010 (UTC)

J1.5:Developing a MVC Component/Creating an Administrator Interface

2010-03-06T20:30:08Z

HobbesPDX: clean-up, consistency

{{ambox
| type = notice
| image = notice
| text = This {{thingamabob}} has been divided into three sections, two new articles are added. Especially this page needs a review
<small>(August 2009)</small>}}
== Introduction ==

In the first three tutorials, we have developed a MVC component that retrieves its data from a table in the database. Currently, there is no way to add data to the database except to do it manually using another tool. In the next articles of this tutorial, we will develop an administrator section for our component which will make it possible to manage the entries in the database.

This article, [[Developing a Model-View-Controller Component - Part 4 - Creating an Administrator Interface | Part 4 - Creating an Administrator Interface]], will be an article with no new source code for our Hello component but will describe some basic details of the MVC pattern. In the frontend solution (site section) we developed the first part of our component. The frontend solution is based upon default Controllers, Views and Templates and you were "taken by the hand" and "left to trust" the default handling of the code. This is going to change in the Backend or Administration section of our Hello component - we will have to develop all of the code that manages the application flow.

== Site / Admin ==
Joomla! is a content management system. The '''frontend''' is used for presenting the users with content and allows certain logged in users to manipulate the content. The '''backend''' is responsible for administering the website framework (structuring / managing / controlling / maintaining). This division between (frontend) site-content and (backend) administration is a fundamental aspect of the Joomla! architecture.

=== Entrance points ===
From the XML file of our frontend example it was already obvious that there would be an administration part:
<source lang="xml"><?xml version="1.0" encoding="utf-8"?>
...
<administration>

<menu>Hello World!</menu>

<files folder="admin">
<filename>hello.php</filename>
<filename>index.html</filename>
<filename>install.sql</filename>
<filename>uninstall.sql</filename>
</files>
</administration>
...
</source>
Only the .sql files were of use and only during installation for our frontend view, the other two files have no content besides generating a blank page. Access your websites' file system at your hosting provider (or on your own server) and browse through the directories after installing the frontend com_hello component. You may have noticed that our Hello component is to be found twice:
<root>/components/com_hello
<root>/administrator/components/com_hello

These two sub-directories link to the previously explained site-content and administration. Administrator interactions explicitly go via the administrator sub-directory, where guest or registered users will enter the default entrance on the root:
<root>/index.php
Administrative users will have to log in, and after logging in they will enter your site via:
<root>/administrator/index.php

With the different access points it is easy to grasp that with setting up the administrator section the naming conventions have no dependency with the site section. Whilst the MVC pattern is also applicable for the administrator section this implies that identical Controls, Views and Models naming can (and sometimes must) be used as in the site section.

== MVC pattern interaction ==
[[image:MVC joomla.png|frameless|right]]In [[Developing a Model-View-Controller Component - Part 1]] the figure on the right was used to explain the focus of the first three parts of this ''Developing a Model-View-Controller Component tutorial''. Now we will use this figure to explain how decisions are made on what is going to be displayed and how to manipulate this.

=== Example roll-out ===
For explanation purposes an easy to grasp example will be used. A library has the main function of lending books to registered users. Simply laid out there are three tables:
* users
* books
* relation

Lets keep it all very simple. The users are addressed by Id and Name. The books are identified by Id and Title and the relation contains both Ids and the date of lending.

[[image:Library Example.png|400px|frameless|center]]

The example is carefully chosen and will help in explaining the Joomla! architecture in more detail. The administrative side of our Hello component is not even that complex with only one table to manage. After the explanation of this chapter it should be easy to follow the tutorial in the succeeding chapters

=== Mapping a Joomla! MVC component from the example ===
In this example we will assume that administrative actions (add, edit, delete) are tasks that are to be performed by the administrator. For the frontend user only the view of the Relation table is interesting ("when do I have to bring back the books?"). This example shows the entire list and ignores all privacy stuff that could be taken care of by letting registered users only see their own books.

Just like our frontend Hello component, for this library component only the default view is being used in the frontend. It lists the relational table, left joining the other two tables to obtain a human readable list of books with their corresponding due date.
Alice | One flew over ... | 12-aug-2009
Alice | Celeb talk | 12-aug-2009
Mark | Joomla! | 15-aug-2009

With respect to the administration part it is important to understand that we have one default and three dedicated views, each controlling three tasks:
* <Component name default view>
* User administration
** Add
** Change
** Delete
* Book administration
** Add
** Change
** Delete
* Relation administration
** Add
** Change
** Delete

==== Controllers ====
The main controller of the admin section needs to differentiate between the different Adds, Changes or Deletes that are requested. This is taken care of by creating sub-controllers for each view for handling their specific tasks.
<root>/administrator/controller.php
<root>/administrator/controllers/users.php
<root>/administrator/controllers/books.php
<root>/administrator/controllers/relation.php

The controller is an important part of the MVC pattern. Not only does it take care of the requested tasks, it is also the initiator of instantiating the model with the same name and it is responsible for setting the view and the desired form for that view. The controller really justifies its name.

Within the controller it is good to make a difference between '''activating tasks''' (for example the edit selection from a menu) and '''resulting tasks''' (for example the result of an edit trigger is the posted data).

Typical controller functions look like:
<source lang="php">
function <activating task>() // <-- edit, add, delete
{
JRequest::setVar( 'view', '[<componentname> | users | books | relation ]' );
JRequest::setVar( 'layout', 'default' ); // <-- The default form is named here, but in
// some complex views, multiple layouts might
// be needed.
parent::display();
}

function <resulting task>() // <-- save, remove
{
$model = $this->getModel('[<componentname> | users | books | relation ]');
if(!$model->action() ) { // <-- action could be delete() or store()
$msg = JText::_( 'Error: Could not perform action' );
} else {
$msg = JText::_( 'Action executed' );
}

$this->setRedirect( 'index.php?option=<componentname>', $msg );
}
</source>
A controller takes care of all tasks for that dedicated controller. After completing a resulting task the module will return to the main administration entrance point for that component, the main controller with the default view. Activating tasks enforce a new view with a form to display after first defining it.

The explicit definition of the form within a view might raise some eyebrows but our examples are too simple. For the general understanding and consistency this field should mostly be ''default''. In complex views multiple forms could be defined within one view.

==== Models ====
The Controllers interact with their equally named Model counter part. In the frontend view the Model was only used to retrieve data. The backend has more controllers and thus also more model files. The backend model files not only are responsible for delivering data to the viewer but also take care of tasks initiated from the controller. A good model contains all actions required to manage a single table in the database.
<root>/administrator/models/<componentname>.php
<root>/administrator/models/users.php
<root>/administrator/models/books.php
<root>/administrator/models/relation.php

==== Views ====
Separate views are of course also required. For views and subsequent forms no forced naming conventions are required (linking to views is taken care of in the controller). In the following listing the Administrative tasks are identified as a subset for the different views. This choice is totally random and maybe even non-logical but that doesn't matter for the explanation. Just for example purposes I added also a different view, a delete view, that could be used for all the deletes for all administrative tasks asking an "Are you sure" display.

<root>/administrator/views/<componentname>/view.html.php + .../tmpl/default.php
<root>/administrator/views/users/view.html.php + .../tmpl/default.php
<root>/administrator/views/books/view.html.php + .../tmpl/default.php
<root>/administrator/views/relation/view.html.php + .../tmpl/default.php
 
<root>/administrator/views/delete/view.html.php + .../tmpl/default.php

''Note'': In general it is good practice to maintain one form per view because the view.html.php still has to deliver the content. With some basic logic you can enable, disable certain content but if this logic is becoming too complex start considering splitting up the view.

''Note'': Sharing template parts amongst the different views (for uniform layouting of headers and titles of your component) can be done using the PHP <code>include / require;</code>. There is one slight problem ... how to make the logical reference? In my modules I have a collector bin for general to use sniplets. Because it involved the views and forms I put this general bin in the views directory. The variable $pathToGeneralView needs to be defined somewhere in the first lines of your file and you have to make sure that the logical reference path is correct (the '..'s). In the following example the files marked with a '*' use the following code:

./com_compname/views/general/navigate.header.php <-- sniplet code for the header
./com_compname/views/general/navigate.footer.php <-- sniplet code for the footer
./com_compname/views/mngtable1/view.html.php
./com_compname/views/mngtable1/tmpl/default.php *
./com_compname/views/mngtable2/view.html.php
./com_compname/views/mngtable2/tmpl/default.php *

<source lang=php>
$pathToGeneralView = strchr(dirname(__FILE__), dirname($_SERVER['SCRIPT_NAME']));
$pathToGeneralView = str_replace(dirname($_SERVER['SCRIPT_NAME']),'.',$pathToGeneralView );
$pathToGeneralView = $pathToGeneralView . "/../../general/"; <-- returning path from current position.
...
<?php require_once $pathToGeneralView . 'navigation.header.php'; ?>
<P>Do something
<?php require_once $pathToGeneralView . 'navigation.footer.php'; ?>
</source>
Another Way to do the same thing:
<source lang=php>
$pathToGeneralView = JPATH_COMPONENT_ADMINISTRATOR.DS. "views".DS."general".DS; <-- will return 'path/Joomla/administrator/components/com_example/views/general/
...
<?php require_once $pathToGeneralView . 'navigation.header.php'; ?>
<P>Do something
<?php require_once $pathToGeneralView . 'navigation.footer.php'; ?>
</source>

''Note'': Giving the forms logical instead of the ''default'' naming is of course handy when having a lot of different views. Having also that much ''default'' forms could make you easily loose oversight. On the other hand the view.html.php can not be renamed and you are always forced to look at the directory name for the view name you are working in.

=== Essential Interaction Parameters ===
Everything is in place:
* main and dedicated controllers;
* main and dedicated modules;
* different views and their forms.

Just one big question remains: '''How to use them'''!

Three parameters are mandatory for letting Joomla! do its job:
* option
* controller
* task

These three parameters are almost self explaining ;). The ''option'' part when developing a component is easy, always assign your component name to it. For component development consider this one as a constant, of course the Joomla! engine has more options than only components.

The ''controller'' and ''task'' parameters can be manipulated within your component anyway you want it to.

==== How it all works together ====
Looking at the simplified MVC picture Joomla! the logical flow of interaction goes the following way:
# What is my entrance point?
#*The Joomla! engine discovers a logged in administrator and sets the entrance point to <root>/administrator/index.php otherwise it wil go to the <root>/index.php entrance.
# What option is requested?
#*The Joomla! engine reads the option variable and discovers that a component named <componentname> is requested. The entrance point becomes: <root>/administrator/modules/com_<componentname>/<componentname>.php
# Is there need to access a dedicated controller?
#* The Joomla! engine reads the controller variable and discovers that a dedicated controller is required: <root>/administrator/modules/com_<componentname>/controllers/<dedicatedcontroller>.php
# Is there a task that needs to be addressed?
#* The identified controller is handed the task value as parameter.
# The Model is derived from the controller and instantiated.
# The View and Form are set in the controller and initiated to become active.

((Remark: the text states that the path is <root>/administrator/modules/com_<componentname>/<componentname>.php, but I am pretty sure that this is an error. It probably should say <root>/administrator/components/com_<componentname>/<componentname>.php. Can somebody please verify this and correct it?))

=== How to add interaction ===
Within HTML there are two common ways to interact with Joomla!:
# reference to a link
# form submission post / get

==== Link reference for the Joomla! engine ====
Remember the '''activating tasks''' and '''resulting tasks''' mentioned earlier? Most activating tasks are initiated by a link. In case of the Library example the site section overview could be copied to the admin section. This default view will now be extended and every cell will become a link for editing the specific database element.

Using the Library example, the template PHP code without looping control will contain the following code:
<source lang=php>
$link = JRoute::_( 'index.php?option=com_library&controller=users&task=edit&cid='. $row->idu );
echo "<td><a href=\"".$link."\">$row->name</a></td>";
$link = JRoute::_( 'index.php?option=com_library&controller=books&task=edit&cid='. $row->idb );
echo "<td><a href=\"".$link."\">$row->title</a></td>";
$link = JRoute::_( 'index.php?option=com_library&controller=relation&task=edit&cid='. $row->idr );
echo "<td><a href=\"".$link."\">$row->date</a></td>";
</source>

Within each clickable field the three mandatory parameters to manipulate MVC can be identified. In addition there is one user parameter for handling the correct index in the controller task (cid). These parameter are separated by '&'. Do not use spaces in your variables this might screw-up parameter handling in certain browsers. After looping all text entries will be clickable and trigger the corresponding controller with the correct row id in the associated table.

[Alice} | [One flew over ...] | [12 aug 2009]
[Alice] | [Celeb talk] | [12 aug 2009]
[Mark] | [Joomla!] | [15 aug 2009]

==== Posting Form Data to the Joomla! Engine ====
After being initiated by an activating task, an input form view might be the result. The sniplet code below could be the result of clicking the first cell of the default component view that is clicked for editing ([Alice]:cid=3).

<source lang="php">
<form action="index.php" method="post">
<input type="text" name="username" id="username" size="32" maxlength="250" value="<?php echo $this->user->name;?>" />

<input type="submit" name="SubmitButton" value="Save" />

<input type="hidden" name="option" value="com_library" /> // <-- mandatory
<input type="hidden" name="controller" value="hello" /> // <-- mandatory
<input type="hidden" name="task" value="save" /> // <-- mandatory
<input type="hidden" name="id" value="<?php echo $this->user->id; ?>" /> // <-- user parameter, index in database for [Alice]
</form>
</source>

The three Joomla! mandatory parameters are placed as hidden in the form. Hidden parameters are not shown in any way but will be added to the posting data.

''Tip'': when debugging this form, replace in the form tag <code>method="post"</code> temporarily with <code>method="get"</code>. All posted parameters will be shown in the URL of your browser. If the module is working undo this change. For one reason it looks sharper without all the parameters being shown in the URL and you avoid motivating people to manipulate the browser URL themselves. Of course one can look at the source code but using ''Post'' instead of ''Get'', but this eliminates the first 90% of the earth population. The other reason is more technical and the simple explanation is that post methods (i.e. method="post") can contain more (complex) data.

''Remark'': In some developed modules you may notice that developers have also added the ''view'' parameter. This is bad programming whilst the controller(s) should take care of the ''view'' and the ''form''.

== Conclusion ==

The use of the three mandatory parameters and the different access points are clarified. Let's do something with this knowledge and extend the Hello component to the administrative section in the succeeding articles of this tutorial.

== Articles in this Series ==
[[Developing a Model-View-Controller Component - Part 1]]

[[Developing a Model-View-Controller Component - Part 2 - Adding a Model]]

[[Developing a Model-View-Controller Component - Part 3 - Using the Database]]

[[Developing a Model-View-Controller Component - Part 4 - Creating an Administrator Interface]]

[[Developing a Model-View-Controller Component - Part 5 - Basic Backend Framework]]

[[Developing a Model-View-Controller Component - Part 6 - Adding Backend Actions]]

== Contributors ==
* staalanden
* jamesconroyuk

[[Category:Development]]

J1.5:Developing a MVC Component/Creating an Administrator Interface

2010-03-06T20:20:27Z

HobbesPDX: removed potentially bogus 'hint'

{{ambox
| type = notice
| image = notice
| text = This {{thingamabob}} has been divided into three sections, two new articles are added. Especially this page needs a review
<small>(August 2009)</small>}}
== Introduction ==

In the first three tutorials, we have developed a MVC component that retrieves its data from a table in the database. Currently, there is no way to add data to the database except to do it manually using another tool. In the next articles of this tutorial, we will develop an administrator section for our component which will make it possible to manage the entries in the database.

This article, [[Developing a Model-View-Controller Component - Part 4 - Creating an Administrator Interface | Part 4 - Creating an Administrator Interface]], will be an article with no new source code for our Hello component but will describe some basic details of the MVC pattern. In the frontend solution (site section) we developed the first part of our component. The frontend solution is based upon default Controllers, Views and Templates and you were "taken by the hand" and "left to trust" the default handling of the code. This is going to change in the Backend or Administration section of our Hello component - we will have to develop all of the code that manages the application flow.

== Site / Admin ==
Joomla! is a content management system. The '''frontend''' is used for presenting the users with content and allows certain logged in users to manipulate the content. The '''backend''' is responsible for administering the website framework (structuring / managing / controlling / maintaining). This division between (frontend) site-content and (backend) administration is a fundamental aspect of the Joomla! architecture.

=== Entrance points ===
From the XML file of our frontend example it was already obvious that there would be an administration part:
<source lang="xml"><?xml version="1.0" encoding="utf-8"?>
...
<administration>

<menu>Hello World!</menu>

<files folder="admin">
<filename>hello.php</filename>
<filename>index.html</filename>
<filename>install.sql</filename>
<filename>uninstall.sql</filename>
</files>
</administration>
...
</source>
Only the .sql files were of use and only during installation for our frontend view, the other two files have no content besides generating a blank page. Access your websites' file system at your hosting provider (or on your own server) and browse through the directories after installing the frontend com_hello component. You may have noticed that our Hello component is to be found twice:
<root>/components/com_hello
<root>/administrator/components/com_hello

These two sub-directories link to the previously explained site-content and administration. Administrator interactions explicitly go via the administrator sub-directory, where guest or registered users will enter the default entrance on the root:
<root>/index.php
Administrative users will have to log in, and after logging in they will enter your site via:
<root>/administrator/index.php

With the different access points it is easy to grasp that with setting up the administrator section the naming conventions have no dependency with the site section. Whilst the MVC pattern is also applicable for the administrator section this implies that identical Controls, Views and Models naming can (and sometimes must) be used as in the site section.

== MVC pattern interaction ==
[[image:MVC joomla.png|frameless|right]]In [[Developing a Model-View-Controller Component - Part 1]] the figure on the right was used to explain the focus of the first three parts of this ''Developing a Model-View-Controller Component tutorial''. Now we will use this figure to explain how decisions are made on what is going to be displayed and how to manipulate this.

=== Example roll-out ===
For explanation purposes an easy to grasp example will be used. A library has the main function of lending books to registered users. Simply laid out there are three tables:
* users
* books
* relation

Lets keep it all very simple. The users are addressed by Id and Name. The books are identified by Id and Title and the relation contains both Ids and the date of lending.

[[image:Library Example.png|400px|frameless|center]]

The example is carefully chosen and will help in explaining the Joomla! architecture in more detail. The administrative side of our Hello component is not even that complex with only one table to manage. After the explanation of this chapter it should be easy to follow the tutorial in the succeeding chapters

=== Mapping a Joomla! MVC component from the example ===
In this example we will assume that administrative actions (add, edit, delete) are tasks that are to be performed by the administrator. For the frontend user only the view of the Relation table is interesting ("when do I have to bring back the books?"). This example shows the entire list and ignores all privacy stuff that could be taken care of by letting registered users only see their own books.

Just like our frontend Hello component, for this library component only the default view is being used in the frontend. It lists the relational table, left joining the other two tables to obtain a human readable list of lend books.
Alice | One flew over ... | 12 aug 2009
Alice | Celeb talk | 12 aug 2009
Mark | Joomla! | 15 aug 2009

With respect to the administration part it is important to understand that we have one default and three dedicated views, each controlling three tasks:
* <Component name default view>
* User administration
** Add
** Change
** Delete
* Book administration
** Add
** Change
** Delete
* Relation administration
** Add
** Change
** Delete

==== Controllers ====
The main controller of the admin section needs to differentiate between the different Adds, Changes or Deletes that are requested. This is taken care of by creating sub-controllers for each view for handling their specific tasks.
<root>/administrator/controller.php
<root>/administrator/controllers/users.php
<root>/administrator/controllers/books.php
<root>/administrator/controllers/relation.php

The controller is an important part of the MVC pattern. Not only does it take care of the requested tasks, it is also the initiator of instantiating the model with the same name and it is responsible for setting the view and the desired form for that view. The controller really justifies its name.

Within the controller it is good to make a difference between '''activating tasks''' (for example the edit selection from a menu) and '''resulting tasks''' (for example the result of an edit trigger is the posted data).

Typical controller functions look like:
<source lang="php">
function <activating task>() // <-- edit, add, delete
{
JRequest::setVar( 'view', '[<componentname> | users | books | relation ]' );
JRequest::setVar( 'layout', 'default' ); // <-- The default form is named here but in complex
// views multiple layouts might be needed.
parent::display();
}

function <resulting task>() // <-- save, remove
{
$model = $this->getModel('[<componentname> | users | books | relation ]');
if(!$model->action() ) { // <-- action could be delete() or store()
$msg = JText::_( 'Error: Could not perform action' );
} else {
$msg = JText::_( 'Action executed' );
}

$this->setRedirect( 'index.php?option=<componentname>', $msg );
}
</source>
A controller takes care of all tasks for that dedicated controller. After completing a resulting task the module will return to the main administration entrance point for that component, the main controller with the default view. Activating tasks enforce a new view with a form to display after first defining it.

The explicit definition of the form within a view might raise some eyebrows but our examples are too simple. For the general understanding and consistency this field should mostly be ''default''. In complex views multiple forms could be defined within one view.

==== Models ====
The Controllers interact with their equally named Model counter part. In the frontend view the Model was only used to retrieve data. The backend has more controllers and thus also more model files. The backend model files not only are responsible for delivering data to the viewer but also take care of tasks initiated from the controller. A good model contains all actions required to manage a single table in the database.
<root>/administrator/models/<componentname>.php
<root>/administrator/models/users.php
<root>/administrator/models/books.php
<root>/administrator/models/relation.php

==== Views ====
Separate views are of course also required. For views and subsequent forms no forced naming conventions are required (linking to views is taken care of in the controller). In the following listing the Administrative tasks are identified as a subset for the different views. This choice is totally random and maybe even non-logical but that doesn't matter for the explanation. Just for example purposes I added also a different view, a delete view, that could be used for all the deletes for all administrative tasks asking an "Are you sure" display.

<root>/administrator/views/<componentname>/view.html.php + .../tmpl/default.php
<root>/administrator/views/users/view.html.php + .../tmpl/default.php
<root>/administrator/views/books/view.html.php + .../tmpl/default.php
<root>/administrator/views/relation/view.html.php + .../tmpl/default.php
 
<root>/administrator/views/delete/view.html.php + .../tmpl/default.php

''Note'': In general it is good practice to maintain one form per view because the view.html.php still has to deliver the content. With some basic logic you can enable, disable certain content but if this logic is becoming too complex start considering splitting up the view.

''Note'': Sharing template parts amongst the different views (for uniform layouting of headers and titles of your component) can be done using the PHP <code>include / require;</code>. There is one slight problem ... how to make the logical reference? In my modules I have a collector bin for general to use sniplets. Because it involved the views and forms I put this general bin in the views directory. The variable $pathToGeneralView needs to be defined somewhere in the first lines of your file and you have to make sure that the logical reference path is correct (the '..'s). In the following example the files marked with a '*' use the following code:

./com_compname/views/general/navigate.header.php <-- sniplet code for the header
./com_compname/views/general/navigate.footer.php <-- sniplet code for the footer
./com_compname/views/mngtable1/view.html.php
./com_compname/views/mngtable1/tmpl/default.php *
./com_compname/views/mngtable2/view.html.php
./com_compname/views/mngtable2/tmpl/default.php *

<source lang=php>
$pathToGeneralView = strchr(dirname(__FILE__), dirname($_SERVER['SCRIPT_NAME']));
$pathToGeneralView = str_replace(dirname($_SERVER['SCRIPT_NAME']),'.',$pathToGeneralView );
$pathToGeneralView = $pathToGeneralView . "/../../general/"; <-- returning path from current position.
...
<?php require_once $pathToGeneralView . 'navigation.header.php'; ?>
<P>Do something
<?php require_once $pathToGeneralView . 'navigation.footer.php'; ?>
</source>
Another Way to do the same thing:
<source lang=php>
$pathToGeneralView = JPATH_COMPONENT_ADMINISTRATOR.DS. "views".DS."general".DS; <-- will return 'path/Joomla/administrator/components/com_example/views/general/
...
<?php require_once $pathToGeneralView . 'navigation.header.php'; ?>
<P>Do something
<?php require_once $pathToGeneralView . 'navigation.footer.php'; ?>
</source>

''Note'': Giving the forms logical instead of the ''default'' naming is of course handy when having a lot of different views. Having also that much ''default'' forms could make you easily loose oversight. On the other hand the view.html.php can not be renamed and you are always forced to look at the directory name for the view name you are working in.

=== Essential Interaction Parameters ===
Everything is in place:
* main and dedicated controllers;
* main and dedicated modules;
* different views and their forms.

Just one big question remains: '''How to use them'''!

Three parameters are mandatory for letting Joomla! do its job:
* option
* controller
* task

These three parameters are almost self explaining ;). The ''option'' part when developing a component is easy, always assign your component name to it. For component development consider this one as a constant, of course the Joomla! engine has more options than only components.

The ''controller'' and ''task'' parameters can be manipulated within your component anyway you want it to.

==== How it all works together ====
Looking at the simplified MVC picture Joomla! the logical flow of interaction goes the following way:
# What is my entrance point?
#*The Joomla! engine discovers a logged in administrator and sets the entrance point to <root>/administrator/index.php otherwise it wil go to the <root>/index.php entrance.
# What option is requested?
#*The Joomla! engine reads the option variable and discovers that a component named <componentname> is requested. The entrance point becomes: <root>/administrator/modules/com_<componentname>/<componentname>.php
# Is there need to access a dedicated controller?
#* The Joomla! engine reads the controller variable and discovers that a dedicated controller is required: <root>/administrator/modules/com_<componentname>/controllers/<dedicatedcontroller>.php
# Is there a task that needs to be addressed?
#* The identified controller is handed the task value as parameter.
# The Model is derived from the controller and instantiated.
# The View and Form are set in the controller and initiated to become active.

((Remark: the text states that the path is <root>/administrator/modules/com_<componentname>/<componentname>.php, but I am pretty sure that this is an error. It probably should say <root>/administrator/components/com_<componentname>/<componentname>.php. Can somebody please verify this and correct it?))

=== How to add interaction ===
Within HTML there are two common ways to interact with Joomla!:
# reference to a link
# form submission post / get

==== Link reference for the Joomla! engine ====
Remember the '''activating tasks''' and '''resulting tasks''' mentioned earlier? Most activating tasks are initiated by a link. In case of the Library example the site section overview could be copied to the admin section. This default view will now be extended and every cell will become a link for editing the specific database element.

Using the Library example, the template PHP code without looping control will contain the following code:
<source lang=php>
$link = JRoute::_( 'index.php?option=com_library&controller=users&task=edit&cid='. $row->idu );
echo "<td><a href=\"".$link."\">$row->name</a></td>";
$link = JRoute::_( 'index.php?option=com_library&controller=books&task=edit&cid='. $row->idb );
echo "<td><a href=\"".$link."\">$row->title</a></td>";
$link = JRoute::_( 'index.php?option=com_library&controller=relation&task=edit&cid='. $row->idr );
echo "<td><a href=\"".$link."\">$row->date</a></td>";
</source>

Within each clickable field the three mandatory parameters to manipulate MVC can be identified. In addition there is one user parameter for handling the correct index in the controller task (cid). These parameter are separated by '&'. Do not use spaces in your variables this might screw-up parameter handling in certain browsers. After looping all text entries will be clickable and trigger the corresponding controller with the correct row id in the associated table.

[Alice} | [One flew over ...] | [12 aug 2009]
[Alice] | [Celeb talk] | [12 aug 2009]
[Mark] | [Joomla!] | [15 aug 2009]

==== Posting Form Data to the Joomla! Engine ====
After being initiated by an activating task, an input form view might be the result. The sniplet code below could be the result of clicking the first cell of the default component view that is clicked for editing ([Alice]:cid=3).

<source lang="php">
<form action="index.php" method="post">
<input type="text" name="username" id="username" size="32" maxlength="250" value="<?php echo $this->user->name;?>" />

<input type="submit" name="SubmitButton" value="Save" />

<input type="hidden" name="option" value="com_library" /> // <-- mandatory
<input type="hidden" name="controller" value="hello" /> // <-- mandatory
<input type="hidden" name="task" value="save" /> // <-- mandatory
<input type="hidden" name="id" value="<?php echo $this->user->id; ?>" /> // <-- user parameter, index in database for [Alice]
</form>
</source>

The three Joomla! mandatory parameters are placed as hidden in the form. Hidden parameters are not shown in any way but will be added to the posting data.

''Tip'': when debugging this form, replace in the form tag <code>method="post"</code> temporarily with <code>method="get"</code>. All posted parameters will be shown in the URL of your browser. If the module is working undo this change. For one reason it looks sharper without all the parameters being shown in the URL and you avoid motivating people to manipulate the browser URL themselves. Of course one can look at the source code but using ''Post'' instead of ''Get'', but this eliminates the first 90% of the earth population. The other reason is more technical and the simple explanation is that post methods (i.e. method="post") can contain more (complex) data.

''Remark'': In some developed modules you may notice that developers have also added the ''view'' parameter. This is bad programming whilst the controller(s) should take care of the ''view'' and the ''form''.

== Conclusion ==

The use of the three mandatory parameters and the different access points are clarified. Let's do something with this knowledge and extend the Hello component to the administrative section in the succeeding articles of this tutorial.

== Articles in this Series ==
[[Developing a Model-View-Controller Component - Part 1]]

[[Developing a Model-View-Controller Component - Part 2 - Adding a Model]]

[[Developing a Model-View-Controller Component - Part 3 - Using the Database]]

[[Developing a Model-View-Controller Component - Part 4 - Creating an Administrator Interface]]

[[Developing a Model-View-Controller Component - Part 5 - Basic Backend Framework]]

[[Developing a Model-View-Controller Component - Part 6 - Adding Backend Actions]]

== Contributors ==
* staalanden
* jamesconroyuk

[[Category:Development]]

J1.5 talk:Developing a MVC Component/Creating an Administrator Interface

2010-03-06T20:19:30Z

HobbesPDX: /* Hint in 'Mapping' section */

== Renaming Part 4 ==
I checked out the comment below. ;-) Certainly, the multitude of hello(s) is confusing. What I did is to rename most everything.

Whenever there's something like HelloWhateverHello, the first Hello represents the component front-end, and the second represents the view/model. By the way, each view has its own model, which I think is pretty much standard MVC architecture. On the other hand, one controller can control several views, although this example doesn't do so.

Conversely, if you see HellosWhateverHello or HellosWhateverHellos, the first Hellos represents the adminstrative back-end, and the Hello or Hellos at the end refers to the view for editing one greeting or for listing all greetings, respectively. (Replace *Whatever* with Model, View, or Controller as appropriate.)

So, I renamed all this to look like FrontWhateverContent, AdminWhateverEdit, AdminWhateverList, and so on. Then I had to rename directories and files as well, so that models/hello.php became models/content.php in the front-end and models/edit.php in the back-end. Likewise, views/hello/ becomes views/content/ in the front-end and views/edit in the back-end. Also, in the back-end only, models/hellos.php & views/hellos/ become models/list.php & views/list. Lastly, I changed controllers/hello.php to controllers/edit.php, to reflect the change from HellosControllerHello to AdminControllerEdit.

Hope this clears things up a bit. It's a tedious refactoring exercise to do all this renaming, but it *is* doable. Good luck.

== "Hello" Overloaded ==

I'm not sure if anybody checks this, but I'm having a difficult time making my own component out of this document.

The first three chapters of this documentation are great. They are simple and to the point. The fourth, this page, is very confusing.

First off, the word "hello" is way over loaded. In the Creating an Admin Interface there are two models and two views:
Hello and Hellos

It's impossible to know why we need two different models. Why cant we use one model and two views?
Its totally impossible to understand which one gets called when.

I have discovered there are a lot of name conventions used here, but after reading this document over and over, it's still very difficult to know what the conventions are. This is probably stemming from "hello" being way too overloaded.

The method "get()" in JView is called in both views. It is supposed to automatically know which model to use, and which method to call. However, I don't think I followed the naming convention correctly, as it simply is not working (I get empty data with no error).

I think I could untangle the naming conventions myself, but with "hello" so overloaded in this example, I am having no luck guessing.

== Great up to chapter 3 ==

The documentation was great upto chapter 3. Got confused in 4th chapter.

Also, this doesn't cover how to create sub menus for a component [http://www.vojtechovsky.net/joomla/component/tutorial-joomla-1.5-free-component.png See example]

== Suggestions for improvement ==

*This is a really long and tedious tutorial with a lot of very useful information in it. I think it would help to break it down into parts or creating separate tutorials covering this material.
[[Link title]]

== REALLY GOOD DOCUMENTATION ==

Apart from a small error in part 4 which I have now corrected

did read:

$row =& $this->items[$i];
$checked = JHTML::_( 'grid.id', $i, $row->id );
$link = JRoute::_( 'index.php?option=com_hello>controller=hello>task=edit>cid[]='. $row->id );

now reads:

$row =& $this->items[$i];
$checked = JHTML::_( 'grid.id', $i, $row->id );
$link = JRoute::_( 'index.php?option=com_hello&controller=hello&task=edit&cid[]='. $row->id );

[[User:Jamesconroyuk|James Conroy]] 16:29, 16 February 2009 (UTC)

== Excellent documentation, but could use a slight extension ==

Have been able to create components using this set of tutorials, but am missing how to use non-string based data in the administrator interface.

The admin form only has one field (a string) and it might be useful to have either examples of, or a link to some other examples of how to view / capture other types of data such as :

Checkboxes (boolean)
Dropdown menus / radio button (int or string)

While it is easy to add the HTML form components (and even populate them with the values from the model), it isn't immediately clear how to recapture the data of these alternative types.

There is another tutorial I have seen on this wiki that has the "build in a rich editor" function, could use a link from this page.

[[User:craigmoore|Craig Moore]] 13:06, 09 May 2009 (UTC)

== Really a great tutorial ... but too many hello.php's ==

First of all, great tutorial, a very good effort to explain the basics.

Maybe just my problem:
I personally prefer to edit several files at a time, what means, i have 10-20 tabs open in my editor (UltraEdit).
In my case that means, that my editor tab-bar looks like:

hello.php - controller.php - hello.php - hello.php - hello.php - controller.php - hellos.php - and so on ...

I would kiss the shoes of everyone who would:

1.) precisely explain naming conventions for files of components (which file may, which file must be called hello.php)

2.) resolve the hello.php-maze in this tutorial with more speaking filenames

Thanks to the authors, best regards and a hello to everyone

Jochen

== Good Tutorial ==

Suggestion for improvement.

I also found Part 4 hard to follow and lacking explanation of why various names/paths/parameters were chosen. For a beginner trying to understand Joomla! MVC conventions I found another component backend howto that gave more of the details I was looking for: [http://www.scribd.com/doc/11515210/Joomla-Component-Development-Backend]

Hope this helps someone else.
-Mike
[[User:M3t00|M3t00]] 15:55, 10 June 2009 (UTC)

== RE: Renaming Part 4 ==

I'm actually even more confused now.

Only by reading through this discussion did it occur to me that you need to use multiple views to handle the various tasks in the controller. That seems like an important concept that is not entirely obvious to someone trying to learn the joomla framework. And yet now that I recognize the concept, it's not obvious what the best practices would be to implement multiple views. I'll work on it.

Despite that, this is still an extremely valuable tutorial -- especially considering that much of the rest of the API documentation is sparse at best. The entire joomla documentation in general could definitely benefit from a bit of a re-org.

EDIT: OK. So after reading through part 4 of the tutorial again, it is clear to me about the multiple views. So, looking back, it would have been valuable to explain that in the introduction. Something like:

"Now we will create an administrator section to create the greetings. It uses 2 views. The first view, called Hellos, will present a list of greetings with the ability to add new ones or remove old ones. The second view will allow the user to edit each greeting."

That would have helped tremendously. In any case, I got it now. I feel a little stupid for missing that the first time around, but maybe it was because it was late at night.

== Component Hello, Site Hello, Admin Hellos, Admin Hello ==

Chapters 1 and 2 were easy to follow. Chapter 3 contains some glitches that took me some time to understand but reading this chapter made everything really confusing. It took me a time to realise the Hello's, just my subject with only the focus clarifies already some impact. After re- and re-re reading it becomes clear to me what is meant. After re-reading the reason for using Hellos (as an Admin List) became clear and re-re- reading made the Admin single view/tmpl Hello obvious again. Why not rename these to:

* Manage_Hello_List
* Manage_Hello_Item

This would make everything much more readable, would set a clear context and increase the ease of understanding.<br>
--[[User:M.A.S.H|M.A.S.H]] 12:37, 3 August 2009 (UTC)

== Splitting up article into two articles ==

If the writers have no objection I propose to split this chapter into two. There are multiple good reasons for doing so but the most important three are the following:
*This chapter is huge making reading a tedious job, overwhelming and scaring away the once that this article is intended for.
*This article has two logical section so braking it at '''Adding Functionality''' doesn't harm any body and helps newbies in achieving results. Being able to check a chapter and visually see the intermediate result is always the best motivation.
*Technically the same split at '''Adding Functionality''' is making a difference in know-how. the first part is not really new when you followed the ''site'' part examples '''Developing a Model-View-Controller Component 1, 2 and 3'''. Old wine in new bottles. The second part really goes into depth and requires good basic programming skills and a general understanding of HTML form handling.
If no objections I will initiate this spilt soon.<br>
--[[User:M.A.S.H|M.A.S.H]] 07:34, 10 August 2009 (UTC)

I think splitting it is a good idea and should improve readability. I look forward to seeing your improvements. [[User:Chris Davenport|Chris Davenport]] 08:51, 10 August 2009 (UTC)

== Confusing ==

I agree Part 4 gets confusing. I see what it is attempting to demonstrate but it is confusing to jump into a completely new example rather than use an example from the onset that could cover the details of the controls in the Admin area.

Maybe choosing a slightly more complex example than 'Hello world!' from the beginning?

Will be good to see this article when it's been updated!

== Hint in 'Mapping' section ==

I'm removing the so-called hint from the section titled 'Mapping a Joomla! MVC component from the example.'

I've never seen the 'registered' method, and I think it's bogus.

Please respond if I'm wrong.

[[User:HobbesPDX|HobbesPDX]] 20:19, 6 March 2010 (UTC)

J1.5 talk:Developing a MVC Component/Creating an Administrator Interface

2010-03-06T20:19:14Z

HobbesPDX: /* Hint in 'Mapping' section */ new section

== Renaming Part 4 ==
I checked out the comment below. ;-) Certainly, the multitude of hello(s) is confusing. What I did is to rename most everything.

Whenever there's something like HelloWhateverHello, the first Hello represents the component front-end, and the second represents the view/model. By the way, each view has its own model, which I think is pretty much standard MVC architecture. On the other hand, one controller can control several views, although this example doesn't do so.

Conversely, if you see HellosWhateverHello or HellosWhateverHellos, the first Hellos represents the adminstrative back-end, and the Hello or Hellos at the end refers to the view for editing one greeting or for listing all greetings, respectively. (Replace *Whatever* with Model, View, or Controller as appropriate.)

So, I renamed all this to look like FrontWhateverContent, AdminWhateverEdit, AdminWhateverList, and so on. Then I had to rename directories and files as well, so that models/hello.php became models/content.php in the front-end and models/edit.php in the back-end. Likewise, views/hello/ becomes views/content/ in the front-end and views/edit in the back-end. Also, in the back-end only, models/hellos.php & views/hellos/ become models/list.php & views/list. Lastly, I changed controllers/hello.php to controllers/edit.php, to reflect the change from HellosControllerHello to AdminControllerEdit.

Hope this clears things up a bit. It's a tedious refactoring exercise to do all this renaming, but it *is* doable. Good luck.

== "Hello" Overloaded ==

I'm not sure if anybody checks this, but I'm having a difficult time making my own component out of this document.

The first three chapters of this documentation are great. They are simple and to the point. The fourth, this page, is very confusing.

First off, the word "hello" is way over loaded. In the Creating an Admin Interface there are two models and two views:
Hello and Hellos

It's impossible to know why we need two different models. Why cant we use one model and two views?
Its totally impossible to understand which one gets called when.

I have discovered there are a lot of name conventions used here, but after reading this document over and over, it's still very difficult to know what the conventions are. This is probably stemming from "hello" being way too overloaded.

The method "get()" in JView is called in both views. It is supposed to automatically know which model to use, and which method to call. However, I don't think I followed the naming convention correctly, as it simply is not working (I get empty data with no error).

I think I could untangle the naming conventions myself, but with "hello" so overloaded in this example, I am having no luck guessing.

== Great up to chapter 3 ==

The documentation was great upto chapter 3. Got confused in 4th chapter.

Also, this doesn't cover how to create sub menus for a component [http://www.vojtechovsky.net/joomla/component/tutorial-joomla-1.5-free-component.png See example]

== Suggestions for improvement ==

*This is a really long and tedious tutorial with a lot of very useful information in it. I think it would help to break it down into parts or creating separate tutorials covering this material.
[[Link title]]

== REALLY GOOD DOCUMENTATION ==

Apart from a small error in part 4 which I have now corrected

did read:

$row =& $this->items[$i];
$checked = JHTML::_( 'grid.id', $i, $row->id );
$link = JRoute::_( 'index.php?option=com_hello>controller=hello>task=edit>cid[]='. $row->id );

now reads:

$row =& $this->items[$i];
$checked = JHTML::_( 'grid.id', $i, $row->id );
$link = JRoute::_( 'index.php?option=com_hello&controller=hello&task=edit&cid[]='. $row->id );

[[User:Jamesconroyuk|James Conroy]] 16:29, 16 February 2009 (UTC)

== Excellent documentation, but could use a slight extension ==

Have been able to create components using this set of tutorials, but am missing how to use non-string based data in the administrator interface.

The admin form only has one field (a string) and it might be useful to have either examples of, or a link to some other examples of how to view / capture other types of data such as :

Checkboxes (boolean)
Dropdown menus / radio button (int or string)

While it is easy to add the HTML form components (and even populate them with the values from the model), it isn't immediately clear how to recapture the data of these alternative types.

There is another tutorial I have seen on this wiki that has the "build in a rich editor" function, could use a link from this page.

[[User:craigmoore|Craig Moore]] 13:06, 09 May 2009 (UTC)

== Really a great tutorial ... but too many hello.php's ==

First of all, great tutorial, a very good effort to explain the basics.

Maybe just my problem:
I personally prefer to edit several files at a time, what means, i have 10-20 tabs open in my editor (UltraEdit).
In my case that means, that my editor tab-bar looks like:

hello.php - controller.php - hello.php - hello.php - hello.php - controller.php - hellos.php - and so on ...

I would kiss the shoes of everyone who would:

1.) precisely explain naming conventions for files of components (which file may, which file must be called hello.php)

2.) resolve the hello.php-maze in this tutorial with more speaking filenames

Thanks to the authors, best regards and a hello to everyone

Jochen

== Good Tutorial ==

Suggestion for improvement.

I also found Part 4 hard to follow and lacking explanation of why various names/paths/parameters were chosen. For a beginner trying to understand Joomla! MVC conventions I found another component backend howto that gave more of the details I was looking for: [http://www.scribd.com/doc/11515210/Joomla-Component-Development-Backend]

Hope this helps someone else.
-Mike
[[User:M3t00|M3t00]] 15:55, 10 June 2009 (UTC)

== RE: Renaming Part 4 ==

I'm actually even more confused now.

Only by reading through this discussion did it occur to me that you need to use multiple views to handle the various tasks in the controller. That seems like an important concept that is not entirely obvious to someone trying to learn the joomla framework. And yet now that I recognize the concept, it's not obvious what the best practices would be to implement multiple views. I'll work on it.

Despite that, this is still an extremely valuable tutorial -- especially considering that much of the rest of the API documentation is sparse at best. The entire joomla documentation in general could definitely benefit from a bit of a re-org.

EDIT: OK. So after reading through part 4 of the tutorial again, it is clear to me about the multiple views. So, looking back, it would have been valuable to explain that in the introduction. Something like:

"Now we will create an administrator section to create the greetings. It uses 2 views. The first view, called Hellos, will present a list of greetings with the ability to add new ones or remove old ones. The second view will allow the user to edit each greeting."

That would have helped tremendously. In any case, I got it now. I feel a little stupid for missing that the first time around, but maybe it was because it was late at night.

== Component Hello, Site Hello, Admin Hellos, Admin Hello ==

Chapters 1 and 2 were easy to follow. Chapter 3 contains some glitches that took me some time to understand but reading this chapter made everything really confusing. It took me a time to realise the Hello's, just my subject with only the focus clarifies already some impact. After re- and re-re reading it becomes clear to me what is meant. After re-reading the reason for using Hellos (as an Admin List) became clear and re-re- reading made the Admin single view/tmpl Hello obvious again. Why not rename these to:

* Manage_Hello_List
* Manage_Hello_Item

This would make everything much more readable, would set a clear context and increase the ease of understanding.<br>
--[[User:M.A.S.H|M.A.S.H]] 12:37, 3 August 2009 (UTC)

== Splitting up article into two articles ==

If the writers have no objection I propose to split this chapter into two. There are multiple good reasons for doing so but the most important three are the following:
*This chapter is huge making reading a tedious job, overwhelming and scaring away the once that this article is intended for.
*This article has two logical section so braking it at '''Adding Functionality''' doesn't harm any body and helps newbies in achieving results. Being able to check a chapter and visually see the intermediate result is always the best motivation.
*Technically the same split at '''Adding Functionality''' is making a difference in know-how. the first part is not really new when you followed the ''site'' part examples '''Developing a Model-View-Controller Component 1, 2 and 3'''. Old wine in new bottles. The second part really goes into depth and requires good basic programming skills and a general understanding of HTML form handling.
If no objections I will initiate this spilt soon.<br>
--[[User:M.A.S.H|M.A.S.H]] 07:34, 10 August 2009 (UTC)

I think splitting it is a good idea and should improve readability. I look forward to seeing your improvements. [[User:Chris Davenport|Chris Davenport]] 08:51, 10 August 2009 (UTC)

== Confusing ==

I agree Part 4 gets confusing. I see what it is attempting to demonstrate but it is confusing to jump into a completely new example rather than use an example from the onset that could cover the details of the controls in the Admin area.

Maybe choosing a slightly more complex example than 'Hello world!' from the beginning?

Will be good to see this article when it's been updated!

== Hint in 'Mapping' section ==

I'm removing the so-called hint from the section titled 'Mapping a Joomla! MVC component from the example.'

I've never seen the 'registered' method, and I think it's bogus.

Please respond if I'm wrong.
[[User:HobbesPDX|HobbesPDX]] 20:19, 6 March 2010 (UTC)

J1.5:Developing a MVC Component/Creating an Administrator Interface

2010-03-06T20:16:44Z

HobbesPDX:

{{ambox
| type = notice
| image = notice
| text = This {{thingamabob}} has been divided into three sections, two new articles are added. Especially this page needs a review
<small>(August 2009)</small>}}
== Introduction ==

In the first three tutorials, we have developed a MVC component that retrieves its data from a table in the database. Currently, there is no way to add data to the database except to do it manually using another tool. In the next articles of this tutorial, we will develop an administrator section for our component which will make it possible to manage the entries in the database.

This article, [[Developing a Model-View-Controller Component - Part 4 - Creating an Administrator Interface | Part 4 - Creating an Administrator Interface]], will be an article with no new source code for our Hello component but will describe some basic details of the MVC pattern. In the frontend solution (site section) we developed the first part of our component. The frontend solution is based upon default Controllers, Views and Templates and you were "taken by the hand" and "left to trust" the default handling of the code. This is going to change in the Backend or Administration section of our Hello component - we will have to develop all of the code that manages the application flow.

== Site / Admin ==
Joomla! is a content management system. The '''frontend''' is used for presenting the users with content and allows certain logged in users to manipulate the content. The '''backend''' is responsible for administering the website framework (structuring / managing / controlling / maintaining). This division between (frontend) site-content and (backend) administration is a fundamental aspect of the Joomla! architecture.

=== Entrance points ===
From the XML file of our frontend example it was already obvious that there would be an administration part:
<source lang="xml"><?xml version="1.0" encoding="utf-8"?>
...
<administration>

<menu>Hello World!</menu>

<files folder="admin">
<filename>hello.php</filename>
<filename>index.html</filename>
<filename>install.sql</filename>
<filename>uninstall.sql</filename>
</files>
</administration>
...
</source>
Only the .sql files were of use and only during installation for our frontend view, the other two files have no content besides generating a blank page. Access your websites' file system at your hosting provider (or on your own server) and browse through the directories after installing the frontend com_hello component. You may have noticed that our Hello component is to be found twice:
<root>/components/com_hello
<root>/administrator/components/com_hello

These two sub-directories link to the previously explained site-content and administration. Administrator interactions explicitly go via the administrator sub-directory, where guest or registered users will enter the default entrance on the root:
<root>/index.php
Administrative users will have to log in, and after logging in they will enter your site via:
<root>/administrator/index.php

With the different access points it is easy to grasp that with setting up the administrator section the naming conventions have no dependency with the site section. Whilst the MVC pattern is also applicable for the administrator section this implies that identical Controls, Views and Models naming can (and sometimes must) be used as in the site section.

== MVC pattern interaction ==
[[image:MVC joomla.png|frameless|right]]In [[Developing a Model-View-Controller Component - Part 1]] the figure on the right was used to explain the focus of the first three parts of this ''Developing a Model-View-Controller Component tutorial''. Now we will use this figure to explain how decisions are made on what is going to be displayed and how to manipulate this.

=== Example roll-out ===
For explanation purposes an easy to grasp example will be used. A library has the main function of lending books to registered users. Simply laid out there are three tables:
* users
* books
* relation

Lets keep it all very simple. The users are addressed by Id and Name. The books are identified by Id and Title and the relation contains both Ids and the date of lending.

[[image:Library Example.png|400px|frameless|center]]

The example is carefully chosen and will help in explaining the Joomla! architecture in more detail. The administrative side of our Hello component is not even that complex with only one table to manage. After the explanation of this chapter it should be easy to follow the tutorial in the succeeding chapters

=== Mapping a Joomla! MVC component from the example ===
In this example we will assume that administrative actions (add, edit, delete) are tasks that are to be performed by the administrator. For the frontend user only the view of the Relation table is interesting ("when do I have to bring back the books?"). This example shows the entire list and ignores all privacy stuff that could be taken care of by letting registered users only see their own books (''Hint'': <code>if ($user->registered) {}</code> ).

Just like our frontend Hello component, for this library component only the default view is being used in the frontend. It lists the relational table, left joining the other two tables to obtain a human readable list of lend books.
Alice | One flew over ... | 12 aug 2009
Alice | Celeb talk | 12 aug 2009
Mark | Joomla! | 15 aug 2009

With respect to the administration part it is important to understand that we have one default and three dedicated views, each controlling three tasks:
* <Component name default view>
* User administration
** Add
** Change
** Delete
* Book administration
** Add
** Change
** Delete
* Relation administration
** Add
** Change
** Delete

==== Controllers ====
The main controller of the admin section needs to differentiate between the different Adds, Changes or Deletes that are requested. This is taken care of by creating sub-controllers for each view for handling their specific tasks.
<root>/administrator/controller.php
<root>/administrator/controllers/users.php
<root>/administrator/controllers/books.php
<root>/administrator/controllers/relation.php

The controller is an important part of the MVC pattern. Not only does it take care of the requested tasks, it is also the initiator of instantiating the model with the same name and it is responsible for setting the view and the desired form for that view. The controller really justifies its name.

Within the controller it is good to make a difference between '''activating tasks''' (for example the edit selection from a menu) and '''resulting tasks''' (for example the result of an edit trigger is the posted data).

Typical controller functions look like:
<source lang="php">
function <activating task>() // <-- edit, add, delete
{
JRequest::setVar( 'view', '[<componentname> | users | books | relation ]' );
JRequest::setVar( 'layout', 'default' ); // <-- The default form is named here but in complex
// views multiple layouts might be needed.
parent::display();
}

function <resulting task>() // <-- save, remove
{
$model = $this->getModel('[<componentname> | users | books | relation ]');
if(!$model->action() ) { // <-- action could be delete() or store()
$msg = JText::_( 'Error: Could not perform action' );
} else {
$msg = JText::_( 'Action executed' );
}

$this->setRedirect( 'index.php?option=<componentname>', $msg );
}
</source>
A controller takes care of all tasks for that dedicated controller. After completing a resulting task the module will return to the main administration entrance point for that component, the main controller with the default view. Activating tasks enforce a new view with a form to display after first defining it.

The explicit definition of the form within a view might raise some eyebrows but our examples are too simple. For the general understanding and consistency this field should mostly be ''default''. In complex views multiple forms could be defined within one view.

==== Models ====
The Controllers interact with their equally named Model counter part. In the frontend view the Model was only used to retrieve data. The backend has more controllers and thus also more model files. The backend model files not only are responsible for delivering data to the viewer but also take care of tasks initiated from the controller. A good model contains all actions required to manage a single table in the database.
<root>/administrator/models/<componentname>.php
<root>/administrator/models/users.php
<root>/administrator/models/books.php
<root>/administrator/models/relation.php

==== Views ====
Separate views are of course also required. For views and subsequent forms no forced naming conventions are required (linking to views is taken care of in the controller). In the following listing the Administrative tasks are identified as a subset for the different views. This choice is totally random and maybe even non-logical but that doesn't matter for the explanation. Just for example purposes I added also a different view, a delete view, that could be used for all the deletes for all administrative tasks asking an "Are you sure" display.

<root>/administrator/views/<componentname>/view.html.php + .../tmpl/default.php
<root>/administrator/views/users/view.html.php + .../tmpl/default.php
<root>/administrator/views/books/view.html.php + .../tmpl/default.php
<root>/administrator/views/relation/view.html.php + .../tmpl/default.php
 
<root>/administrator/views/delete/view.html.php + .../tmpl/default.php

''Note'': In general it is good practice to maintain one form per view because the view.html.php still has to deliver the content. With some basic logic you can enable, disable certain content but if this logic is becoming too complex start considering splitting up the view.

''Note'': Sharing template parts amongst the different views (for uniform layouting of headers and titles of your component) can be done using the PHP <code>include / require;</code>. There is one slight problem ... how to make the logical reference? In my modules I have a collector bin for general to use sniplets. Because it involved the views and forms I put this general bin in the views directory. The variable $pathToGeneralView needs to be defined somewhere in the first lines of your file and you have to make sure that the logical reference path is correct (the '..'s). In the following example the files marked with a '*' use the following code:

./com_compname/views/general/navigate.header.php <-- sniplet code for the header
./com_compname/views/general/navigate.footer.php <-- sniplet code for the footer
./com_compname/views/mngtable1/view.html.php
./com_compname/views/mngtable1/tmpl/default.php *
./com_compname/views/mngtable2/view.html.php
./com_compname/views/mngtable2/tmpl/default.php *

<source lang=php>
$pathToGeneralView = strchr(dirname(__FILE__), dirname($_SERVER['SCRIPT_NAME']));
$pathToGeneralView = str_replace(dirname($_SERVER['SCRIPT_NAME']),'.',$pathToGeneralView );
$pathToGeneralView = $pathToGeneralView . "/../../general/"; <-- returning path from current position.
...
<?php require_once $pathToGeneralView . 'navigation.header.php'; ?>
<P>Do something
<?php require_once $pathToGeneralView . 'navigation.footer.php'; ?>
</source>
Another Way to do the same thing:
<source lang=php>
$pathToGeneralView = JPATH_COMPONENT_ADMINISTRATOR.DS. "views".DS."general".DS; <-- will return 'path/Joomla/administrator/components/com_example/views/general/
...
<?php require_once $pathToGeneralView . 'navigation.header.php'; ?>
<P>Do something
<?php require_once $pathToGeneralView . 'navigation.footer.php'; ?>
</source>

''Note'': Giving the forms logical instead of the ''default'' naming is of course handy when having a lot of different views. Having also that much ''default'' forms could make you easily loose oversight. On the other hand the view.html.php can not be renamed and you are always forced to look at the directory name for the view name you are working in.

=== Essential Interaction Parameters ===
Everything is in place:
* main and dedicated controllers;
* main and dedicated modules;
* different views and their forms.

Just one big question remains: '''How to use them'''!

Three parameters are mandatory for letting Joomla! do its job:
* option
* controller
* task

These three parameters are almost self explaining ;). The ''option'' part when developing a component is easy, always assign your component name to it. For component development consider this one as a constant, of course the Joomla! engine has more options than only components.

The ''controller'' and ''task'' parameters can be manipulated within your component anyway you want it to.

==== How it all works together ====
Looking at the simplified MVC picture Joomla! the logical flow of interaction goes the following way:
# What is my entrance point?
#*The Joomla! engine discovers a logged in administrator and sets the entrance point to <root>/administrator/index.php otherwise it wil go to the <root>/index.php entrance.
# What option is requested?
#*The Joomla! engine reads the option variable and discovers that a component named <componentname> is requested. The entrance point becomes: <root>/administrator/modules/com_<componentname>/<componentname>.php
# Is there need to access a dedicated controller?
#* The Joomla! engine reads the controller variable and discovers that a dedicated controller is required: <root>/administrator/modules/com_<componentname>/controllers/<dedicatedcontroller>.php
# Is there a task that needs to be addressed?
#* The identified controller is handed the task value as parameter.
# The Model is derived from the controller and instantiated.
# The View and Form are set in the controller and initiated to become active.

((Remark: the text states that the path is <root>/administrator/modules/com_<componentname>/<componentname>.php, but I am pretty sure that this is an error. It probably should say <root>/administrator/components/com_<componentname>/<componentname>.php. Can somebody please verify this and correct it?))

=== How to add interaction ===
Within HTML there are two common ways to interact with Joomla!:
# reference to a link
# form submission post / get

==== Link reference for the Joomla! engine ====
Remember the '''activating tasks''' and '''resulting tasks''' mentioned earlier? Most activating tasks are initiated by a link. In case of the Library example the site section overview could be copied to the admin section. This default view will now be extended and every cell will become a link for editing the specific database element.

Using the Library example, the template PHP code without looping control will contain the following code:
<source lang=php>
$link = JRoute::_( 'index.php?option=com_library&controller=users&task=edit&cid='. $row->idu );
echo "<td><a href=\"".$link."\">$row->name</a></td>";
$link = JRoute::_( 'index.php?option=com_library&controller=books&task=edit&cid='. $row->idb );
echo "<td><a href=\"".$link."\">$row->title</a></td>";
$link = JRoute::_( 'index.php?option=com_library&controller=relation&task=edit&cid='. $row->idr );
echo "<td><a href=\"".$link."\">$row->date</a></td>";
</source>

Within each clickable field the three mandatory parameters to manipulate MVC can be identified. In addition there is one user parameter for handling the correct index in the controller task (cid). These parameter are separated by '&'. Do not use spaces in your variables this might screw-up parameter handling in certain browsers. After looping all text entries will be clickable and trigger the corresponding controller with the correct row id in the associated table.

[Alice} | [One flew over ...] | [12 aug 2009]
[Alice] | [Celeb talk] | [12 aug 2009]
[Mark] | [Joomla!] | [15 aug 2009]

==== Posting Form Data to the Joomla! Engine ====
After being initiated by an activating task, an input form view might be the result. The sniplet code below could be the result of clicking the first cell of the default component view that is clicked for editing ([Alice]:cid=3).

<source lang="php">
<form action="index.php" method="post">
<input type="text" name="username" id="username" size="32" maxlength="250" value="<?php echo $this->user->name;?>" />

<input type="submit" name="SubmitButton" value="Save" />

<input type="hidden" name="option" value="com_library" /> // <-- mandatory
<input type="hidden" name="controller" value="hello" /> // <-- mandatory
<input type="hidden" name="task" value="save" /> // <-- mandatory
<input type="hidden" name="id" value="<?php echo $this->user->id; ?>" /> // <-- user parameter, index in database for [Alice]
</form>
</source>

The three Joomla! mandatory parameters are placed as hidden in the form. Hidden parameters are not shown in any way but will be added to the posting data.

''Tip'': when debugging this form, replace in the form tag <code>method="post"</code> temporarily with <code>method="get"</code>. All posted parameters will be shown in the URL of your browser. If the module is working undo this change. For one reason it looks sharper without all the parameters being shown in the URL and you avoid motivating people to manipulate the browser URL themselves. Of course one can look at the source code but using ''Post'' instead of ''Get'', but this eliminates the first 90% of the earth population. The other reason is more technical and the simple explanation is that post methods (i.e. method="post") can contain more (complex) data.

''Remark'': In some developed modules you may notice that developers have also added the ''view'' parameter. This is bad programming whilst the controller(s) should take care of the ''view'' and the ''form''.

== Conclusion ==

The use of the three mandatory parameters and the different access points are clarified. Let's do something with this knowledge and extend the Hello component to the administrative section in the succeeding articles of this tutorial.

== Articles in this Series ==
[[Developing a Model-View-Controller Component - Part 1]]

[[Developing a Model-View-Controller Component - Part 2 - Adding a Model]]

[[Developing a Model-View-Controller Component - Part 3 - Using the Database]]

[[Developing a Model-View-Controller Component - Part 4 - Creating an Administrator Interface]]

[[Developing a Model-View-Controller Component - Part 5 - Basic Backend Framework]]

[[Developing a Model-View-Controller Component - Part 6 - Adding Backend Actions]]

== Contributors ==
* staalanden
* jamesconroyuk

[[Category:Development]]

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

2010-03-06T20:07:56Z

HobbesPDX: spelling

== Introduction ==

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

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

== Retrieving the Data ==

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

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

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

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

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

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

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

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

Our new getGreeting() method will therefore look like:

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

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

return $greeting;
}</source>

hello is the name of the table that we will create later, and greeting is the name of the field that stores the greetings. If you are not familiar with SQL, it would be helpful to take a tutorial or a lesson to get yourself up to speed. One such tutorial can be found at [http://www.w3schools.com/sql/default.asp w3schools].

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

== Creating the Installation SQL File ==

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

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

Here are our queries:

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

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

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

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

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

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

=== Creating the Uninstall SQL File ===

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

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

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

== Updating our XML File ==

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

Our new file looks like this:

<source lang="xml"><?xml version="1.0" encoding="utf-8"?>
<install type="component" version="1.5.0">
<name>Hello</name>

<creationDate>2007-02-22</creationDate>
<author>John Doe</author>
<authorEmail>john.doe@example.org</authorEmail>
<authorUrl>http://www.example.org</authorUrl>
<copyright>Copyright Info</copyright>
<license>License Info</license>

<version>3.01</version>

<description>Description of the component ...</description>



<files folder="site">
<filename>controller.php</filename>
<filename>hello.php</filename>
<filename>index.html</filename>
<filename>models/hello.php</filename>
<filename>models/index.html</filename>
<filename>views/index.html</filename>
<filename>views/hello/index.html</filename>
<filename>views/hello/view.html.php</filename>
<filename>views/hello/tmpl/default.php</filename>
<filename>views/hello/tmpl/index.html</filename>
</files>

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

<administration>

<menu>Hello World!</menu>


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

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

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

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

== Conclusion ==

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

== Articles in this Series ==
[[Developing a Model-View-Controller Component - Part 1]]

[[Developing a Model-View-Controller Component - Part 2 - Adding a Model]]

[[Developing a Model-View-Controller Component - Part 3 - Using the Database]]

[[Developing a Model-View-Controller Component - Part 4 - Creating an Administrator Interface]]

[[Developing a Model-View-Controller Component - Part 5 - Basic Backend Framework]]

[[Developing a Model-View-Controller Component - Part 6 - Adding Backend Actions]]

== Contributors ==
* staalanden

== Download ==

The component can be downloaded at: [http://joomlacode.org/gf/download/frsrelease/8110/29435/com_hello3_01.zip com_hello3_01]

[[Category:Database]]
[[Category:Development]]

J1.5:Developing a MVC Component/Adding a Model

2010-03-06T20:06:46Z

HobbesPDX: continuity

{{review}}
== Introduction ==

In the first tutorial of this series, creating a simple view-controller component using the Joomla! 1.5 CMS framework was demonstrated.

In the first tutorial, the greeting was hardcoded into the view. This doesn't follow the MVC pattern exactly because the view is intended to only display the data, and not contain it.

In this second part of the tutorial we will demonstrate how to move this out of the view and into a model. In future tutorials we will demonstrate the power and flexibility that this design pattern provides.

== Creating the Model ==

The concept of model gets its name because this class is intended to represent (or 'model') some entity. In our case, our first model will represent a 'hello', or a greeting. This is in line with our design thus far, because we have one view ('hello'), which is a view of our greeting.

The naming convention for models in the Joomla! framework is that the class name starts with the name of the component (in our case 'hello', followed by 'model', followed by the model name. Therefore, our model class is called HelloModelHello.

At this point, we will only model one behaviour of our hello, and that is retrieving the greeting. We will thus have one method, called getGreeting(). It will simply return the string 'Hello, World!'.

The code for the view at site/models/hello.php:

<source lang="php"><?php
/**
* Hello Model for Hello World Component
*
* @package Joomla.Tutorials
* @subpackage Components
* @link http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_2
* @license GNU/GPL
*/

// No direct access

defined( '_JEXEC' ) or die( 'Restricted access' );

jimport( 'joomla.application.component.model' );

/**
* Hello Model
*
* @package Joomla.Tutorials
* @subpackage Components
*/
class HelloModelHello extends JModel
{
/**
* Gets the greeting
* @return string The greeting to be displayed to the user
*/
function getGreeting()
{
return 'Hello, World!';
}
}</source>

You will notice a line that starts with jimport. The jimport function is used to load files from the Joomla! framework that are required for our component. This particular statement will load the file /libraries/joomla/application/component/model.php. The '.'s are used as directory separators and the last part is the name of the file to load. All files are loaded relative to the libraries directory. This particular file contains the class definition for the JModel class, which is necessary because our model extends this class.

Now that we have created our model, we must modify our view so that it uses it to obtain the greeting.

== Using the Model ==

The Joomla! framework is setup in such a way that the controller will automatically load the model that has the same name as the view and will push it into the view. Since our view is called 'Hello', our 'Hello' model will automatically be loaded and pushed into the view. Therefore, we can easily retrieve a reference to our model using the JView::getModel() method. (If the model had not followed this convention, we could have passed the model name to [http://api.joomla.org/Joomla-Framework/Application/JView.html#getModel JView::getModel()])

Our previous view code contained the lines:

<source lang="php">$greeting = "Hello World!";</source>

To take advantage of our model, we change this line to:

<source lang="php">$model = &$this->getModel();
$greeting = $model->getGreeting();</source>

The complete view now looks like:

<source lang="php"><?php
/**
* @package Joomla.Tutorials
* @subpackage Components
* @link http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_2
* @license GNU/GPL
*/

// No direct access

defined( '_JEXEC' ) or die( 'Restricted access' );

jimport( 'joomla.application.component.view');

/**
* HTML View class for the HelloWorld Component
*
* @package HelloWorld
*/

class HelloViewHello extends JView
{
function display($tpl = null)
{
$model = &$this->getModel();
$greeting = $model->getGreeting();
$this->assignRef( 'greeting', $greeting );

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

=== Adding the File to the Package ===

All that remains is to add an entry to the XML file so that our new model will be copied. The Joomla! framework will look for our model in the models directory, so the entry for this file will look like (it should be added to the site section):

<source lang="php"><filename>models/hello.php</filename></source>

Our new hello.xml file will look like:

<source lang="xml"><?xml version="1.0" encoding="utf-8"?>
<install type="component" version="1.5.0">
<name>Hello</name>

<creationDate>2007-02-22</creationDate>
<author>John Doe</author>
<authorEmail>john.doe@example.org</authorEmail>
<authorUrl>http://www.example.org</authorUrl>
<copyright>Copyright Info</copyright>
<license>License Info</license>

<version>1.01</version>

<description>Description of the component ...</description>



<files folder="site">
<filename>controller.php</filename>
<filename>hello.php</filename>
<filename>index.html</filename>
<filename>models/hello.php</filename>
<filename>models/index.html</filename>
<filename>views/index.html</filename>
<filename>views/hello/index.html</filename>
<filename>views/hello/view.html.php</filename>
<filename>views/hello/tmpl/default.php</filename>
<filename>views/hello/tmpl/index.html</filename>
</files>

<administration>

<menu>Hello World!</menu>


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

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

== Conclusion ==

We now have a simple MVC component. Each element is very simple at this point, but provides a great deal of flexibility and power.

== Articles in this Series ==
[[Developing a Model-View-Controller Component - Part 1]]

[[Developing a Model-View-Controller Component - Part 2 - Adding a Model]]

[[Developing a Model-View-Controller Component - Part 3 - Using the Database]]

[[Developing a Model-View-Controller Component - Part 4 - Creating an Administrator Interface]]

[[Developing a Model-View-Controller Component - Part 5 - Basic Backend Framework]]

[[Developing a Model-View-Controller Component - Part 6 - Adding Backend Actions]]

== Contributors ==
* staalanden

== Download ==

The component can be downloaded at: [http://joomlacode.org/gf/download/frsrelease/8109/29434/com_hello2_01.zip com_hello2_01]

[[Category:Development]]

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

2010-03-06T20:04:49Z

HobbesPDX: for continuity -- it's hello.xml, not install.xml

== Introduction ==

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

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

== Retrieving the Data ==

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

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

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

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

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

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

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

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

Our new getGreeting() method will therefore look like:

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

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

return $greeting;
}</source>

hello is the name of the table that we will create later, and greeting is the name of the field that stores the greetings. If you are not familiar with SQL, it would be helpful to take a tutorial or a lesson to get yourself up to speed. One such tutorial can be found at [http://www.w3schools.com/sql/default.asp w3schools].

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

== Creating the Installation SQL File ==

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

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

Here are our queries:

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

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

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

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

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

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

=== Creating the Uninstall SQL File ===

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

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

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

== Updating our XML File ==

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

Our new file looks like this:

<source lang="xml"><?xml version="1.0" encoding="utf-8"?>
<install type="component" version="1.5.0">
<name>Hello</name>

<creationDate>2007-02-22</creationDate>
<author>John Doe</author>
<authorEmail>john.doe@example.org</authorEmail>
<authorUrl>http://www.example.org</authorUrl>
<copyright>Copyright Info</copyright>
<license>License Info</license>

<version>3.01</version>

<description>Description of the component ...</description>



<files folder="site">
<filename>controller.php</filename>
<filename>hello.php</filename>
<filename>index.html</filename>
<filename>models/hello.php</filename>
<filename>models/index.html</filename>
<filename>views/index.html</filename>
<filename>views/hello/index.html</filename>
<filename>views/hello/view.html.php</filename>
<filename>views/hello/tmpl/default.php</filename>
<filename>views/hello/tmpl/index.html</filename>
</files>

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

<administration>

<menu>Hello World!</menu>


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

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

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

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

== Conclusion ==

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

== Articles in this Series ==
[[Developing a Model-View-Controller Component - Part 1]]

[[Developing a Model-View-Controller Component - Part 2 - Adding a Model]]

[[Developing a Model-View-Controller Component - Part 3 - Using the Database]]

[[Developing a Model-View-Controller Component - Part 4 - Creating an Administrator Interface]]

[[Developing a Model-View-Controller Component - Part 5 - Basic Backend Framework]]

[[Developing a Model-View-Controller Component - Part 6 - Adding Backend Actions]]

== Contributors ==
* staalanden

== Download ==

The component can be downloaded at: [http://joomlacode.org/gf/download/frsrelease/8110/29435/com_hello3_01.zip com_hello3_01]

[[Category:Database]]
[[Category:Development]]