Joomla! Documentation - User contributions [en]

J4.x:Creating a Plugin for Joomla/fa

2019-03-22T19:29:24Z

Levelup: Created page with "ساختار پلاگین در جوملا 1.5 و 2.5 و 3 بسیار منعطف و قدرتمند بود. بطوریکه نه تنها می توان پلاگین ها را ب..."

<noinclude><languages /></noinclude>
{{Top portal heading|color=white-bkgd|icon=magic|icon-color=#5091cd|size=3x|text-color=#333|title=خودآموز<br />
چگونه یک پلاگین برای جوملا 4 درست کنیم}}
<noinclude>{{Joomla version|version=4.x|comment=series}}</noinclude>
{{-}}
ساختار پلاگین در جوملا 1.5 و 2.5 و 3 بسیار منعطف و قدرتمند بود. بطوریکه نه تنها می توان پلاگین ها را برای راه اندازی رخداد های انجام شده در هسته اپلیکیشن و افزونه ها استفاده کرد، بلکه می توانند برای توسعه و قدرتمند کردن افزونه های دیگران نیز مورد استفاده قرار بگیرند. در جوملا 4 ما مقدار زیادی از سیستم dispatcher پشت سر آن را بازنویسی کرده ایم تا انعطاف پذیری را بیشتر افزایش دهیم هنگامی که شما پارامترهایی را که به عنوان رویدادها اصلاح می کنید و در عین حال کارایی پلاگین ها را افزایش دهید.

This How-To should provide you with the basics of what you need to know to develop your own plugin. Most plugins consist of just a single code file but to correctly install the plugin code it must be packaged into an installation file which can be processed by the Joomla installer.

=== Creating the Installation File ===
As with all extensions in Joomla, plugins are easily installed as a .zip file (.tar.gz is also supported) but a correctly formatted XML file must be included. <br />
As an example, here is the XML installation file for the categories search plugin:

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension version="3.1" type="plugin" group="search" method="upgrade">
<name>plg_search_categories</name>
<author>Joomla! Project</author>
<creationDate>November 2005</creationDate>
<copyright>Copyright (C) 2005 - 2018 Open Source Matters. All rights reserved.</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<authorEmail>admin@joomla.org</authorEmail>
<authorUrl>www.joomla.org</authorUrl>
<version>3.0.0</version>
<description>PLG_SEARCH_CATEGORIES_XML_DESCRIPTION</description>
<files>
<filename plugin="categories">categories.php</filename>
</files>
<languages>
<language tag="en-GB">en-GB.plg_search_categories.ini</language>
<language tag="en-GB">en-GB.plg_search_categories.sys.ini</language>
</languages>
<config>
<fields name="params">

<fieldset name="basic">
<field
name="search_limit"
type="number"
label="JFIELD_PLG_SEARCH_SEARCHLIMIT_LABEL"
default="50"
/>

<field
name="search_content"
type="radio"
class="switcher"
label="JFIELD_PLG_SEARCH_ALL_LABEL"
default="0"
>
<option value="1">JYES</option>
<option value="0">JNO</option>
</field>

<field
name="search_archived"
type="radio"
class="switcher"
label="JFIELD_PLG_SEARCH_ARCHIVED_LABEL"
default="0"
>
<option value="1">JYES</option>
<option value="0">JNO</option>
</field>
</fieldset>

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

As you can see, the system is similar to other Joomla XML installation files. You only have to look out for the <tt>group="xxx"</tt> entry in the <tt><extension></tt> tag and the extended information in the <tt><filename></tt> tag. This information tells Joomla into which folder to copy the file and to which group the plugin should be added.

If you are creating a plugin that responds to existing core events, the <tt>group="xxx"</tt> attribute would be changed to reflect the name of existing plugin folder for the event type you wish to augment. e.g. <tt>group="authentication"</tt> or <tt>group="user"</tt>. See [[S:MyLanguage/Plugin/Events|Plugin/Events]] for a complete list of existing core event categories. In creating a new plugin to respond to core events it is important that your plugin's name is unique and does not conflict with any of the other plugins that may also be responding to the core event you wish to service as well.

If you are creating a plugin to respond to non-core system events your choice for the <tt>group="xxx"</tt> tag should be different than any of the existing core categories.

'''TIP:''' ''If you add the attribute <tt>method="upgrade"</tt> to the tag <tt>extension</tt>, this plugin can be installed without uninstalling an earlier version. All existing files will be overwritten, but old files will not be deleted.''

