Joomla! Documentation - User contributions [en]

J3.x:Developing an MVC Component/Using the database

2017-09-12T10:27:54Z

Honje:

<noinclude><languages /></noinclude>
{{:J3.1:Developing an MVC Component/<translate>
en</translate>}}
<translate>== Introduction == </translate>
<translate>
This tutorial is part of the [[S:MyLanguage/J3.3:Developing an MVC Component | Developing an MVC Component for Joomla! 3.3]] tutorial. You are encouraged to read the previous parts of the tutorial before reading this. Also while doing this part you are also encouraged to read more on database queries, selecting data from a database table and retrieving it in several formats [[S:MyLanguage/Selecting_data_using_JDatabase|here]].</translate>

<translate> There are also 3 videos associated with this step in the tutorial, covering [https://www.youtube.com/watch?v=JWS_3rx8RzY the Database Setup], [https://www.youtube.com/watch?v=rKEHDeFGlGM Displaying the message (using JTable)] and [https://www.youtube.com/watch?v=uEDNyG6pSEk Admin message selection (and JDatabase)].</translate>

{{#widget:YouTube|id=JWS_3rx8RzY}}

{{#widget:YouTube|id=rKEHDeFGlGM}}

{{#widget:YouTube|id=uEDNyG6pSEk}}

<translate>== Using the database == </translate>
<translate>
Components usually manage their contents using the database. During the install/uninstall/update phase of a component, you can execute SQL queries through the use of SQL text files.</translate>

<translate>
With your favourite file manager and editor create two files called <tt>admin/sql/install.mysql.utf8.sql</tt> and <tt>admin/sql/updates/mysql/0.0.6.sql</tt>. They should both have the same content, as follows:</translate>

<span id="admin/sql/install.mysql.utf8.sql">
<tt>'''admin/sql/install.mysql.utf8.sql''' and '''admin/sql/updates/mysql/0.0.6.sql'''</tt>
<source lang="sql">
DROP TABLE IF EXISTS `#__helloworld`;

CREATE TABLE `#__helloworld` (
`id` INT(11) NOT NULL AUTO_INCREMENT,
`greeting` VARCHAR(25) NOT NULL,
`published` tinyint(4) NOT NULL DEFAULT '1',
PRIMARY KEY (`id`)
)
ENGINE =MyISAM
AUTO_INCREMENT =0
DEFAULT CHARSET =utf8;

INSERT INTO `#__helloworld` (`greeting`) VALUES
('Hello World!'),
('Good bye World!');

</source>
</span>

<translate>
The file <tt>install.mysql.utf8.sql</tt> will be executed when you install this component. The file ''0.0.6.sql'' is executed when you do an update.</translate>

<translate>
'''Important Note:''' When the component is installed, the files in the SQL updates folder (for example, ''admin/sql/updates/mysql'') are read and the name of the last file alphabetically is used to populate the component's version number in the <code>#__schemas</code> table. This value must be in this table in order for the automatic update to execute the update SQL files for future versions. For this reason, it is good practice to create a SQL update file for each version (even if it is empty or just has a comment). This way the <code>#__schemas</code> version will always match the component version.</translate>

<translate>
'''Important Note:''' When saving the SQL files in utf8, be sure to save them as utf8 NOT BOM or the query will fail with MySQL error #1064.</translate>

<translate>
This is the install file. It will be executed if you put an appropriate order in the <tt>helloworld.xml</tt> file.</translate>

<span id="helloworld.xml">
<tt>'''helloworld.xml'''</tt>
<source lang="xml" highlight="13,17-26,58-61">
<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="3.2.0" method="upgrade">

<name>Hello World!</name>

<creationDate>January 2014</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.6</version>

<description>Description of the Hello World component ...</description>

<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>
</files>

<administration>

<menu link='index.php?option=com_helloworld'>Hello World!</menu>


<files folder="admin">

<filename>index.html</filename>
<filename>helloworld.php</filename>

<folder>sql</folder>

<folder>tables</folder>

<folder>models</folder>
</files>
</administration>

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

<translate>
Do the same for the uninstall file:


With your favourite file manager and editor put a file <tt>admin/sql/uninstall.mysql.utf8.sql</tt> containing:</translate>

<span id="admin/sql/uninstall.mysql.utf8.sql">
<tt>'''admin/sql/uninstall.mysql.utf8.sql'''</tt>
<source lang="sql">
DROP TABLE IF EXISTS `#__helloworld`;
</source>
</span>

<translate>== Adding a new field type == </translate>
<translate>
For the moment, we have used a [[S:MyLanguage/J3.3:Developing an MVC Component/Adding a menu type to the site part|hard coded field type for messages]]. We need to use our database for choosing the message, and for this we need to define a custom field type (which we call ''helloworld'' below) as described [https://docs.joomla.org/Creating_a_custom_form_field_type here].</translate>

<translate>
Modify the <tt>site/views/helloworld/tmpl/default.xml</tt> file and put these lines</translate>

<span id="site/views/helloworld/tmpl/default.xml">
<tt>'''site/views/helloworld/tmpl/default.xml'''</tt>
<source lang="xml" highlight="8,11-16">
<?xml version="1.0" encoding="utf-8"?>
<metadata>
<layout title="COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_TITLE">
<message>COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_DESC</message>
</layout>
<fields
name="request"
addfieldpath="/administrator/components/com_helloworld/models/fields"
>
<fieldset name="request">
<field
name="id"
type="helloworld"
label="COM_HELLOWORLD_HELLOWORLD_FIELD_GREETING_LABEL"
description="COM_HELLOWORLD_HELLOWORLD_FIELD_GREETING_DESC"
/>
</fieldset>
</fields>
</metadata>
</source>
</span>

<translate>
It introduces a new field type and tells Joomla to look for the field definition in the <tt>/administrator/components/com_helloworld/models/fields</tt> folder.</translate>

<translate>
In order to learn more on database queries, selecting data from a database table and retrieving it in several formats [[S:MyLanguage/Selecting_data_using_JDatabase|click here]].</translate>
<translate>
With your favourite file manager and editor put a file ''admin/models/fields/helloworld.php'' containing:</translate>

<span id="admin/models/fields/helloworld.php">
<tt>'''admin/models/fields/helloworld.php'''</tt>
<source lang="php">
<?php
/**
* @package Joomla.Administrator
* @subpackage com_helloworld
*
* @copyright Copyright (C) 2005 - 2015 Open Source Matters, Inc. All rights reserved.
* @license GNU General Public License version 2 or later; see LICENSE.txt
*/

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

JFormHelper::loadFieldClass('list');

/**
* HelloWorld Form Field class for the HelloWorld component
*
* @since 0.0.1
*/
class JFormFieldHelloWorld extends JFormFieldList
{
/**
* The field type.
*
* @var string
*/
protected $type = 'HelloWorld';

/**
* Method to get a list of options for a list input.
*
* @return array An array of JHtml options.
*/
protected function getOptions()
{
$db = JFactory::getDBO();
$query = $db->getQuery(true);
$query->select('id,greeting');
$query->from('#__helloworld');
$db->setQuery((string) $query);
$messages = $db->loadObjectList();
$options = array();

if ($messages)
{
foreach ($messages as $message)
{
$options[] = JHtml::_('select.option', $message->id, $message->greeting);
}
}

$options = array_merge(parent::getOptions(), $options);

return $options;
}
}

</source>
</span>

<translate>
The new field type displays a drop-down list of messages to choose from. You can see the result of this change in the menu manager section for the helloworld item.</translate>

<translate>== Display the chosen message == </translate>
<translate>
When a menu item of this component is created/updated, Joomla stores the identifier of the message. The <tt>HelloWorldModelHelloWorld</tt> model has now to compute the message according to this identifier and the data stored in the database. To do this is uses the [https://docs.joomla.org/Using_the_JTable_class JTable] functionality, which is an alternative to JDatabase if only CRUD operations on single records are required.</translate>

<translate>
Modify the <tt>site/models/helloworld.php</tt> file:</translate>

<span id="site/models/helloworld.php">
<tt>'''site/models/helloworld.php'''</tt>
<source lang="php">
<?php
/**
* @package Joomla.Administrator
* @subpackage com_helloworld
*
* @copyright Copyright (C) 2005 - 2015 Open Source Matters, Inc. All rights reserved.
* @license GNU General Public License version 2 or later; see LICENSE.txt
*/

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

/**
* HelloWorld Model
*
* @since 0.0.1
*/
class HelloWorldModelHelloWorld extends JModelItem
{
/**
* @var array messages
*/
protected $messages;

/**
* Method to get a table object, load it if necessary.
*
* @param string $type The table name. Optional.
* @param string $prefix The class prefix. Optional.
* @param array $config Configuration array for model. Optional.
*
* @return JTable A JTable object
*
* @since 1.6
*/
public function getTable($type = 'HelloWorld', $prefix = 'HelloWorldTable', $config = array())
{
return JTable::getInstance($type, $prefix, $config);
}

/**
* Get the message
*
* @param integer $id Greeting Id
*
* @return string Fetched String from Table for relevant Id
*/
public function getMsg($id = 1)
{
if (!is_array($this->messages))
{
$this->messages = array();
}

if (!isset($this->messages[$id]))
{
// Request the selected id
$jinput = JFactory::getApplication()->input;
$id = $jinput->get('id', 1, 'INT');

// Get a TableHelloWorld instance
$table = $this->getTable();

// Load the message
$table->load($id);

// Assign the message
$this->messages[$id] = $table->greeting;
}

return $this->messages[$id];
}
}

</source>
</span>

<translate>
The model now asks the ''TableHelloWorld'' to get the message. This table class has to be defined in <tt>admin/tables/helloworld.php</tt> file</translate>

<span id="admin/tables/helloworld.php">
<tt>'''admin/tables/helloworld.php'''</tt>
<source lang="php">
<?php
/**
* @package Joomla.Administrator
* @subpackage com_helloworld
*
* @copyright Copyright (C) 2005 - 2015 Open Source Matters, Inc. All rights reserved.
* @license GNU General Public License version 2 or later; see LICENSE.txt
*/
// No direct access
defined('_JEXEC') or die('Restricted access');

/**
* Hello Table class
*
* @since 0.0.1
*/
class HelloWorldTableHelloWorld extends JTable
{
/**
* Constructor
*
* @param JDatabaseDriver &$db A database connector object
*/
function __construct(&$db)
{
parent::__construct('#__helloworld', 'id', $db);
}
}

</source>
</span>

<translate>
You shouldn't see any differences, but if you access the database you should see a table named ''jos_helloworld'' with two columns: id and greeting. And two entries: ''Hello World!'' and ''Good bye World''.</translate>

<translate>== Packaging the component == </translate>

<translate>
Content of your code directory</translate>

* ''[[#helloworld.xml|helloworld.xml]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Adding_a_view_to_the_site_part#site/helloworld.php|site/helloworld.php]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Developing_a_Basic_Component#index.html|site/index.html]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Adding_a_view_to_the_site_part#site/controller.php|site/controller.php]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Developing_a_Basic_Component#index.html|site/views/index.html]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Developing_a_Basic_Component#index.html|site/views/helloworld/index.html]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Adding_a_view_to_the_site_part#site/views/helloworld/view.html.php|site/views/helloworld/view.html.php]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Developing_a_Basic_Component#index.html|site/views/helloworld/tmpl/index.html]]''
* ''[[#site/views/helloworld/tmpl/default.xml|site/views/helloworld/tmpl/default.xml]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Adding_a_view_to_the_site_part#site/views/helloworld/tmpl/default.php|site/views/helloworld/tmpl/default.php]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Developing_a_Basic_Component#index.html|site/models/index.html]]''
* ''[[#site/models/helloworld.php|site/models/helloworld.php]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Developing_a_Basic_Component#index.html|admin/index.html]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Developing_a_Basic_Component#admin/helloworld.php|admin/helloworld.php]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Developing_a_Basic_Component#index.html|admin/sql/index.html]]''
* ''[[#admin/sql/install.mysql.utf8.sql|admin/sql/install.mysql.utf8.sql]]''
* ''[[#admin/sql/uninstall.mysql.utf8.sql|admin/sql/uninstall.mysql.utf8.sql]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Developing_a_Basic_Component#index.html|admin/sql/updates/index.html]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Developing_a_Basic_Component#index.html|admin/sql/updates/mysql/index.html]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Developing_a_Basic_Component#admin/sql/updates/mysql/0.0.1.sql|admin/sql/updates/mysql/0.0.1.sql]]''
* ''[[#admin/sql/install.mysql.utf8.sql|admin/sql/updates/mysql/0.0.6.sql]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Developing_a_Basic_Component#index.html|admin/models/index.html]]''
* ''[[#admin/models/helloworld.php|admin/models/helloworld.php]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Developing_a_Basic_Component#index.html|admin/models/fields/index.html]]''
* ''[[#admin/models/fields/helloworld.php]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Developing_a_Basic_Component#index.html|admin/tables/index.html]]''
* ''[[#admin/tables/helloworld.php|admin/tables/helloworld.php]]''

<translate>
Create a compressed file of this directory or directly download the [https://github.com/scionescire/Joomla-3.2-Hello-World-Component/archive/step-6-using-the-database.zip archive] and install it using the extension manager of Joomla. You can add a menu item of this component using the menu manager in the backend.</translate>

{{notice|<translate>
Please create a pull request or issue at https://github.com/joomla/Joomla-3.2-Hello-World-Component for any code discrepancies or if editing any of the source code on this page.</translate>}}

== Contributors ==
*[[User:cdemko|Christophe Demko]]
*[[User:oaksu|Ozgur Aksu]]
*[[User:scionescire|Scionescire]]

<div class="row">
<div class="large-6 columns">{{Basic button|<translate>
S:MyLanguage/J3.x:Developing_an_MVC_Component/Adding a variable request in the menu type|Prev: Adding a variable request in the menu type</translate>|class=expand success}}</div>
<div class="large-6 columns">{{Basic button|<translate>
S:MyLanguage/J3.x:Developing_an_MVC_Component/Basic backend|Next: Basic backend</translate>|class=expand}}</div>
</div>

<noinclude>
<translate>

[[Category:Joomla! 3.x]]
[[Category:Joomla! 3.0]]
[[Category:Joomla! 3.1]]
[[Category:Joomla! 3.2]]
[[Category:Joomla! 3.3]]
[[Category:Joomla! 3.4]]
[[Category:Beginner Development]]
[[Category:Component Development]]
[[Category:Tutorials]]
[[Category:Tutorials in a Series]]
</translate>
</noinclude>

J3.x:Developing an MVC Component/Using the database

2017-09-12T10:22:58Z

Honje:

<noinclude><languages /></noinclude>
{{:J3.1:Developing an MVC Component/<translate>
en</translate>}}
<translate>== Introduction == </translate>
<translate>
This tutorial is part of the [[S:MyLanguage/J3.3:Developing an MVC Component | Developing an MVC Component for Joomla! 3.3]] tutorial. You are encouraged to read the previous parts of the tutorial before reading this. Also while doing this part you are also encouraged to read more on database queries, selecting data from a database table and retrieving it in several formats [[S:MyLanguage/Selecting_data_using_JDatabase|here]].</translate>

<translate> There are also 3 videos associated with this step in the tutorial, covering [https://www.youtube.com/watch?v=JWS_3rx8RzY the Database Setup], [https://www.youtube.com/watch?v=rKEHDeFGlGM Displaying the message (using JTable)] and [https://www.youtube.com/watch?v=uEDNyG6pSEk Admin message selection (and JDatabase)].</translate>

{{#widget:YouTube|id=JWS_3rx8RzY}}

{{#widget:YouTube|id=rKEHDeFGlGM}}

{{#widget:YouTube|id=uEDNyG6pSEk}}

<translate>== Using the database == </translate>
<translate>
Components usually manage their contents using the database. During the install/uninstall/update phase of a component, you can execute SQL queries through the use of SQL text files.</translate>

<translate>
With your favourite file manager and editor create two files called <tt>admin/sql/install.mysql.utf8.sql</tt> and <tt>admin/sql/updates/mysql/0.0.6.sql</tt>. They should both have the same content, as follows:</translate>

<span id="admin/sql/install.mysql.utf8.sql">
<tt>'''admin/sql/install.mysql.utf8.sql''' and '''admin/sql/updates/mysql/0.0.6.sql'''</tt>
<source lang="sql">
DROP TABLE IF EXISTS `#__helloworld`;

CREATE TABLE `#__helloworld` (
`id` INT(11) NOT NULL AUTO_INCREMENT,
`greeting` VARCHAR(25) NOT NULL,
`published` tinyint(4) NOT NULL DEFAULT '1',
PRIMARY KEY (`id`)
)
ENGINE =MyISAM
AUTO_INCREMENT =0
DEFAULT CHARSET =utf8;

INSERT INTO `#__helloworld` (`greeting`) VALUES
('Hello World!'),
('Good bye World!');

</source>
</span>

<translate>
The file <tt>install.mysql.utf8.sql</tt> will be executed when you install this component. The file ''0.0.6.sql'' is executed when you do an update.</translate>

<translate>
'''Important Note:''' When the component is installed, the files in the SQL updates folder (for example, ''admin/sql/updates/mysql'') are read and the name of the last file alphabetically is used to populate the component's version number in the <code>#__schemas</code> table. This value must be in this table in order for the automatic update to execute the update SQL files for future versions. For this reason, it is good practice to create a SQL update file for each version (even if it is empty or just has a comment). This way the <code>#__schemas</code> version will always match the component version.</translate>

<translate>
'''Important Note:''' When saving the SQL files in utf8, be sure to save them as utf8 NOT BOM or the query will fail with MySQL error #1064.</translate>

<translate>
This is the install file. It will be executed if you put an appropriate order in the <tt>helloworld.xml</tt> file.</translate>

<span id="helloworld.xml">
<tt>'''helloworld.xml'''</tt>
<source lang="xml" highlight="13,17-26,58-61">
<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="3.2.0" method="upgrade">

<name>Hello World!</name>

<creationDate>January 2014</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.6</version>

<description>Description of the Hello World component ...</description>

<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>
</files>

<administration>

<menu link='index.php?option=com_helloworld'>Hello World!</menu>


<files folder="admin">

<filename>index.html</filename>
<filename>helloworld.php</filename>

<folder>sql</folder>

<folder>tables</folder>

<folder>models</folder>
</files>
</administration>

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

<translate>
Do the same for the uninstall file:


With your favourite file manager and editor put a file <tt>admin/sql/uninstall.mysql.utf8.sql</tt> containing:</translate>

<span id="admin/sql/uninstall.mysql.utf8.sql">
<tt>'''admin/sql/uninstall.mysql.utf8.sql'''</tt>
<source lang="sql">
DROP TABLE IF EXISTS `#__helloworld`;
</source>
</span>

<translate>== Adding a new field type == </translate>
<translate>
For the moment, we have used a [[S:MyLanguage/J3.3:Developing an MVC Component/Adding a menu type to the site part|hard coded field type for messages]]. We need to use our database for choosing the message, and for this we need to define a custom field type (which we call ''helloworld'' below) as described [https://docs.joomla.org/Creating_a_custom_form_field_type here].</translate>

<translate>
Modify the <tt>site/views/helloworld/tmpl/default.xml</tt> file and put these lines</translate>

<span id="site/views/helloworld/tmpl/default.xml">
<tt>'''site/views/helloworld/tmpl/default.xml'''</tt>
<source lang="xml" highlight="8,11-16">
<?xml version="1.0" encoding="utf-8"?>
<metadata>
<layout title="COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_TITLE">
<message>COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_DESC</message>
</layout>
<fields
name="request"
addfieldpath="/administrator/components/com_helloworld/models/fields"
>
<fieldset name="request">
<field
name="id"
type="helloworld"
label="COM_HELLOWORLD_HELLOWORLD_FIELD_GREETING_LABEL"
description="COM_HELLOWORLD_HELLOWORLD_FIELD_GREETING_DESC"
/>
</fieldset>
</fields>
</metadata>
</source>
</span>

<translate>
It introduces a new field type and tells Joomla to look for the field definition in the <tt>/administrator/components/com_helloworld/models/fields</tt> folder.</translate>

<translate>
In order to learn more on database queries, selecting data from a database table and retrieving it in several formats [[S:MyLanguage/Selecting_data_using_JDatabase|click here]].</translate>
<translate>
With your favourite file manager and editor put a file ''admin/models/fields/helloworld.php'' containing:</translate>

<span id="admin/models/fields/helloworld.php">
<tt>'''admin/models/fields/helloworld.php'''</tt>
<source lang="php">
<?php
/**
* @package Joomla.Administrator
* @subpackage com_helloworld
*
* @copyright Copyright (C) 2005 - 2015 Open Source Matters, Inc. All rights reserved.
* @license GNU General Public License version 2 or later; see LICENSE.txt
*/

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

JFormHelper::loadFieldClass('list');

/**
* HelloWorld Form Field class for the HelloWorld component
*
* @since 0.0.1
*/
class JFormFieldHelloWorld extends JFormFieldList
{
/**
* The field type.
*
* @var string
*/
protected $type = 'HelloWorld';

/**
* Method to get a list of options for a list input.
*
* @return array An array of JHtml options.
*/
protected function getOptions()
{
$db = JFactory::getDBO();
$query = $db->getQuery(true);
$query->select('id,greeting');
$query->from('#__helloworld');
$db->setQuery((string) $query);
$messages = $db->loadObjectList();
$options = array();

if ($messages)
{
foreach ($messages as $message)
{
$options[] = JHtml::_('select.option', $message->id, $message->greeting);
}
}

$options = array_merge(parent::getOptions(), $options);

return $options;
}
}

</source>
</span>

<translate>
The new field type displays a drop-down list of messages to choose from. You can see the result of this change in the menu manager section for the helloworld item.</translate>

<translate>== Display the chosen message == </translate>
<translate>
When a menu item of this component is created/updated, Joomla stores the identifier of the message. The <tt>HelloWorldModelHelloWorld</tt> model has now to compute the message according to this identifier and the data stored in the database. To do this is uses the [https://docs.joomla.org/Using_the_JTable_class JTable] functionality, which is an alternative to JDatabase if only CRUD operations on single records are required.</translate>

<translate>
Modify the <tt>site/models/helloworld.php</tt> file:</translate>

<span id="site/models/helloworld.php">
<tt>'''site/models/helloworld.php'''</tt>
<source lang="php">
<?php
/**
* @package Joomla.Administrator
* @subpackage com_helloworld
*
* @copyright Copyright (C) 2005 - 2015 Open Source Matters, Inc. All rights reserved.
* @license GNU General Public License version 2 or later; see LICENSE.txt
*/

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

/**
* HelloWorld Model
*
* @since 0.0.1
*/
class HelloWorldModelHelloWorld extends JModelItem
{
/**
* @var array messages
*/
protected $messages;

/**
* Method to get a table object, load it if necessary.
*
* @param string $type The table name. Optional.
* @param string $prefix The class prefix. Optional.
* @param array $config Configuration array for model. Optional.
*
* @return JTable A JTable object
*
* @since 1.6
*/
public function getTable($type = 'HelloWorld', $prefix = 'HelloWorldTable', $config = array())
{
return JTable::getInstance($type, $prefix, $config);
}

/**
* Get the message
*
* @param integer $id Greeting Id
*
* @return string Fetched String from Table for relevant Id
*/
public function getMsg($id = 1)
{
if (!is_array($this->messages))
{
$this->messages = array();
}

if (!isset($this->messages[$id]))
{
// Request the selected id
$jinput = JFactory::getApplication()->input;
$id = $jinput->get('id', 1, 'INT');

// Get a TableHelloWorld instance
$table = $this->getTable();

// Load the message
$table->load($id);

// Assign the message
$this->messages[$id] = $table->greeting;
}

return $this->messages[$id];
}
}

</source>
</span>

<translate>
The model now asks the ''TableHelloWorld'' to get the message. This table class has to be defined in <tt>admin/tables/helloworld.php</tt> file</translate>

<span id="admin/tables/helloworld.php">
<tt>'''admin/tables/helloworld.php'''</tt>
<source lang="php">
<?php
/**
* @package Joomla.Administrator
* @subpackage com_helloworld
*
* @copyright Copyright (C) 2005 - 2015 Open Source Matters, Inc. All rights reserved.
* @license GNU General Public License version 2 or later; see LICENSE.txt
*/
// No direct access
defined('_JEXEC') or die('Restricted access');

/**
* Hello Table class
*
* @since 0.0.1
*/
class HelloWorldTableHelloWorld extends JTable
{
/**
* Constructor
*
* @param JDatabaseDriver &$db A database connector object
*/
function __construct(&$db)
{
parent::__construct('#__helloworld', 'id', $db);
}
}

</source>
</span>

<translate>
You shouldn't see any differences, but if you access the database you should see a table named ''jos_helloworld'' with two columns: id and greeting. And two entries: ''Hello World!'' and ''Good bye World''.</translate>

<translate>== Packaging the component == </translate>

<translate>
Content of your code directory</translate>

* ''[[#helloworld.xml|helloworld.xml]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Adding_a_view_to_the_site_part#site/helloworld.php|site/helloworld.php]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Developing_a_Basic_Component#index.html|site/index.html]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Adding_a_view_to_the_site_part#site/controller.php|site/controller.php]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Developing_a_Basic_Component#index.html|site/views/index.html]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Developing_a_Basic_Component#index.html|site/views/helloworld/index.html]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Adding_a_view_to_the_site_part#site/views/helloworld/view.html.php|site/views/helloworld/view.html.php]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Developing_a_Basic_Component#index.html|site/views/helloworld/tmpl/index.html]]''
* ''[[#site/views/helloworld/tmpl/default.xml|site/views/helloworld/tmpl/default.xml]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Adding_a_view_to_the_site_part#site/views/helloworld/tmpl/default.php|site/views/helloworld/tmpl/default.php]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Developing_a_Basic_Component#index.html|site/models/index.html]]''
* ''[[#site/models/helloworld.php|site/models/helloworld.php]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Developing_a_Basic_Component#index.html|admin/index.html]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Developing_a_Basic_Component#admin/helloworld.php|admin/helloworld.php]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Developing_a_Basic_Component#index.html|admin/sql/index.html]]''
* ''[[#admin/sql/install.mysql.utf8.sql|admin/sql/install.mysql.utf8.sql]]''
* ''[[#admin/sql/uninstall.mysql.utf8.sql|admin/sql/uninstall.mysql.utf8.sql]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Developing_a_Basic_Component#index.html|admin/sql/updates/index.html]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Developing_a_Basic_Component#index.html|admin/sql/updates/mysql/index.html]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Developing_a_Basic_Component#admin/sql/updates/mysql/0.0.1.sql|admin/sql/updates/mysql/0.0.1.sql]]''
* ''[[#admin/sql/install.mysql.utf8.sql|admin/sql/updates/mysql/0.0.6.sql]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Developing_a_Basic_Component#index.html|admin/models/index.html]]''
* ''[[#admin/models/helloworld.php|admin/models/helloworld.php]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Developing_a_Basic_Component#index.html|admin/models/fields/index.html]]''
* ''[[#admin/models/fields/helloworld.php|admin/models/fields/helloworld.php]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Developing_a_Basic_Component#index.html|admin/tables/index.html]]''
* ''[[#admin/tables/helloworld.php|admin/tables/helloworld.php]]''

<translate>
Create a compressed file of this directory or directly download the [https://github.com/scionescire/Joomla-3.2-Hello-World-Component/archive/step-6-using-the-database.zip archive] and install it using the extension manager of Joomla. You can add a menu item of this component using the menu manager in the backend.</translate>

{{notice|<translate>
Please create a pull request or issue at https://github.com/joomla/Joomla-3.2-Hello-World-Component for any code discrepancies or if editing any of the source code on this page.</translate>}}

== Contributors ==
*[[User:cdemko|Christophe Demko]]
*[[User:oaksu|Ozgur Aksu]]
*[[User:scionescire|Scionescire]]

<div class="row">
<div class="large-6 columns">{{Basic button|<translate>
S:MyLanguage/J3.x:Developing_an_MVC_Component/Adding a variable request in the menu type|Prev: Adding a variable request in the menu type</translate>|class=expand success}}</div>
<div class="large-6 columns">{{Basic button|<translate>
S:MyLanguage/J3.x:Developing_an_MVC_Component/Basic backend|Next: Basic backend</translate>|class=expand}}</div>
</div>

<noinclude>
<translate>

[[Category:Joomla! 3.x]]
[[Category:Joomla! 3.0]]
[[Category:Joomla! 3.1]]
[[Category:Joomla! 3.2]]
[[Category:Joomla! 3.3]]
[[Category:Joomla! 3.4]]
[[Category:Beginner Development]]
[[Category:Component Development]]
[[Category:Tutorials]]
[[Category:Tutorials in a Series]]
</translate>
</noinclude>

J3.x:Developing an MVC Component/Using the database

2017-09-12T10:17:51Z

Honje:

<noinclude><languages /></noinclude>
{{:J3.1:Developing an MVC Component/<translate>
en</translate>}}
<translate>== Introduction == </translate>
<translate>
This tutorial is part of the [[S:MyLanguage/J3.3:Developing an MVC Component | Developing an MVC Component for Joomla! 3.3]] tutorial. You are encouraged to read the previous parts of the tutorial before reading this. Also while doing this part you are also encouraged to read more on database queries, selecting data from a database table and retrieving it in several formats [[S:MyLanguage/Selecting_data_using_JDatabase|here]].</translate>

<translate> There are also 3 videos associated with this step in the tutorial, covering [https://www.youtube.com/watch?v=JWS_3rx8RzY the Database Setup], [https://www.youtube.com/watch?v=rKEHDeFGlGM Displaying the message (using JTable)] and [https://www.youtube.com/watch?v=uEDNyG6pSEk Admin message selection (and JDatabase)].</translate>

{{#widget:YouTube|id=JWS_3rx8RzY}}

{{#widget:YouTube|id=rKEHDeFGlGM}}

{{#widget:YouTube|id=uEDNyG6pSEk}}

<translate>== Using the database == </translate>
<translate>
Components usually manage their contents using the database. During the install/uninstall/update phase of a component, you can execute SQL queries through the use of SQL text files.</translate>

<translate>
With your favourite file manager and editor create two files called <tt>admin/sql/install.mysql.utf8.sql</tt> and <tt>admin/sql/updates/mysql/0.0.6.sql</tt>. They should both have the same content, as follows:</translate>

<span id="admin/sql/install.mysql.utf8.sql">
<tt>'''admin/sql/install.mysql.utf8.sql''' and '''admin/sql/updates/mysql/0.0.6.sql'''</tt>
<source lang="sql">
DROP TABLE IF EXISTS `#__helloworld`;

CREATE TABLE `#__helloworld` (
`id` INT(11) NOT NULL AUTO_INCREMENT,
`greeting` VARCHAR(25) NOT NULL,
`published` tinyint(4) NOT NULL DEFAULT '1',
PRIMARY KEY (`id`)
)
ENGINE =MyISAM
AUTO_INCREMENT =0
DEFAULT CHARSET =utf8;

INSERT INTO `#__helloworld` (`greeting`) VALUES
('Hello World!'),
('Good bye World!');

</source>
</span>

<translate>
The file <tt>install.mysql.utf8.sql</tt> will be executed when you install this component. The file ''0.0.6.sql'' is executed when you do an update.</translate>

<translate>
'''Important Note:''' When the component is installed, the files in the SQL updates folder (for example, ''admin/sql/updates/mysql'') are read and the name of the last file alphabetically is used to populate the component's version number in the <code>#__schemas</code> table. This value must be in this table in order for the automatic update to execute the update SQL files for future versions. For this reason, it is good practice to create a SQL update file for each version (even if it is empty or just has a comment). This way the <code>#__schemas</code> version will always match the component version.</translate>

<translate>
'''Important Note:''' When saving the SQL files in utf8, be sure to save them as utf8 NOT BOM or the query will fail with MySQL error #1064.</translate>

<translate>
This is the install file. It will be executed if you put an appropriate order in the <tt>helloworld.xml</tt> file.</translate>

<span id="helloworld.xml">
<tt>'''helloworld.xml'''</tt>
<source lang="xml" highlight="13,17-26,58-61">
<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="3.2.0" method="upgrade">

<name>Hello World!</name>

<creationDate>January 2014</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.6</version>

<description>Description of the Hello World component ...</description>

<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>
</files>

<administration>

<menu link='index.php?option=com_helloworld'>Hello World!</menu>


<files folder="admin">

<filename>index.html</filename>
<filename>helloworld.php</filename>

<folder>sql</folder>

<folder>tables</folder>

<folder>models</folder>
</files>
</administration>

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

<translate>
Do the same for the uninstall file:


With your favourite file manager and editor put a file <tt>admin/sql/uninstall.mysql.utf8.sql</tt> containing:</translate>

<span id="admin/sql/uninstall.mysql.utf8.sql">
<tt>'''admin/sql/uninstall.mysql.utf8.sql'''</tt>
<source lang="sql">
DROP TABLE IF EXISTS `#__helloworld`;
</source>
</span>

<translate>== Adding a new field type == </translate>
<translate>
For the moment, we have used a [[S:MyLanguage/J3.3:Developing an MVC Component/Adding a menu type to the site part|hard coded field type for messages]]. We need to use our database for choosing the message, and for this we need to define a custom field type (which we call ''helloworld'' below) as described [https://docs.joomla.org/Creating_a_custom_form_field_type here].</translate>

<translate>
Modify the <tt>site/views/helloworld/tmpl/default.xml</tt> file and put these lines</translate>

<span id="site/views/helloworld/tmpl/default.xml">
<tt>'''site/views/helloworld/tmpl/default.xml'''</tt>
<source lang="xml" highlight="8,11-16">
<?xml version="1.0" encoding="utf-8"?>
<metadata>
<layout title="COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_TITLE">
<message>COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_DESC</message>
</layout>
<fields
name="request"
addfieldpath="/administrator/components/com_helloworld/models/fields"
>
<fieldset name="request">
<field
name="id"
type="helloworld"
label="COM_HELLOWORLD_HELLOWORLD_FIELD_GREETING_LABEL"
description="COM_HELLOWORLD_HELLOWORLD_FIELD_GREETING_DESC"
/>
</fieldset>
</fields>
</metadata>
</source>
</span>

<translate>
It introduces a new field type and tells Joomla to look for the field definition in the <tt>/administrator/components/com_helloworld/models/fields</tt> folder.</translate>

<translate>
In order to learn more on database queries, selecting data from a database table and retrieving it in several formats [[S:MyLanguage/Selecting_data_using_JDatabase|click here]].</translate>
<translate>
With your favourite file manager and editor put a file ''admin/models/fields/helloworld.php'' containing:</translate>

<span id="admin/models/fields/helloworld.php">
<tt>'''admin/models/fields/helloworld.php'''</tt>
<source lang="php">
<?php
/**
* @package Joomla.Administrator
* @subpackage com_helloworld
*
* @copyright Copyright (C) 2005 - 2015 Open Source Matters, Inc. All rights reserved.
* @license GNU General Public License version 2 or later; see LICENSE.txt
*/

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

JFormHelper::loadFieldClass('list');

/**
* HelloWorld Form Field class for the HelloWorld component
*
* @since 0.0.1
*/
class JFormFieldHelloWorld extends JFormFieldList
{
/**
* The field type.
*
* @var string
*/
protected $type = 'HelloWorld';

/**
* Method to get a list of options for a list input.
*
* @return array An array of JHtml options.
*/
protected function getOptions()
{
$db = JFactory::getDBO();
$query = $db->getQuery(true);
$query->select('id,greeting');
$query->from('#__helloworld');
$db->setQuery((string) $query);
$messages = $db->loadObjectList();
$options = array();

if ($messages)
{
foreach ($messages as $message)
{
$options[] = JHtml::_('select.option', $message->id, $message->greeting);
}
}

$options = array_merge(parent::getOptions(), $options);

return $options;
}
}

</source>
</span>

<translate>
The new field type displays a drop-down list of messages to choose from. You can see the result of this change in the menu manager section for the helloworld item.</translate>

<translate>== Display the chosen message == </translate>
<translate>
When a menu item of this component is created/updated, Joomla stores the identifier of the message. The <tt>HelloWorldModelHelloWorld</tt> model has now to compute the message according to this identifier and the data stored in the database. To do this is uses the [https://docs.joomla.org/Using_the_JTable_class JTable] functionality, which is an alternative to JDatabase if only CRUD operations on single records are required.</translate>

<translate>
Modify the <tt>site/models/helloworld.php</tt> file:</translate>

<span id="site/models/helloworld.php">
<tt>'''site/models/helloworld.php'''</tt>
<source lang="php">
<?php
/**
* @package Joomla.Administrator
* @subpackage com_helloworld
*
* @copyright Copyright (C) 2005 - 2015 Open Source Matters, Inc. All rights reserved.
* @license GNU General Public License version 2 or later; see LICENSE.txt
*/

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

/**
* HelloWorld Model
*
* @since 0.0.1
*/
class HelloWorldModelHelloWorld extends JModelItem
{
/**
* @var array messages
*/
protected $messages;

/**
* Method to get a table object, load it if necessary.
*
* @param string $type The table name. Optional.
* @param string $prefix The class prefix. Optional.
* @param array $config Configuration array for model. Optional.
*
* @return JTable A JTable object
*
* @since 1.6
*/
public function getTable($type = 'HelloWorld', $prefix = 'HelloWorldTable', $config = array())
{
return JTable::getInstance($type, $prefix, $config);
}

/**
* Get the message
*
* @param integer $id Greeting Id
*
* @return string Fetched String from Table for relevant Id
*/
public function getMsg($id = 1)
{
if (!is_array($this->messages))
{
$this->messages = array();
}

if (!isset($this->messages[$id]))
{
// Request the selected id
$jinput = JFactory::getApplication()->input;
$id = $jinput->get('id', 1, 'INT');

// Get a TableHelloWorld instance
$table = $this->getTable();

// Load the message
$table->load($id);

// Assign the message
$this->messages[$id] = $table->greeting;
}

return $this->messages[$id];
}
}

</source>
</span>

<translate>
The model now asks the ''TableHelloWorld'' to get the message. This table class has to be defined in <tt>admin/tables/helloworld.php</tt> file</translate>

<span id="admin/tables/helloworld.php">
<tt>'''admin/tables/helloworld.php'''</tt>
<source lang="php">
<?php
/**
* @package Joomla.Administrator
* @subpackage com_helloworld
*
* @copyright Copyright (C) 2005 - 2015 Open Source Matters, Inc. All rights reserved.
* @license GNU General Public License version 2 or later; see LICENSE.txt
*/
// No direct access
defined('_JEXEC') or die('Restricted access');

/**
* Hello Table class
*
* @since 0.0.1
*/
class HelloWorldTableHelloWorld extends JTable
{
/**
* Constructor
*
* @param JDatabaseDriver &$db A database connector object
*/
function __construct(&$db)
{
parent::__construct('#__helloworld', 'id', $db);
}
}

</source>
</span>

<translate>
You shouldn't see any differences, but if you access the database you should see a table named ''jos_helloworld'' with two columns: id and greeting. And two entries: ''Hello World!'' and ''Good bye World''.</translate>

<translate>== Packaging the component == </translate>

<translate>
Content of your code directory</translate>

* ''[[#helloworld.xml|helloworld.xml]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Adding_a_view_to_the_site_part#site/helloworld.php|site/helloworld.php]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Developing_a_Basic_Component#index.html|site/index.html]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Adding_a_view_to_the_site_part#site/controller.php|site/controller.php]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Developing_a_Basic_Component#index.html|site/views/index.html]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Developing_a_Basic_Component#index.html|site/views/helloworld/index.html]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Adding_a_view_to_the_site_part#site/views/helloworld/view.html.php|site/views/helloworld/view.html.php]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Developing_a_Basic_Component#index.html|site/views/helloworld/tmpl/index.html]]''
* ''[[#site/views/helloworld/tmpl/default.xml|site/views/helloworld/tmpl/default.xml]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Adding_a_view_to_the_site_part#site/views/helloworld/tmpl/default.php|site/views/helloworld/tmpl/default.php]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Developing_a_Basic_Component#index.html|site/models/index.html]]''
* ''[[#site/models/helloworld.php|site/models/helloworld.php]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Developing_a_Basic_Component#index.html|admin/index.html]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Developing_a_Basic_Component#admin/helloworld.php|admin/helloworld.php]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Developing_a_Basic_Component#index.html|admin/sql/index.html]]''
* ''[[#admin/sql/install.mysql.utf8.sql|admin/sql/install.mysql.utf8.sql]]''
* ''[[#admin/sql/uninstall.mysql.utf8.sql|admin/sql/uninstall.mysql.utf8.sql]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Developing_a_Basic_Component#index.html|admin/sql/updates/index.html]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Developing_a_Basic_Component#index.html|admin/sql/updates/mysql/index.html]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Developing_a_Basic_Component#admin/sql/updates/mysql/0.0.1.sql|admin/sql/updates/mysql/0.0.1.sql]]''
* ''[[#admin/sql/install.mysql.utf8.sql|admin/sql/updates/mysql/0.0.6.sql]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Developing_a_Basic_Component#index.html|admin/models/index.html]]''
* ''[[#admin/models/helloworld.php]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Developing_a_Basic_Component#index.html|admin/models/fields/index.html]]''
* ''[[#admin/models/fields/helloworld.php|admin/models/fields/helloworld.php]]''
* ''[[S:MyLanguage/J3.2:Developing_an_MVC_Component/Developing_a_Basic_Component#index.html|admin/tables/index.html]]''
* ''[[#admin/tables/helloworld.php|admin/tables/helloworld.php]]''

<translate>
Create a compressed file of this directory or directly download the [https://github.com/scionescire/Joomla-3.2-Hello-World-Component/archive/step-6-using-the-database.zip archive] and install it using the extension manager of Joomla. You can add a menu item of this component using the menu manager in the backend.</translate>

{{notice|<translate>
Please create a pull request or issue at https://github.com/joomla/Joomla-3.2-Hello-World-Component for any code discrepancies or if editing any of the source code on this page.</translate>}}

== Contributors ==
*[[User:cdemko|Christophe Demko]]
*[[User:oaksu|Ozgur Aksu]]
*[[User:scionescire|Scionescire]]

<div class="row">
<div class="large-6 columns">{{Basic button|<translate>
S:MyLanguage/J3.x:Developing_an_MVC_Component/Adding a variable request in the menu type|Prev: Adding a variable request in the menu type</translate>|class=expand success}}</div>
<div class="large-6 columns">{{Basic button|<translate>
S:MyLanguage/J3.x:Developing_an_MVC_Component/Basic backend|Next: Basic backend</translate>|class=expand}}</div>
</div>

<noinclude>
<translate>

[[Category:Joomla! 3.x]]
[[Category:Joomla! 3.0]]
[[Category:Joomla! 3.1]]
[[Category:Joomla! 3.2]]
[[Category:Joomla! 3.3]]
[[Category:Joomla! 3.4]]
[[Category:Beginner Development]]
[[Category:Component Development]]
[[Category:Tutorials]]
[[Category:Tutorials in a Series]]
</translate>
</noinclude>

Deploying an Update Server

2017-08-22T14:05:25Z

Honje:

<noinclude><languages /></noinclude>
<noinclude>{{Joomla version|version=2.5|status=eos}}{{Joomla version|version=3.x|}}</noinclude>

<translate>
== Introduction == 
</translate>
__TOC__
<translate>
This tutorial is designed to teach developers how to create an update server for integration with the update system introduced in Joomla!. By adding an update server listing to your extension's manifest, developers enable users to update their extensions via the Extension Manager's Update (see [[S:MyLanguage/Help31:Extensions Extension Manager Update|Joomla 3.x]] helpscreen) view with only a few clicks.</translate>
<translate>
== Defining an update server == 
</translate>
<translate>
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! 2.5 and newer 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. This code should be added to the extension manifest file, within the root "extension" element. The update server is defined as follows for each type:</translate>

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

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

<translate>
== Server types == 
</translate>
<translate>
=== Collection === 
</translate>
<translate>
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:</translate>

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

<translate>
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:</translate>

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

<translate>
=== Extension === 
</translate>
<translate>
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! 3.6.5 release:</translate>

<source lang="xml">
<updates>
<update>
<name>Joomla! 3.6</name>
<description>Joomla! 3.6 CMS</description>
<element>joomla</element>
<type>file</type>
<version>3.6.5</version>
<infourl title="Joomla!">https://www.joomla.org/announcements/release-news/5693-joomla-3-6-5-released.html</infourl>
<downloads>
<downloadurl type="full" format="zip">https://downloads.joomla.org/cms/joomla3/3-6-5/Joomla_3.6.5-Stable-Update_Package.zip</downloadurl>
</downloads>
<tags>
<tag>stable</tag>
</tags>
<maintainer>Joomla! PLT</maintainer>
<maintainerurl>https://www.joomla.org</maintainerurl>
<section>STS</section>
<targetplatform name="joomla" version="3.[234567]" />
<php_minimum>5.3.10</php_minimum>
</update>
</updates>
</source>

<translate>
The following section describes the elements of a single update entity.</translate>

<translate>
* '''name''' - The name of the extension, this name will appear in the Name column of the Extension Manager's Update view (required)</translate>
<translate>
* '''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.</translate>
<translate>
* '''element''' - The installed name of the extension (required). For plugins, this needs to be same as plugin attribute value for main file in plugin manifest. For <filename plugin="pluginname">pluginname.php</filename>, element value should be '''pluginname'''.</translate>
<translate>
* '''type''' - The type of extension (component, module, plugin, etc.) (required)</translate>
<translate>
* '''folder''' - Specific to plugins, this tag describes the type of plugin being updated (content, system, etc.) (required for plugins)</translate>
<translate>
* '''client''' - Required for modules and templates as of 3.2.0. - The client ID of the extension, which can be found by looking inside the #__extensions table. To date, use 0 for "site" and 1 for "administrator". Plugins and front-end modules are automatically installed with a client of 0 (site), but you will need to specify the client in an update or it will default to 1 (administrator) and then found update would not be shown because it would not match any extension. Components are automatically installed with a client of 1, which is currently the default.</translate>
<translate>
** ''Warning'': The tag name is <'''client'''> for Joomla! 2.5 and <'''client_id'''> for 1.6 and 1.7. If you use <client_id> (rather than <client>) on a 2.5 site, it will be ignored.</translate>
<translate>
* '''version''' - The version of the release (required)</translate>
<translate>
* '''infourl''' - A URL to point users to containing information about the update (optional) (In CMS 2.5, if set, this URL will be displayed in the update view)</translate>
<translate>
* '''downloads''' - The section which lists all download locations</translate>
<translate>
** '''downloadurl''' - The URL to download the extension from; the <downloadurl> tag has two required parameters:</translate>
<translate>
*** '''type''' - The type of package (full or upgrade)</translate>
<translate>
*** '''format''' - The format of the package (zip, tar, etc.)</translate>
<translate>
** '''NB''' - there must be no newline before or after the URL; it needs to all be on one line or you will get Error connecting to the server: malformed when the update is run</translate>
<translate>
* '''tags''' - A list of tags relevant to this version. Joomla! 3.4 and later uses this to determine the stability level of the update. The valid tags are:</translate>
<translate>
** ''dev'': Development versions, very unstable and pre-alpha (e.g. nightly builds)</translate>
<translate>
** ''alpha'': Alpha quality software (features not implemented, show-stopper bugs)</translate>
<translate>
** ''beta'': Beta quality software (all features implemented, show-stopper bugs possible, minor bugs almost certain)</translate>
<translate>
** ''rc'': Release Candidate quality software (no show-stopper bugs, minor bugs may still be present)</translate>
<translate>
** ''stable'': Production quality software All other tags are currently ignored. If you provide more than one tag containing one of the aforementioned stability keywords only the LAST tag will be taken into account. If you do not provide any tags Joomla! will assume it is a stable version</translate>.
<translate>
* '''maintainer''' - The name of the extension maintainer (similar to the <author> tag in a manifest) (optional)</translate>
<translate>
* '''maintainerurl''' - The website of the extension maintainer (similar to the <authorUrl> tag in a manifest) (optional)</translate>
<translate>
* '''section''' - Optional (unknown use)</translate>
<translate>
* '''targetplatform''' - A tag to define platform requirements, requires the following elementsː</translate>
<translate>
** '''name''' - The name of the platform dependency; as of this writing, it should ONLY be "joomla"</translate>
<translate>
** '''version''' - The version of Joomla! the extension supports</translate>
<translate>
** '''min_dev_level''' and '''max_dev_level''' - These attributes were added in 3.0.1 to allow you to select a target platform based on the developer level ("z" in x.y.z). They are optional. You can specify either one or both. If omitted, all developer levels are matched. For example, the following matches versions 4.0.0 and 4.0.1. <code><targetplatform name="joomla" version="4.0" min_dev_level="0" max_dev_level="1"/></code></translate>
<translate>
*** '''Note:''' If your extension is Joomla! 2.5 and/or 3.1 compatible, you will be required to have separate <update> definitions for each version due to the manner in which the updater checks the version if you specify a number. However to show your extension on all Joomla versions that support automatic updates add <code><targetplatform name="joomla" version=".*"/></code>. If you want your extension to show on all {{JVer|3.x}} versions then rather than specifying a version in the version tag add in <code><targetplatform name="joomla" version="3.[012345]"/></code>. This will show the update to all 3.x versions.</translate>
<translate>
* '''php_minimum''' - Beginning with 3.2.2, a minimum supported PHP version can be supplied in the update stream. If the server does not meet the minimum, a message is displayed to the user advising that an update is available but cannot be installed due to unsupported requirements.</translate>
* '''supported_databases''' - Beginning with 3.7, a minimum supported Databases + version can be supplied in the update stream. If the server does not meet the minimum, a message is displayed to the user advising that an update is available but cannot be installed due to unsupported requirements.
** An example could look like this: <code><supported_databases mysql="5.5.3" postgresql="9.2" mssql="10.50.1600.1" /></code>

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

<translate>
The values of '''element''', '''type''', '''client_id''' and '''folder''' should match those in the table #__extensions.</translate>

<translate>
'''Important for plugins:''' Plugins have to include <folder> and <client> elements to work properly</translate>

<translate>
== Troubleshooting == 
</translate>
<translate>
* '''SQL update script is not executed during update.'''</translate>
<translate>
:If the SQL update script (for example, in the folder <code>sql/updates/mysql</code>) does not get executed during the update process, it could be because there is no version number in the <code>#__schemas</code> table for this extension ''prior to the update''. This value is determined by the last script name in the SQL updates folder. If this value is blank, no SQL scripts will be executed during that update cycle. To make sure this value is set correctly, make sure you have a SQL script in this folder with its name as the version number (for example, 1.2.3.sql if the version is 1.2.3). The file can be empty or just have a SQL comment line. This should be done in the old version -- the one before the update. Alternatively, you can add this value to the <code>#__schemas</code> using a SQL query.</translate>

<translate>
== Supporting Tools == 
</translate>

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