=== Creating the Plugin ===
The object-oriented way of writing plugins involves writing a subclass of [https://api.joomla.org/cms-4/classes/Joomla.CMS.Plugin.CMSPlugin.html CMSPlugin], a base class that implements the basic properties of plugins. In your methods, the following properties are available:

* <tt>$this->params</tt>: the [[S:MyLanguage/Parameter|parameters]] set for this plugin by the administrator
* <tt>$this->_name</tt>: the name of the plugin
* <tt>$this->_type</tt>: the group (type) of the plugin
* <tt>$this->db</tt>: the db object
* <tt>$this->app</tt>: the application object

'''TIP:''' ''To use <tt>$this->db</tt> and <tt>$this->app</tt>, <tt>CMSPlugin</tt> tests if the property exists and is not private. If it is desired for the default objects to be used, create un-instantiated properties in the plugin class (i.e. <tt>protected $db; protected $app;</tt> in the same area as <tt>protected $autoloadLanguage = true;</tt>). The properties will not exist unless explicitly created.''

In the following code example, <tt><PluginGroup></tt> represents the group (type) of the plugin, and <tt><PluginName></tt> represents its name. Note that class and function names in PHP are case-insensitive.

We also implement the [https://api.joomla.org/framework-2/classes/Joomla.Event.SubscriberInterface.html SubscriberInterface] here which is the major change from Joomla 1.5-3.x. Instead of the function name automatically being detected and being the same as the event name this allows you to have custom function names. This allows us to tell what plugins are implementing what functions and as parsing public methods in PHP code is slow gives a significant performance boost.

Note throughout the Joomla 4 series there is a deprecated layer that will cover plugins using the old naming strategy of plugin names being the same as the event name when SubscriberInterface is not implemented.

<source lang="php">
<?php
// no direct access
defined( '_JEXEC' ) or die;

use Joomla\CMS\Plugin\CMSPlugin;
use Joomla\CMS\Event\Event;
use Joomla\Event\SubscriberInterface;

class Plg<PluginGroup><PluginName> extends CMSPlugin implements SubscriberInterface
{
/**
* Load the language file on instantiation
*
* @var boolean
* @since 3.1
*/
protected $autoloadLanguage = true;

/**
* Returns an array of events this subscriber will listen to.
*
* @return array
*/
public static function getSubscribedEvents(): array
{
return [
'<EventName>' => 'myFunctionName',
];
}

/**
* Plugin method is the array value in the getSubscribedEvents method
* The plugin then modifies the Event object (if it's not immutable)
*/
public function myFunctionName(Event $event)
{
/*
* Plugin code goes here.
* You can access parameters via $this->params
*/
return true;
}
}
?>
</source>

استفاده از پلاگین ها در کد های شما
If you are creating a plugin for a new, non-core event, remember to activate your plugin after you install it. Precede any reference to your new plugin with the <tt>JPluginHelper::importPlugin()</tt> command.

Now that you've created your plugin, you will probably want to call it in your code. You might not: the Joomla core has a number of built-in events that you might want your plugin code to be registered to (and in that case you can ignore this section).

==== New Joomla 4 Way ====
The new way of doing this in Joomla 4 is to get the dispatcher and dispatch a named event.

<source lang="php">
use Joomla\CMS\Event\AbstractEvent;
use Joomla\CMS\Factory;

$dispatcher = Factory::getApplication()->getDispatcher();

// Here we create an event however as long as you implement EventInterface you can create your own
// custom classes
$event = AbstractEvent::create(
'<EventName>',
[
'name' => $value,
]
);

$eventResult = $dispatcher->dispatch('<EventName>', $event);
</source>

If you want to allow the user to modify values you can then use the event result and getResults back out of it. You can look at

<source lang="php">
defined('_JEXEC') or die;

use BadMethodCallException;
use Joomla\CMS\Event\AbstractImmutableEvent;
use Joomla\CMS\Table\TableInterface;

/**
* Event class for an event
*/
class MyCustomEvent extends AbstractImmutableEvent
{
/**
* Constructor.
*
* @param string $name The event name.
* @param array $arguments The event arguments.
*
* @throws BadMethodCallException
*/
public function __construct($name, array $arguments = array())
{
if (!array_key_exists('myProperty', $arguments))
{
throw new BadMethodCallException("Argument 'myProperty' is required for event $name");
}

parent::__construct($name, $arguments);
}

/**
* Setter for the myProperty argument
*
* @param mixed $value The value to set
*
* @return mixed
*
* @throws BadMethodCallException if the argument is not of the expected type
*/
protected function setMyProperty($value)
{
if (!empty($value) && !is_object($value) && !is_array($value))
{
throw new BadMethodCallException("Argument 'src' of event {$this->name} must be empty, object or array");
}

return $value;
}
}
</source>

Why have we introduced this name class over parameters? Well it makes it easier to introduce custom setters and getters for properties - currently a plugin can either completely change a property as it wants - for a components there's no way of imposing any limitations. Additionally it makes it much easier for developers to add and remove parameters in an event without having major b/c issues (as you are now calling defined methods and are not subject to a property being the 2nd argument of your function).

==== How to achieve maximum compatibility with Joomla 3 ====
If you want to trigger an event in a similar way to the removed J3.x JEventDispatcher then you use code like this:

<source lang="php">
$results = \Joomla\CMS\Factory::getApplication()->triggerEvent( '<EventName>', <ParameterArray> );
</source>

It is important to note that the parameters have to be in an array. The plugin function itself will get the parameters as an Event object if it implements the SubscriberInterface and as individual values if it does not, but this method will always return an array that the plugin returns.

Note that if ANY plugin in a group doesn't implement the SubscriberInterface then the result property (as both a named parameter and result from a plugin) is used as a special property and cannot be used.

<noinclude>
[[Category:Tutorials{{#translation:}}]]
[[Category:Plugin Development{{#translation:}}]]
[[Category:Development{{#translation:}}]]
[[Category:Joomla!_4.x{{#translation:}}]]
</noinclude>

Translations:J4.x:Creating a Plugin for Joomla/2/fa

2019-03-22T19:29:23Z

ساختار پلاگین در جوملا 1.5 و 2.5 و 3 بسیار منعطف و قدرتمند بود. بطوریکه نه تنها می توان پلاگین ها را برای راه اندازی رخداد های انجام شده در هسته اپلیکیشن و افزونه ها استفاده کرد، بلکه می توانند برای توسعه و قدرتمند کردن افزونه های دیگران نیز مورد استفاده قرار بگیرند. در جوملا 4 ما مقدار زیادی از سیستم dispatcher پشت سر آن را بازنویسی کرده ایم تا انعطاف پذیری را بیشتر افزایش دهیم هنگامی که شما پارامترهایی را که به عنوان رویدادها اصلاح می کنید و در عین حال کارایی پلاگین ها را افزایش دهید.

J4.x:Creating a Plugin for Joomla/fa

2019-03-22T19:18:08Z

Levelup: Created page with "خودآموز<br /> چگونه یک پلاگین برای جوملا 4 درست کنیم"

<noinclude><languages /></noinclude>
{{Top portal heading|color=white-bkgd|icon=magic|icon-color=#5091cd|size=3x|text-color=#333|title=خودآموز<br />
چگونه یک پلاگین برای جوملا 4 درست کنیم}}
<noinclude>{{Joomla version|version=4.x|comment=series}}</noinclude>
{{-}}
The plugin structure for Joomla! 1.5, 2.5 and 3.x was very flexible and powerful. Not only can plugins be used to handle events triggered by the core application and extensions, but plugins can also be used to make third party extensions extensible and powerful. In Joomla 4.x we have rewritten a lot of the dispatcher system behind this to increase the flexibility further when you modify the parameters passed as events whilst simultaneously increasing the performance of plugins.

This How-To should provide you with the basics of what you need to know to develop your own plugin. Most plugins consist of just a single code file but to correctly install the plugin code it must be packaged into an installation file which can be processed by the Joomla installer.

=== Creating the Installation File ===
As with all extensions in Joomla, plugins are easily installed as a .zip file (.tar.gz is also supported) but a correctly formatted XML file must be included. <br />
As an example, here is the XML installation file for the categories search plugin:

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension version="3.1" type="plugin" group="search" method="upgrade">
<name>plg_search_categories</name>
<author>Joomla! Project</author>
<creationDate>November 2005</creationDate>
<copyright>Copyright (C) 2005 - 2018 Open Source Matters. All rights reserved.</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<authorEmail>admin@joomla.org</authorEmail>
<authorUrl>www.joomla.org</authorUrl>
<version>3.0.0</version>
<description>PLG_SEARCH_CATEGORIES_XML_DESCRIPTION</description>
<files>
<filename plugin="categories">categories.php</filename>
</files>
<languages>
<language tag="en-GB">en-GB.plg_search_categories.ini</language>
<language tag="en-GB">en-GB.plg_search_categories.sys.ini</language>
</languages>
<config>
<fields name="params">

<fieldset name="basic">
<field
name="search_limit"
type="number"
label="JFIELD_PLG_SEARCH_SEARCHLIMIT_LABEL"
default="50"
/>

<field
name="search_content"
type="radio"
class="switcher"
label="JFIELD_PLG_SEARCH_ALL_LABEL"
default="0"
>
<option value="1">JYES</option>
<option value="0">JNO</option>
</field>

<field
name="search_archived"
type="radio"
class="switcher"
label="JFIELD_PLG_SEARCH_ARCHIVED_LABEL"
default="0"
>
<option value="1">JYES</option>
<option value="0">JNO</option>
</field>
</fieldset>

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

As you can see, the system is similar to other Joomla XML installation files. You only have to look out for the <tt>group="xxx"</tt> entry in the <tt><extension></tt> tag and the extended information in the <tt><filename></tt> tag. This information tells Joomla into which folder to copy the file and to which group the plugin should be added.

If you are creating a plugin that responds to existing core events, the <tt>group="xxx"</tt> attribute would be changed to reflect the name of existing plugin folder for the event type you wish to augment. e.g. <tt>group="authentication"</tt> or <tt>group="user"</tt>. See [[S:MyLanguage/Plugin/Events|Plugin/Events]] for a complete list of existing core event categories. In creating a new plugin to respond to core events it is important that your plugin's name is unique and does not conflict with any of the other plugins that may also be responding to the core event you wish to service as well.

If you are creating a plugin to respond to non-core system events your choice for the <tt>group="xxx"</tt> tag should be different than any of the existing core categories.

'''TIP:''' ''If you add the attribute <tt>method="upgrade"</tt> to the tag <tt>extension</tt>, this plugin can be installed without uninstalling an earlier version. All existing files will be overwritten, but old files will not be deleted.''

=== Creating the Plugin ===
The object-oriented way of writing plugins involves writing a subclass of [https://api.joomla.org/cms-4/classes/Joomla.CMS.Plugin.CMSPlugin.html CMSPlugin], a base class that implements the basic properties of plugins. In your methods, the following properties are available:

* <tt>$this->params</tt>: the [[S:MyLanguage/Parameter|parameters]] set for this plugin by the administrator
* <tt>$this->_name</tt>: the name of the plugin
* <tt>$this->_type</tt>: the group (type) of the plugin
* <tt>$this->db</tt>: the db object
* <tt>$this->app</tt>: the application object

'''TIP:''' ''To use <tt>$this->db</tt> and <tt>$this->app</tt>, <tt>CMSPlugin</tt> tests if the property exists and is not private. If it is desired for the default objects to be used, create un-instantiated properties in the plugin class (i.e. <tt>protected $db; protected $app;</tt> in the same area as <tt>protected $autoloadLanguage = true;</tt>). The properties will not exist unless explicitly created.''

In the following code example, <tt><PluginGroup></tt> represents the group (type) of the plugin, and <tt><PluginName></tt> represents its name. Note that class and function names in PHP are case-insensitive.

We also implement the [https://api.joomla.org/framework-2/classes/Joomla.Event.SubscriberInterface.html SubscriberInterface] here which is the major change from Joomla 1.5-3.x. Instead of the function name automatically being detected and being the same as the event name this allows you to have custom function names. This allows us to tell what plugins are implementing what functions and as parsing public methods in PHP code is slow gives a significant performance boost.

Note throughout the Joomla 4 series there is a deprecated layer that will cover plugins using the old naming strategy of plugin names being the same as the event name when SubscriberInterface is not implemented.

<source lang="php">
<?php
// no direct access
defined( '_JEXEC' ) or die;

use Joomla\CMS\Plugin\CMSPlugin;
use Joomla\CMS\Event\Event;
use Joomla\Event\SubscriberInterface;

class Plg<PluginGroup><PluginName> extends CMSPlugin implements SubscriberInterface
{
/**
* Load the language file on instantiation
*
* @var boolean
* @since 3.1
*/
protected $autoloadLanguage = true;

/**
* Returns an array of events this subscriber will listen to.
*
* @return array
*/
public static function getSubscribedEvents(): array
{
return [
'<EventName>' => 'myFunctionName',
];
}

/**
* Plugin method is the array value in the getSubscribedEvents method
* The plugin then modifies the Event object (if it's not immutable)
*/
public function myFunctionName(Event $event)
{
/*
* Plugin code goes here.
* You can access parameters via $this->params
*/
return true;
}
}
?>
</source>

استفاده از پلاگین ها در کد های شما
If you are creating a plugin for a new, non-core event, remember to activate your plugin after you install it. Precede any reference to your new plugin with the <tt>JPluginHelper::importPlugin()</tt> command.

Now that you've created your plugin, you will probably want to call it in your code. You might not: the Joomla core has a number of built-in events that you might want your plugin code to be registered to (and in that case you can ignore this section).

==== New Joomla 4 Way ====
The new way of doing this in Joomla 4 is to get the dispatcher and dispatch a named event.

<source lang="php">
use Joomla\CMS\Event\AbstractEvent;
use Joomla\CMS\Factory;

$dispatcher = Factory::getApplication()->getDispatcher();

// Here we create an event however as long as you implement EventInterface you can create your own
// custom classes
$event = AbstractEvent::create(
'<EventName>',
[
'name' => $value,
]
);

$eventResult = $dispatcher->dispatch('<EventName>', $event);
</source>

If you want to allow the user to modify values you can then use the event result and getResults back out of it. You can look at

<source lang="php">
defined('_JEXEC') or die;

use BadMethodCallException;
use Joomla\CMS\Event\AbstractImmutableEvent;
use Joomla\CMS\Table\TableInterface;

/**
* Event class for an event
*/
class MyCustomEvent extends AbstractImmutableEvent
{
/**
* Constructor.
*
* @param string $name The event name.
* @param array $arguments The event arguments.
*
* @throws BadMethodCallException
*/
public function __construct($name, array $arguments = array())
{
if (!array_key_exists('myProperty', $arguments))
{
throw new BadMethodCallException("Argument 'myProperty' is required for event $name");
}

parent::__construct($name, $arguments);
}

/**
* Setter for the myProperty argument
*
* @param mixed $value The value to set
*
* @return mixed
*
* @throws BadMethodCallException if the argument is not of the expected type
*/
protected function setMyProperty($value)
{
if (!empty($value) && !is_object($value) && !is_array($value))
{
throw new BadMethodCallException("Argument 'src' of event {$this->name} must be empty, object or array");
}

return $value;
}
}
</source>

Why have we introduced this name class over parameters? Well it makes it easier to introduce custom setters and getters for properties - currently a plugin can either completely change a property as it wants - for a components there's no way of imposing any limitations. Additionally it makes it much easier for developers to add and remove parameters in an event without having major b/c issues (as you are now calling defined methods and are not subject to a property being the 2nd argument of your function).

==== How to achieve maximum compatibility with Joomla 3 ====
If you want to trigger an event in a similar way to the removed J3.x JEventDispatcher then you use code like this:

<source lang="php">
$results = \Joomla\CMS\Factory::getApplication()->triggerEvent( '<EventName>', <ParameterArray> );
</source>

It is important to note that the parameters have to be in an array. The plugin function itself will get the parameters as an Event object if it implements the SubscriberInterface and as individual values if it does not, but this method will always return an array that the plugin returns.

Note that if ANY plugin in a group doesn't implement the SubscriberInterface then the result property (as both a named parameter and result from a plugin) is used as a special property and cannot be used.

<noinclude>
[[Category:Tutorials{{#translation:}}]]
[[Category:Plugin Development{{#translation:}}]]
[[Category:Development{{#translation:}}]]
[[Category:Joomla!_4.x{{#translation:}}]]
</noinclude>

Translations:J4.x:Creating a Plugin for Joomla/1/fa

2019-03-22T19:18:07Z

Levelup: Created page with "خودآموز<br /> چگونه یک پلاگین برای جوملا 4 درست کنیم"

خودآموز<br />
چگونه یک پلاگین برای جوملا 4 درست کنیم

Translations:J4.x:Creating a Plugin for Joomla/Page display title/fa

2019-03-22T19:17:09Z

Levelup: Created page with "جوملا 4.x: ساخت یک پلاگین برای جوملا"

جوملا 4.x: ساخت یک پلاگین برای جوملا

J4.x:Creating a Plugin for Joomla/fa

2018-08-10T04:43:14Z

Levelup: Created page with "استفاده از پلاگین ها در کد های شما"

<noinclude><languages /></noinclude>
{{Top portal heading|color=white-bkgd|icon=magic|icon-color=#5091cd|size=3x|text-color=#333|title=Tutorial<br />
How to create a Plugin for Joomla 4}}
<noinclude>{{Joomla version|version=4.x|comment=series}}</noinclude>
{{-}}
The plugin structure for Joomla! 1.5, 2.5 and 3.x was very flexible and powerful. Not only can plugins be used to handle events triggered by the core application and extensions, but plugins can also be used to make third party extensions extensible and powerful. In Joomla 4.x we have rewritten a lot of the dispatcher system behind this to increase the flexibility further when you modify the parameters passed as events whilst simultaneously increasing the performance of plugins.

This How-To should provide you with the basics of what you need to know to develop your own plugin. Most plugins consist of just a single code file but to correctly install the plugin code it must be packaged into an installation file which can be processed by the Joomla installer.

=== Creating the Installation File ===
As with all extensions in Joomla, plugins are easily installed as a .zip file (.tar.gz is also supported) but a correctly formatted XML file must be included. <br />
As an example, here is the XML installation file for the categories search plugin:

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension version="3.1" type="plugin" group="search" method="upgrade">
<name>plg_search_categories</name>
<author>Joomla! Project</author>
<creationDate>November 2005</creationDate>
<copyright>Copyright (C) 2005 - 2018 Open Source Matters. All rights reserved.</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<authorEmail>admin@joomla.org</authorEmail>
<authorUrl>www.joomla.org</authorUrl>
<version>3.0.0</version>
<description>PLG_SEARCH_CATEGORIES_XML_DESCRIPTION</description>
<files>
<filename plugin="categories">categories.php</filename>
</files>
<languages>
<language tag="en-GB">en-GB.plg_search_categories.ini</language>
<language tag="en-GB">en-GB.plg_search_categories.sys.ini</language>
</languages>
<config>
<fields name="params">

<fieldset name="basic">
<field
name="search_limit"
type="number"
label="JFIELD_PLG_SEARCH_SEARCHLIMIT_LABEL"
default="50"
/>

<field
name="search_content"
type="radio"
class="switcher"
label="JFIELD_PLG_SEARCH_ALL_LABEL"
default="0"
>
<option value="1">JYES</option>
<option value="0">JNO</option>
</field>

<field
name="search_archived"
type="radio"
class="switcher"
label="JFIELD_PLG_SEARCH_ARCHIVED_LABEL"
default="0"
>
<option value="1">JYES</option>
<option value="0">JNO</option>
</field>
</fieldset>

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

As you can see, the system is similar to other Joomla XML installation files. You only have to look out for the <tt>group="xxx"</tt> entry in the <tt><extension></tt> tag and the extended information in the <tt><filename></tt> tag. This information tells Joomla into which folder to copy the file and to which group the plugin should be added.

If you are creating a plugin that responds to existing core events, the <tt>group="xxx"</tt> attribute would be changed to reflect the name of existing plugin folder for the event type you wish to augment. e.g. <tt>group="authentication"</tt> or <tt>group="user"</tt>. See [[S:MyLanguage/Plugin/Events|Plugin/Events]] for a complete list of existing core event categories. In creating a new plugin to respond to core events it is important that your plugin's name is unique and does not conflict with any of the other plugins that may also be responding to the core event you wish to service as well.

If you are creating a plugin to respond to non-core system events your choice for the <tt>group="xxx"</tt> tag should be different than any of the existing core categories.

'''TIP:''' ''If you add the attribute <tt>method="upgrade"</tt> to the tag <tt>extension</tt>, this plugin can be installed without uninstalling an earlier version. All existing files will be overwritten, but old files will not be deleted.''

=== Creating the Plugin ===
The object-oriented way of writing plugins involves writing a subclass of [https://api.joomla.org/cms-4/classes/Joomla.CMS.Plugin.CMSPlugin.html CMSPlugin], a base class that implements the basic properties of plugins. In your methods, the following properties are available:

* <tt>$this->params</tt>: the [[S:MyLanguage/Parameter|parameters]] set for this plugin by the administrator
* <tt>$this->_name</tt>: the name of the plugin
* <tt>$this->_type</tt>: the group (type) of the plugin
* <tt>$this->db</tt>: the db object
* <tt>$this->app</tt>: the application object

'''TIP:''' ''To use <tt>$this->db</tt> and <tt>$this->app</tt>, <tt>CMSPlugin</tt> tests if the property exists and is not private. If it is desired for the default objects to be used, create un-instantiated properties in the plugin class (i.e. <tt>protected $db; protected $app;</tt> in the same area as <tt>protected $autoloadLanguage = true;</tt>). The properties will not exist unless explicitly created.''

In the following code example, <tt><PluginGroup></tt> represents the group (type) of the plugin, and <tt><PluginName></tt> represents its name. Note that class and function names in PHP are case-insensitive.

We also implement the [https://api.joomla.org/framework-2/classes/Joomla.Event.SubscriberInterface.html SubscriberInterface] here which is the major change from Joomla 1.5-3.x. Instead of the function name automatically being detected and being the same as the event name this allows you to have custom function names. This allows us to tell what plugins are implementing what functions and as parsing public methods in PHP code is slow gives a significant performance boost.

Note throughout the Joomla 4 series there is a deprecated layer that will cover plugins using the old naming strategy of plugin names being the same as the event name when SubscriberInterface is not implemented.

<source lang="php">
<?php
// no direct access
defined( '_JEXEC' ) or die;

use Joomla\CMS\Plugin\CMSPlugin;
use Joomla\CMS\Event\Event;
use Joomla\Event\SubscriberInterface;

class Plg<PluginGroup><PluginName> extends CMSPlugin implements SubscriberInterface
{
/**
* Load the language file on instantiation
*
* @var boolean
* @since 3.1
*/
protected $autoloadLanguage = true;

/**
* Returns an array of events this subscriber will listen to.
*
* @return array
*/
public static function getSubscribedEvents(): array
{
return [
'<EventName>' => 'myFunctionName',
];
}

/**
* Plugin method is the array value in the getSubscribedEvents method
* The plugin then modifies the Event object (if it's not immutable)
*/
public function myFunctionName(Event $event)
{
/*
* Plugin code goes here.
* You can access parameters via $this->params
*/
return true;
}
}
?>
</source>

استفاده از پلاگین ها در کد های شما
If you are creating a plugin for a new, non-core event, remember to activate your plugin after you install it. Precede any reference to your new plugin with the <tt>JPluginHelper::importPlugin()</tt> command.

Now that you've created your plugin, you will probably want to call it in your code. You might not: the Joomla core has a number of built-in events that you might want your plugin code to be registered to (and in that case you can ignore this section).

==== New Joomla 4 Way ====
The new way of doing this in Joomla 4 is to get the dispatcher and dispatch a named event.

<source lang="php">
use Joomla\CMS\Event\AbstractEvent;
use Joomla\CMS\Factory;

$dispatcher = Factory::getApplication()->getDispatcher();

// Here we create an event however as long as you implement EventInterface you can create your own
// custom classes
$event = AbstractEvent::create(
'<EventName>',
[
'name' => $value,
]
);

$eventResult = $dispatcher->dispatch('<EventName>', $event);
</source>

If you want to allow the user to modify values you can then use the event result and getResults back out of it. You can look at

<source lang="php">
defined('_JEXEC') or die;

use BadMethodCallException;
use Joomla\CMS\Event\AbstractImmutableEvent;
use Joomla\CMS\Table\TableInterface;

/**
* Event class for an event
*/
class MyCustomEvent extends AbstractImmutableEvent
{
/**
* Constructor.
*
* @param string $name The event name.
* @param array $arguments The event arguments.
*
* @throws BadMethodCallException
*/
public function __construct($name, array $arguments = array())
{
if (!array_key_exists('myProperty', $arguments))
{
throw new BadMethodCallException("Argument 'myProperty' is required for event $name");
}

parent::__construct($name, $arguments);
}

/**
* Setter for the myProperty argument
*
* @param mixed $value The value to set
*
* @return mixed
*
* @throws BadMethodCallException if the argument is not of the expected type
*/
protected function setMyProperty($value)
{
if (!empty($value) && !is_object($value) && !is_array($value))
{
throw new BadMethodCallException("Argument 'src' of event {$this->name} must be empty, object or array");
}

return $value;
}
}
</source>

Why have we introduced this name class over parameters? Well it makes it easier to introduce custom setters and getters for properties - currently a plugin can either completely change a property as it wants - for a components there's no way of imposing any limitations. Additionally it makes it much easier for developers to add and remove parameters in an event without having major b/c issues (as you are now calling defined methods and are not subject to a property being the 2nd argument of your function).

==== How to achieve maximum compatibility with Joomla 3 ====
If you want to trigger an event in a similar way to the removed J3.x JEventDispatcher then you use code like this:

<source lang="php">
$results = JFactory::getApplication->triggerEvent( '<EventName>', <ParameterArray> );
</source>

It is important to note that the parameters have to be in an array. The plugin function itself will get the parameters as an Event object if it implements the SubscriberInterface and as individual values if it does not, but this method will always return an array that the plugin returns.

Note that if ANY plugin in a group doesn't implement the SubscriberInterface then the result property (as both a named parameter and result from a plugin) is used as a special property and cannot be used.

<noinclude>
[[Category:Tutorials{{#translation:}}]]
[[Category:Plugin Development{{#translation:}}]]
[[Category:Development{{#translation:}}]]
[[Category:Joomla!_4.x{{#translation:}}]]
</noinclude>

Translations:J4.x:Creating a Plugin for Joomla/22/fa

2018-08-10T04:43:13Z

Levelup: Created page with "استفاده از پلاگین ها در کد های شما"

استفاده از پلاگین ها در کد های شما

J4.x:CLI Update/fa

2018-08-04T14:38:09Z

Levelup:

<noinclude><languages /></noinclude>
{{Top portal heading|color=white-bkgd|text-color=#333|title=
GSoC 2018 <br />
بروز رسانی CLI <br/> مستندات}}
[[Image:Gsoc2016.png|75px|center|link=GSOC 2018]]
<noinclude>{{Joomla version|version=4.x}}</noinclude>
{{-}}

== Introduction ==
Performing some minor task on the Joomla! administrator dashboard might seem cumbersome and slow. The CLI Update is introducing a faster way to perform some of these operations through the command line. It brings forward a way to integrate things faster in the Joomla! app. With it, small tests can be done faster without having to go through the process of the web dashboard. It a CLI Application to the Joomla! CMS that enables user to perform updates in the CMS.

This documentation shows how the CLI Update can be used and how you can extend its functionality as a developer.

===Requirements===
As it goes for all CLI (Command Line Interface) Apps, access to a to your Joomla! installation via the command line is very important to use the tools provided by the CLI Update.
You might want to consider having an SSH access for your live server.

===Terms and definitions===
*CLI - Command Line Interface
*SSH - Secure SHell

==Using the CLI Update==
In other for you to use the tools provided by CLI Update, as said in former section, you need access to a CLI into the root of the Joomla Installation. In other words you have to be in the root folder of your Joomla CMS as all commands will run from the root folder.
[[File:All commands.png|center|800px]]

==General Command Usage==
In this section we will talk about the usage of commands, we will talk about different commands, what they are and how you can use them. We will go by checking out available commands in the CLI Update.

===Available commands===
There are quite a number of commands available in the CLI Update that ready for use, these commands are grouped based on the area of the Joomla! CMS that they are touching.

====Checking for Updates Updates====
The CLI Update provides a command to check for Joomla! updates, it works just like the web version of <tt>com_joomlaupdate</tt>, it retrieves update and tells if update is available or not. To run the update check, we will just issue the command like this from the root directory:<br />
<tt>php cli/joomla.php check-updates</tt>
<br />
The command runs and the output displays an available update version, if available, or tell otherwise that the current installation is up to date.
[[File:CheckCheck.png|center|800px]]

====Extension commands====
The next group of commands are the extension based commands, simply put, the commands allows us to manage extensions within the Jommla! core, the CLI Update ships with commands to install, list and remove extensions.

======Listing installed extensions======
This command allows us to list all installed extensions. This command can run in two different ways which are:
*''General Listing'': Lists all the extensions installed, by extensions it means components, languages, plugins, modules will be listed together when you run this command. This is how you call the command:{{-}}<tt>php cli/joomla.php extension:list</tt/> {{-}}[[File:Extension list.png|center|800px]]
*''Listing By types'': General listing of extension can be tedious if you're looking for a particular extension out of the big list, however, you can beat down the numbers specifying the type of extensions you can the command to display by adding a type option to the command. Here is how that is done: {{-}}<tt>php cli/joomla.php extension:list --type=language</tt>{{-}}[[File:Extension list type.png|center|800px]]
This will list out only language based extensions, you can specify type as module, plugin and component as well.

======Installing an Extension======
Joomla provides installing an extension through an URL to the zip file or a path to the file, the CLI Update provides both as well and how you can use them is described below.
*''Installing from URL'': To install an extension from URL we will run the command like this and provide an argument and option for the <tt>extension:install</tt> command.{{-}}<tt>php cli/joomla.php extension:install url --url=https://github.com/joomla-extensions/patchtester/releases/download/3.0.0-beta3/com_patchtester.zip</tt>{{-}}This will download the <tt>com_patchtester</tt> extension.
{{-}}[[File:Extension install url.png|center|800px]]
*''Installing from a PATH'':To install an extension from a PATH we will run the same <tt>extension:install</tt> command and specify arguments for paths like this:{{-}}<tt>php cli/joomla.php extension:install path --path=/Users/bosunski/docs/com_pathtester.zip</tt> {{-}}[[File:Extension install path.png|center|800px]]
This loads the extension and performs the installation as expected.

======Removing an extension======
The last command under this category is the <tt>extension:remove</tt> command that is used to remove extensions from the Joomla CMS. This command takes in the <tt>extension_id</tt> as an argument, you can always use the <tt>extension:list</tt> to display extension id. This is how we remove an extension of id <tt>803</tt><br/>
<tt>php cli/joomla.php extension:remove 803</tt>
[[File:Extension Remove.png|center|800px]]

====Updating the Joomla Core====
As much as the CLI Update provides a command to check update, it also provides a command to perform the update if an update is available. To perform update we will just run this:<br/>
<tt>php cli/joomla.php core:update</tt><br/>
This command updates the Joomla core updating it to the latest version available.

====Installing Joomla! via the CLI====
The next command here is the <tt>core:intall</tt> command that lets installation of Joomla CMS to be done via the CLI. This command can work in 2 modes: The Interactive mode and the Non-interactive mode.

=====Interactive installation=====
To have a fresh installation of Joomla using the interactive mode we will just run the <tt>extension:install</tt> command like so:<br/>
<tt>php cli/joomla.php extension:install</tt>

The default installation mode will run and will ask you to input the settings as it's required, once all options have been provided and validated, the installations will run and Joomla will be installed.

[[File:Core install interactive.png|center|800px]]

=====Non-interactive Installation=====
The next type of installation is the Non-interactive mode. In this mode you will not be asked to input the options but rather all options will be specified within a file and the command will take in an option that specifies the path to the file you want to load the options from, it's done like this:<br/>
<tt>php cli/joomla.php core:install --file=/path/to/config.json</tt>

[[File:Core install file.png|center|800px]]

An example of the contents of <tt>config.json</tt> can be:<br/>
<source lang="json">
{
"language":"en-GB",
"site_name":"Joomla",
"admin_email":"email@example.com",
"admin_user":"user",
"admin_password":"password",
"db_type":"mysql",
"db_host":"localhost",
"db_user":"root",
"db_pass":"xcdxcx",
"db_name":"jtest",
"db_prefix":"efs0k_",
"db_old":"remove",
"helpurl":"https://joomla.org"
}
</source>

OR as sample <tt>config.ini</tt>

<source lang="ini">
site_name="gsoc"
admin_email="user@example.com"
admin_user="user"
admin_password="secret"
db_type="mysql"
db_host="localhost"
db_user="root"
db_pass=""
db_name="joomla"
db_prefix="prefix_"
</source>

The options defined are loaded and validated after which the installation will run.

====
Configuration based commands====
The next set of commands we will be looking at is for setting and viewing configuration options inside the Joomla installation:

=====Setting configurations=====
The CLI Update provides a command to change the value of an option existing in the configuration. Using the <tt>config:get</tt> command you can set any configuration option that exists inside the <tt>configuration.php</tt>. This is how to use command:<br/>
<tt>php cli/joomla.php config:set mailer=mail</tt>

[[File:Config set single.png|center|800px]]

You can even add multiple option-value pairs like this:<br/>
<tt>php cli/joomla.php config:set mailer=mail fromname=Joomla!</tt>
This will set multiple options at once.

[[File:Config set multiple.png|center|800px]]

=====Getting configurations=====
The next command in this category is the <tt>config:get</tt> command, as the name suggests it gets the value of an option that exists inside the <tt>configuration.php</tt>, when no argument is supplied to the command, it will display all the options available in a tabulated form. Here is the command:<br/>
<tt>php cli/joomla.php config:get sitename</tt>

This will return the value for the option <tt>sitename</tt>.

[[File:011-cli.png|center|800px]]

<tt>php cli/joomla.php config:get</tt>

This will return all the values for the available options.

[[File:Config get all.png|center|800px]]

=====Getting grouped configurations=====
The CLI Update adds an option to <tt>config:get</tt> command that allows us to get logically grouped options, say for example you want to view all your database related options, or you want to view all email related options. To achieve this the CLI Update provides an option to specify a group of options to display, here is how to do that:

<tt>php cli/joomla.php config:get --group=mail</tt>

[[File:Config get group.png|center|800px]]

The command takes in the <tt>group</tt> option and given the value of <tt>mail</tt>. CLI Update currently supports group values: mail, db and session.

====Site down and Site up commands====
As their name suggests, these commands allow you to quickly put your Joomla powered website into offline or online mode. Here is how to use the commands:<br/>
<tt>php cli/joomla.php site:up</tt>

[[File:Site up.png|center|800px]]

<tt>php cli/joomla.php site:down</tt>

[[File:Site down.png|center|800px]]

The second command puts the website in offline mode while the first command brings the website to online mode.

==Contributing to CLI Update as a developer==

===Adding more commands===
The CLI Update ships with some commands which are added based on the need seen as of the time. However, the CLI Update allows other commands to be added easily and this is what this section is for. A video tutorial is included below.

<div class="video-container">
{{#widget:YouTube|id=gcJJtTcPiTg}}
</div>

===Calling other commands within command classes===
Should in case a command you want to write for the CLI Update is going to be require that you call an existing command internally, this is how that can be achieved from within another command class:

<source lang="php">
<?php
class RunHelloCommand extends AbstractCommand {
...

public function execute(): int {
$command = $this->getApplication()->getCommand('say:hello');
$code = $command->execute();

if($code === 0) {
// command ran successfully, do something
}
}

...
}
</source>

Here, we're attempting to call the <tt>say:hello</tt> command created in the Video above.

===Some important things to checkout===
*Symfony Style Documentation: [https://symfony.com/doc/current/console/style.html How to Style a Console Command]

<noinclude>
[[Category:Google Summer of Code 2018]]
[[Category:Development]]
[[Category:Joomla!_4.x]]
</noinclude>

Translations:J4.x:CLI Update/1/fa

2018-08-04T14:38:08Z

Levelup:

بروز رسانی CLI <br/> مستندات

J4.x:CLI Update/fa

2018-08-04T14:37:36Z

Levelup: Created page with "بروز رسانی CLI <br /> مستندات"

<noinclude><languages /></noinclude>
{{Top portal heading|color=white-bkgd|text-color=#333|title=
GSoC 2018 <br />
بروز رسانی CLI <br /> مستندات}}
[[Image:Gsoc2016.png|75px|center|link=GSOC 2018]]
<noinclude>{{Joomla version|version=4.x}}</noinclude>
{{-}}

== Introduction ==
Performing some minor task on the Joomla! administrator dashboard might seem cumbersome and slow. The CLI Update is introducing a faster way to perform some of these operations through the command line. It brings forward a way to integrate things faster in the Joomla! app. With it, small tests can be done faster without having to go through the process of the web dashboard. It a CLI Application to the Joomla! CMS that enables user to perform updates in the CMS.

This documentation shows how the CLI Update can be used and how you can extend its functionality as a developer.

===Requirements===
As it goes for all CLI (Command Line Interface) Apps, access to a to your Joomla! installation via the command line is very important to use the tools provided by the CLI Update.
You might want to consider having an SSH access for your live server.

===Terms and definitions===
*CLI - Command Line Interface
*SSH - Secure SHell

==Using the CLI Update==
In other for you to use the tools provided by CLI Update, as said in former section, you need access to a CLI into the root of the Joomla Installation. In other words you have to be in the root folder of your Joomla CMS as all commands will run from the root folder.
[[File:All commands.png|center|800px]]

==General Command Usage==
In this section we will talk about the usage of commands, we will talk about different commands, what they are and how you can use them. We will go by checking out available commands in the CLI Update.

===Available commands===
There are quite a number of commands available in the CLI Update that ready for use, these commands are grouped based on the area of the Joomla! CMS that they are touching.

====Checking for Updates Updates====
The CLI Update provides a command to check for Joomla! updates, it works just like the web version of <tt>com_joomlaupdate</tt>, it retrieves update and tells if update is available or not. To run the update check, we will just issue the command like this from the root directory:<br />
<tt>php cli/joomla.php check-updates</tt>
<br />
The command runs and the output displays an available update version, if available, or tell otherwise that the current installation is up to date.
[[File:CheckCheck.png|center|800px]]

====Extension commands====
The next group of commands are the extension based commands, simply put, the commands allows us to manage extensions within the Jommla! core, the CLI Update ships with commands to install, list and remove extensions.

======Listing installed extensions======
This command allows us to list all installed extensions. This command can run in two different ways which are:
*''General Listing'': Lists all the extensions installed, by extensions it means components, languages, plugins, modules will be listed together when you run this command. This is how you call the command:{{-}}<tt>php cli/joomla.php extension:list</tt/> {{-}}[[File:Extension list.png|center|800px]]
*''Listing By types'': General listing of extension can be tedious if you're looking for a particular extension out of the big list, however, you can beat down the numbers specifying the type of extensions you can the command to display by adding a type option to the command. Here is how that is done: {{-}}<tt>php cli/joomla.php extension:list --type=language</tt>{{-}}[[File:Extension list type.png|center|800px]]
This will list out only language based extensions, you can specify type as module, plugin and component as well.

======Installing an Extension======
Joomla provides installing an extension through an URL to the zip file or a path to the file, the CLI Update provides both as well and how you can use them is described below.
*''Installing from URL'': To install an extension from URL we will run the command like this and provide an argument and option for the <tt>extension:install</tt> command.{{-}}<tt>php cli/joomla.php extension:install url --url=https://github.com/joomla-extensions/patchtester/releases/download/3.0.0-beta3/com_patchtester.zip</tt>{{-}}This will download the <tt>com_patchtester</tt> extension.
{{-}}[[File:Extension install url.png|center|800px]]
*''Installing from a PATH'':To install an extension from a PATH we will run the same <tt>extension:install</tt> command and specify arguments for paths like this:{{-}}<tt>php cli/joomla.php extension:install path --path=/Users/bosunski/docs/com_pathtester.zip</tt> {{-}}[[File:Extension install path.png|center|800px]]
This loads the extension and performs the installation as expected.

======Removing an extension======
The last command under this category is the <tt>extension:remove</tt> command that is used to remove extensions from the Joomla CMS. This command takes in the <tt>extension_id</tt> as an argument, you can always use the <tt>extension:list</tt> to display extension id. This is how we remove an extension of id <tt>803</tt><br/>
<tt>php cli/joomla.php extension:remove 803</tt>
[[File:Extension Remove.png|center|800px]]

====Updating the Joomla Core====
As much as the CLI Update provides a command to check update, it also provides a command to perform the update if an update is available. To perform update we will just run this:<br/>
<tt>php cli/joomla.php core:update</tt><br/>
This command updates the Joomla core updating it to the latest version available.

====Installing Joomla! via the CLI====
The next command here is the <tt>core:intall</tt> command that lets installation of Joomla CMS to be done via the CLI. This command can work in 2 modes: The Interactive mode and the Non-interactive mode.

=====Interactive installation=====
To have a fresh installation of Joomla using the interactive mode we will just run the <tt>extension:install</tt> command like so:<br/>
<tt>php cli/joomla.php extension:install</tt>

The default installation mode will run and will ask you to input the settings as it's required, once all options have been provided and validated, the installations will run and Joomla will be installed.

[[File:Core install interactive.png|center|800px]]

=====Non-interactive Installation=====
The next type of installation is the Non-interactive mode. In this mode you will not be asked to input the options but rather all options will be specified within a file and the command will take in an option that specifies the path to the file you want to load the options from, it's done like this:<br/>
<tt>php cli/joomla.php core:install --file=/path/to/config.json</tt>

[[File:Core install file.png|center|800px]]

An example of the contents of <tt>config.json</tt> can be:<br/>
<source lang="json">
{
"language":"en-GB",
"site_name":"Joomla",
"admin_email":"email@example.com",
"admin_user":"user",
"admin_password":"password",
"db_type":"mysql",
"db_host":"localhost",
"db_user":"root",
"db_pass":"xcdxcx",
"db_name":"jtest",
"db_prefix":"efs0k_",
"db_old":"remove",
"helpurl":"https://joomla.org"
}
</source>

OR as sample <tt>config.ini</tt>

<source lang="ini">
site_name="gsoc"
admin_email="user@example.com"
admin_user="user"
admin_password="secret"
db_type="mysql"
db_host="localhost"
db_user="root"
db_pass=""
db_name="joomla"
db_prefix="prefix_"
</source>

The options defined are loaded and validated after which the installation will run.

====
Configuration based commands====
The next set of commands we will be looking at is for setting and viewing configuration options inside the Joomla installation:

=====Setting configurations=====
The CLI Update provides a command to change the value of an option existing in the configuration. Using the <tt>config:get</tt> command you can set any configuration option that exists inside the <tt>configuration.php</tt>. This is how to use command:<br/>
<tt>php cli/joomla.php config:set mailer=mail</tt>

[[File:Config set single.png|center|800px]]

You can even add multiple option-value pairs like this:<br/>
<tt>php cli/joomla.php config:set mailer=mail fromname=Joomla!</tt>
This will set multiple options at once.

[[File:Config set multiple.png|center|800px]]

=====Getting configurations=====
The next command in this category is the <tt>config:get</tt> command, as the name suggests it gets the value of an option that exists inside the <tt>configuration.php</tt>, when no argument is supplied to the command, it will display all the options available in a tabulated form. Here is the command:<br/>
<tt>php cli/joomla.php config:get sitename</tt>

This will return the value for the option <tt>sitename</tt>.

[[File:011-cli.png|center|800px]]

<tt>php cli/joomla.php config:get</tt>

This will return all the values for the available options.

[[File:Config get all.png|center|800px]]

=====Getting grouped configurations=====
The CLI Update adds an option to <tt>config:get</tt> command that allows us to get logically grouped options, say for example you want to view all your database related options, or you want to view all email related options. To achieve this the CLI Update provides an option to specify a group of options to display, here is how to do that:

<tt>php cli/joomla.php config:get --group=mail</tt>

[[File:Config get group.png|center|800px]]

The command takes in the <tt>group</tt> option and given the value of <tt>mail</tt>. CLI Update currently supports group values: mail, db and session.

====Site down and Site up commands====
As their name suggests, these commands allow you to quickly put your Joomla powered website into offline or online mode. Here is how to use the commands:<br/>
<tt>php cli/joomla.php site:up</tt>

[[File:Site up.png|center|800px]]

<tt>php cli/joomla.php site:down</tt>

[[File:Site down.png|center|800px]]

The second command puts the website in offline mode while the first command brings the website to online mode.

==Contributing to CLI Update as a developer==

===Adding more commands===
The CLI Update ships with some commands which are added based on the need seen as of the time. However, the CLI Update allows other commands to be added easily and this is what this section is for. A video tutorial is included below.

<div class="video-container">
{{#widget:YouTube|id=gcJJtTcPiTg}}
</div>

===Calling other commands within command classes===
Should in case a command you want to write for the CLI Update is going to be require that you call an existing command internally, this is how that can be achieved from within another command class:

<source lang="php">
<?php
class RunHelloCommand extends AbstractCommand {
...

public function execute(): int {
$command = $this->getApplication()->getCommand('say:hello');
$code = $command->execute();

if($code === 0) {
// command ran successfully, do something
}
}

...
}
</source>

Here, we're attempting to call the <tt>say:hello</tt> command created in the Video above.

===Some important things to checkout===
*Symfony Style Documentation: [https://symfony.com/doc/current/console/style.html How to Style a Console Command]

<noinclude>
[[Category:Google Summer of Code 2018]]
[[Category:Development]]
[[Category:Joomla!_4.x]]
</noinclude>

Translations:J4.x:CLI Update/1/fa

2018-08-04T14:37:35Z

Levelup: Created page with "بروز رسانی CLI <br /> مستندات"

بروز رسانی CLI <br /> مستندات

J4.x:Improved Override Management/fa

2018-08-04T14:36:06Z

Levelup: Created page with "== مقدمه =="

<noinclude><languages /></noinclude>
{{Top portal heading|color=white-bkgd|text-color=#333|title=
GSoC 2018 <br />
Improved Override Management <br />Documentation}}
[[Image:Gsoc2016.png|75px|center|link=GSOC 2018]]
<noinclude>{{Joomla version|version=4.x}}</noinclude>
{{-}}
== مقدمه ==
This project adds an update checking feature to Joomla so that if a template overrides core file is changed or updated, it notifies the user that one of the core files of their template overrides is changed with the update, to avoid security issues or functionality issue and they can adjust their override before anyone can notice.

'''Project repository link:''' https://github.com/joomla-projects/gsoc18_override_management

== Getting a head-start with Improved Override Management ==
=== Notes ===
If you are new to Joomla development, and don't know much about Template Manager and Overrides, please read:
#[[S:MyLanguage/J3.x:How_to_use_the_Template_Manager|How to use the Template Manager]]
#[[S:MyLanguage/Layout_Overrides_in_Joomla|Layout Overrides in Joomla]]

Now, if you got familiar with how to use Template Manager and types of Overrides in Joomla. Then, let's go through this project features.
* Supported Overrides
* Diff View
* Override - Quick Icon Notification Plugin
* Installer - Override Plugin
* Updated - Override History

== Types of overrides supported by this feature ==
It does not support Alternative Layout in which filename get renamed to something else and js, css overrides.
This feature supports these override files listed in Create Override tab. Example:
[[File:Selection 035-en.png|center|800px]]

== Diff view between core and override files ==
This feature shows the difference between the core file and the override file. When you open any override file to edit you can see two buttons or switchers in the top right corner of the page if core file of that file is exited.

Buttons like this:
[[File:Selection 027-en.png|center|Buttons]]
Here, you can control the hide and show view of diff view and core file view.
In the next image, you will see the location of the core file and diff view in the template manager.
[[File:Selection 028-en.png|center|800px]]
You can not edit the core file.

=== How diff view is working ===
When you click on any override file to edit it, it calls a function method <tt>getCoreFile</tt> which receives the two parameters <tt>path</tt> of the override file in the template. Example : <tt>/html/layouts/joomla/form/field/user.php</tt> and the client path of the file whether it belongs to <tt>Site</tt> or <tt>Administrator</tt>. Then, based on these information it returns the path of the core file if it exists.
For showing the diff between the core and override files we used [https://github.com/kpdecker/jsdiff jsdiff] library.

== Override - Quick Icon Notification Plugin ==
A quick icon notification plugin which shows the notification in cpanel and it shows the total updated overrides from all templates. When overrides are updated then the quick icon shows something like in the example below:
[[File:Selection 020-en.png|center|Quick Icon|800px]]
When you click on it, it will redirect you to Templates which contain the list of your templates with their description. You'll see a new column header '''Overrides''' showing the number of override updated which belongs to the template. If nothing has been updated in the template override it will show a Up to date badge.
[[File:Selection 022-en.png|center|Templates|800px]]

=== How quick icon is working ===
It makes an AJAX call to the <tt>TemplateController.php</tt> which returns the information and displays a notification when such overrides are updated.

'''Warning'''

Quick icon notification plugin only works or able to fetch data if <tt>installer/override</tt> plugin is enabled. If <tt>installer/override</tt> is disabled then you will see this error message in quick icon.
[[File:Selection 024-en.png|center|Enable|800px]]
If you click on the quick icon you will be redirected to the <tt>installer/override</tt> plugin settings where you can edit the settings of the plugin.
== Installer - Override Plugin ==
This plugin is the main part of this feature. It allows to find the correct updated overrides during the extension install or update and Joomla update.

[[File:Selection 025-en.png|center|Installer Override|800px]]

=== How installer override plugin is working ===
This plugin works on 6 events:
*onExtensionBeforeUpdate
*onExtensionAfterUpdate
*onInstallerBeforeInstaller
*onInstallerAfterInstaller
*onJoomlaBeforeUpdate
*onJoomlaAfterUpdate
Which collect all overrides core file <tt>md5_file()</tt> hash before update and after update then compairs both values. Then, find the correct changed or updated file. And, store information in <tt>#__templates_overrides</tt> table.

== Updated - Override History ==
You can access this from the Updated Files tab in a template.
This is a list view that shows the list of updated overrides which do belongs to that template.
[[File:Selection 029-en.png|center|800px]]

There are many options available to manage list. Where you can check the status of override file history whether is checked or not, created date, date of change and update action like: whether it belongs to (Joomla Update, Extension Update or Extension Install).

'''Note'''

These information are only history so if you checked the updated override changes then, you can delete the history, as not needed anymore.

<noinclude>
[[Category:Google Summer of Code 2018{{#translation:}}]]
[[Category:Development{{#translation:}}]]
[[Category:Joomla!_4.x{{#translation:}}]]
[[Category:Tutorials{{#translation:}}]]
</noinclude>

Translations:J4.x:Improved Override Management/2/fa

2018-08-04T14:36:06Z

Levelup: Created page with "== مقدمه =="

== مقدمه ==

J3.x:Upgrading from Joomla 3.4.x to 3.5/fa

2016-03-12T20:07:24Z

Levelup: Created page with "شما باید جهت بروزرسانی از طریق کامپوننت بروزرسانی جوملا یا به وسیله ی عمل دستی چنانچه از این پس ن..."

<noinclude><languages /></noinclude>
<br />{{note|مهم ! بروزرسانی از 3.5.x به 3.5 نمی تواند به وسیله ی مدیریت افزونه ها انجام گیرد <br />شما باید جهت بروزرسانی از طریق کامپوننت بروزرسانی جوملا یا به وسیله ی عمل دستی چنانچه از این پس نشان داده می شود اقدام کنید|type=serious}}

{{tip|title=Before updating, always take a [[S:Mylanguage/Backup|backup]] and don’t forget to test it.}}
<noinclude>{{Joomla version|version=3.x}}</noinclude>
Preferably you update your Joomla! Installation by using the Joomla! Update component and use the fix database option via '''Extension'''{{rarr}}'''Manage'''{{rarr}}'''Database''' and select the '''Fix''' button on the top left.

If you can’t update your Joomla! Installation in the prefered way because of hosting limitations or connection issues. You need to follow these steps :
#Download the update package from (link)
#Extract the download package on your computer
#Upload the content of the extracted download package to the root or the folder where your Joomla! Installation is.
#Log in to your Joomla! Administrator panel and go to '''Extension'''{{rarr}}'''Manage'''{{rarr}}'''Database''' and select the '''Fix''' button on the top left.
#Go within the manage section to ''Discover'' menu item in the left menu and click the '''Discover''' button. Install any Joomla! extension shown in the list by pressing the ''Install'' button.
#In the main menu of your administrator panel, go to '''System'''{{rarr}}'''Clear Cache''' and if any rows are shown, select them and click the '''Clear cache''' button.

<noinclude>
[[Category:Version 3.x FAQ]]
[[Category:Version 3.5 FAQ]]
[[Category:Joomla! 3.x]]
[[Category:Joomla! 3.5]]
[[Category:Update]]
[[Category:FAQ]]
</noinclude>

Translations:J3.x:Upgrading from Joomla 3.4.x to 3.5/10/fa

2016-03-12T20:07:24Z

شما باید جهت بروزرسانی از طریق کامپوننت بروزرسانی جوملا یا به وسیله ی عمل دستی چنانچه از این پس نشان داده می شود اقدام کنید

J3.x:Upgrading from Joomla 3.4.x to 3.5/fa

2016-03-12T19:41:08Z

Levelup: Created page with "مهم ! بروزرسانی از 3.5.x به 3.5 نمی تواند به وسیله ی مدیریت افزونه ها انجام گیرد"

<noinclude><languages /></noinclude>
<br />{{note|مهم ! بروزرسانی از 3.5.x به 3.5 نمی تواند به وسیله ی مدیریت افزونه ها انجام گیرد <br />You have to update via the Joomla! Update component or by manual action as indicated hereafter.|type=serious}}

{{tip|title=Before updating, always take a [[S:Mylanguage/Backup|backup]] and don’t forget to test it.}}
<noinclude>{{Joomla version|version=3.x}}</noinclude>
Preferably you update your Joomla! Installation by using the Joomla! Update component and use the fix database option via '''Extension'''{{rarr}}'''Manage'''{{rarr}}'''Database''' and select the '''Fix''' button on the top left.

If you can’t update your Joomla! Installation in the prefered way because of hosting limitations or connection issues. You need to follow these steps :
#Download the update package from (link)
#Extract the download package on your computer
#Upload the content of the extracted download package to the root or the folder where your Joomla! Installation is.
#Log in to your Joomla! Administrator panel and go to '''Extension'''{{rarr}}'''Manage'''{{rarr}}'''Database''' and select the '''Fix''' button on the top left.
#Go within the manage section to ''Discover'' menu item in the left menu and click the '''Discover''' button. Install any Joomla! extension shown in the list by pressing the ''Install'' button.
#In the main menu of your administrator panel, go to '''System'''{{rarr}}'''Clear Cache''' and if any rows are shown, select them and click the '''Clear cache''' button.

<noinclude>
[[Category:Version 3.x FAQ]]
[[Category:Version 3.5 FAQ]]
[[Category:Joomla! 3.x]]
[[Category:Joomla! 3.5]]
[[Category:Update]]
[[Category:FAQ]]
</noinclude>

Translations:J3.x:Upgrading from Joomla 3.4.x to 3.5/9/fa

2016-03-12T19:41:07Z

Levelup: Created page with "مهم ! بروزرسانی از 3.5.x به 3.5 نمی تواند به وسیله ی مدیریت افزونه ها انجام گیرد"

مهم ! بروزرسانی از 3.5.x به 3.5 نمی تواند به وسیله ی مدیریت افزونه ها انجام گیرد

J3.x:Upgrading from Joomla 3.4.x to 3.5/fa

2016-03-12T19:38:01Z

Levelup: Created page with "J3.x : بروزرسانی از جوملا 3.4.x به 3.5"

<noinclude><languages /></noinclude>
<br />{{note|'''IMPORTANT! Updating from 3.4.x to 3.5 cannot be done by the extension manager.''' <br />You have to update via the Joomla! Update component or by manual action as indicated hereafter.|type=serious}}

{{tip|title=Before updating, always take a [[S:Mylanguage/Backup|backup]] and don’t forget to test it.}}
<noinclude>{{Joomla version|version=3.x}}</noinclude>
Preferably you update your Joomla! Installation by using the Joomla! Update component and use the fix database option via '''Extension'''{{rarr}}'''Manage'''{{rarr}}'''Database''' and select the '''Fix''' button on the top left.

If you can’t update your Joomla! Installation in the prefered way because of hosting limitations or connection issues. You need to follow these steps :
#Download the update package from (link)
#Extract the download package on your computer
#Upload the content of the extracted download package to the root or the folder where your Joomla! Installation is.
#Log in to your Joomla! Administrator panel and go to '''Extension'''{{rarr}}'''Manage'''{{rarr}}'''Database''' and select the '''Fix''' button on the top left.
#Go within the manage section to ''Discover'' menu item in the left menu and click the '''Discover''' button. Install any Joomla! extension shown in the list by pressing the ''Install'' button.
#In the main menu of your administrator panel, go to '''System'''{{rarr}}'''Clear Cache''' and if any rows are shown, select them and click the '''Clear cache''' button.

<noinclude>
[[Category:Version 3.x FAQ]]
[[Category:Version 3.5 FAQ]]
[[Category:Joomla! 3.x]]
[[Category:Joomla! 3.5]]
[[Category:Update]]
[[Category:FAQ]]
</noinclude>

Translations:J3.x:Upgrading from Joomla 3.4.x to 3.5/Page display title/fa

2016-03-12T19:38:01Z

Levelup: Created page with "J3.x : بروزرسانی از جوملا 3.4.x به 3.5"

J3.x : بروزرسانی از جوملا 3.4.x به 3.5

Understanding Joomla! templates/fa

2015-05-26T19:22:26Z

Levelup: Created page with "دسته بندی:قالب ها دسته بندی:خودآموز"

<noinclude><languages /></noinclude>
{{version|1.5,2.5,3.x}}

{{:What is the typical template directory structure?/fa|What is the typical template directory structure?}}

{{:What is the purpose of the templateDetails.xml file?/fa|What is the purpose of the templateDetails.xml file?}}

{{:What is the purpose of the index.php file?/fa|What is the purpose of the index.php file?}}

<noinclude>
[[دسته بندی:قالب ها]]
[[دسته بندی:خودآموز]]
</noinclude>

Translations:Understanding Joomla! templates/4/fa

2015-05-26T19:22:26Z

Levelup: Created page with "دسته بندی:قالب ها دسته بندی:خودآموز"

[[دسته بندی:قالب ها]]
[[دسته بندی:خودآموز]]

Understanding Joomla! templates/fa

2015-05-26T19:21:43Z