Joomla! Documentation - User contributions [en]

How do you add a PayPal button?

2024-01-13T18:24:51Z

Cmb: URL update. Other markup changes.

<noinclude><languages /></noinclude>
{{Joomla version|version=3.x}}{{Joomla version|version=2.5|status=eos}}
<translate>
PayPal, Google Checkout and other ecommerce sites often provide HTML code that you can use to insert links such as ''Add to Cart'' and ''Buy Now'' buttons into your Website.</translate>

<translate>
It is generally preferable to create a Custom HTML module instead of just pasting the code into an article. This way you can put the link in a module position on as many page as you like. You can also put the module inside an article using the [[S:MyLanguage/How_do_you_put_a_module_inside_an_article%3F|{loadposition myposition}]] command.</translate>

<translate>
== PayPal Technical Documentation == 
</translate>
<translate>
Specifications and examples of the HTML code are shown in the [https://developer.paypal.com/api/nvp-soap/paypal-payments-standard/integration-guide/pps-integration/ PayPal Payments Standard Integration Guide].</translate>

<translate>
== HTML Editor Pitfalls == 
</translate>
<translate>
You can insert this type of HTML code, including forms, either inside an Article or in a Custom HTML Module. However, the TinyMCE editor will normally strip out HTML code. If you try to paste in some types of HTML code using this editor, it will not work; the editor will remove the code when you save the Article or Module.</translate>
<translate>
=== TinyMCE Editor Solution === 
</translate>
<translate>
To avoid this problem while using the TinyMCE editor:</translate>
<translate>
#Go to the User Manager and change the User Editor to ''No editor''.</translate>
<translate>
#Go to the article or Custom HTML module and paste in the desired HTML code.</translate>
<translate>
#Go back to the User Manager and change the User Editor back to TinyMCE.</translate>
<translate>
Note that you will need to repeat this any time you want to edit the code (unless you use the alternate solution below).</translate>
<translate>
=== JCE Editor Solution === 
</translate>
<translate>
#Install the JCE editor from [https://extensions.joomla.org/extension/jce/ the Joomla Extensions Directory]</translate>
<translate>
#Change the default editor {{rarr|Global Configuration,Site,Default WYSIWYG Editor}} to JCE from TinyMCE. You may also need to change the default editor for other users.</translate>
<translate>
#Go to the article or Custom HTML module and hit the ''show/hide'' button, which will change the edit box to allow you to input HTML code instead of WYSIWYG text.</translate>
<translate>
#Paste the HTML code into the editor.</translate>
<translate>
When you navigate back to the article or module in the Backend, it will already be set to HTML input; the code will not get garbled. This is easier than having to change the user settings each time you want to edit the code while you are testing different button settings.</translate>
<translate>

== Email Cloaking Pitfalls == 
</translate>
<translate>
The PayPal code includes an email address for your Website. Joomla! has a Plugin called ''Content - Email Cloaking'' that attempts to disguise emails in Articles. If you wish to paste the PayPal code directly inside an Article, you may need to disable this Plugin. Navigate to {{rarr|Extensions,Plugins}}, find the Plugin ''Content - Email Cloaking'' and click the green checkbox in the Enabled column to disable it.</translate>

<translate>
Plugins are not processed in modules, so should you use a Custom HTML module, you will still be able to have email cloaking enabled.</translate>

<translate>
=== Article-Specific Email Cloaking Switch === 
</translate>
<translate>
You can disable email cloaking in an article by entering ''{emailcloak=off}'' anywhere in the article before the email address. With this control, you do not need to disable global email cloaking.</translate>

<translate>
=== Secure Merchant Account ID in Place of the Email Address === 
</translate>
<translate>
PayPal offers a Secure Merchant Account ID (an alphanumeric string used in place of the merchant email address) at no cost. It is available for Web Payments Standard customers as well as in the extra-cost plans. Email cloaking does not affect the Secure Merchant Account ID.</translate>

<translate>
== PayPal Button Function Invoked by a Joomla Menu Item == 
</translate>
<translate>
You may use a menu item to act as a PayPal button. For example, the PayPal View Cart button simply sends a query string as part of a Uniform Resource Locator (URL) using an HTML form. You can create a Joomla menu item that performs the same function.</translate>

<translate>
In the Menu Item Manager create a new External Link menu item. In the Menu Item Details section, go to the Link field and enter at URL of the form:</translate>

<source lang=text>https://www.paypal.com/us/cgi-bin/webscr&business=myusername@mysite.com&cmd=_cart&display=1</source>

<translate>
Replace ''myusername@mysite.com'' in the URL example above with the unique username of '''your''' PayPal account.</translate>

<translate>
To test the operation in the PayPal Sandbox, simply modify the URL slightly so that ''www.paypal.com'' becomes ''www.sandbox.paypal.com''.</translate>

<source lang=text>https://www.sandbox.paypal.com/us/cgi-bin/webscr&business=myusername@mysite.com&cmd=_cart&display=1</source>

<noinclude>
[[Category:FAQ{{#translation:}}]]
[[Category:Administration FAQ{{#translation:}}]]
[[Category:Article Management{{#translation:}}]]
[[Category:Component Development{{#translation:}}]]
</noinclude>

J4.x:Web Assets

2023-10-25T23:23:16Z

Cmb: Some phrasing and markup changes.

<noinclude><languages /></noinclude>
<translate>
== Concept == 
</translate>

<translate> In the Frontend world many assets are related. For example, our ''keepalive'' script depends on the ''core.js'' file for options management. In Joomla there never was an easy way to specify this; you just had to include multiple files. Joomla 4 changes this with the concept of web assets.</translate>

<translate>
== Definition == 
</translate>

<translate> Related assets are defined in a JSON file such as [https://github.com/joomla/joomla-cms/blob/7b72c565b610e02c1b01f8958d622879631fa6a2/build/media_source/system/joomla.asset.json#L14-L21 system/joomla.asset.json#L14-L21]</translate>

<translate> This has a structure of having a schema definition (for validation), name, version, license and then one or more asset definitions. Assets comprise a list of JavaScript files and CSS files related to the assets and any dependencies. The dependencies section is just a list of asset names that are required for the asset to function. Example:</translate>

<syntaxhighlight lang="json">
{
"$schema": "https://developer.joomla.org/schemas/json-schema/web_assets.json",
"name": "com_example",
"version": "4.0.0",
"description": "Joomla CMS",
"license": "GPL-2.0+",
"assets": [
{
"name": "bar",
"type": "style",
"uri": "com_example/bar.css"
},
{
"name": "bar",
"type": "script",
"uri": "com_example/bar.js"
},
{
"name": "beer",
"type": "style",
"uri": "com_example/beer.css",
"dependencies": [
"bar"
],
},
{
"name": "beer",
"type": "script",
"dependencies": [
"core",
"bar"
],
"uri": "com_example/beer.js",
"attributes": {
"defer": true,
"data-foo": "bar"
}
}
]
}
</syntaxhighlight>

<translate> The <syntaxhighlight lang="json" inline>$schema</syntaxhighlight> attribute is a schema definition file that allows you to validate your file using JSON Schema. Read [https://json-schema.org/understanding-json-schema/index.html the official website] for more information on how JSON schema validation works.</translate>

<translate> '''Note''' Having ''joomla.asset.json'' for your extension or template are recommended but not required for WebAsset to work. (See the next section).</translate>

<translate> '''Note''' It is not recommended to add an inline asset to a JSON file. Prefer to use a file.</translate>

<translate>
== Explaining Asset Stages == 
</translate>

<translate> Each asset has two stages: registered and used.</translate>

<translate>

'''Registered''' is where an asset is loaded into '''WebAssetRegistry'''. That means '''WebAssetManager''' knows about the existence of these assets, but will not attach them to a document while rendering. All assets loaded from joomla.asset.json is at '''registered''' stage.</translate>

<translate> '''Used''' is where an asset is enabled via ''$wa->useAsset()'' (->useScript(), ->useStyle(), ->registerAndUseX() etc). That means '''WebAssetManager''' will attach these assets and their dependencies to a document while rendering.</translate>

<translate> An asset cannot be used if it was not previously registered. This will cause an unknown asset exception.</translate>

<translate>
== Register an Asset == 
</translate>

<translate> All known assets loaded and then stored in '''WebAssetRegistry'''. (To enable/disable an asset item, use '''WebAssetManager'''. See the next section.)</translate>

<translate> Joomla! will look for next assets definition automatically at runtime (in following order):</translate>
<pre>
media/vendor/joomla.asset.json (on first access to WebAssetRegistry)
media/system/joomla.asset.json
media/legacy/joomla.asset.json
media/{com_active_component}/joomla.asset.json (on dispatch the application)
templates/{active_template}/joomla.asset.json
</pre>

<translate> ...and load them to the registry of known assets.</translate>

<translate> '''Note''' Each following assets definition will override asset items from previous assets definition, by item name.</translate>

<translate> You can register your own assets definition via '''WebAssetRegistry''':</translate>

<syntaxhighlight lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();
$wr = $wa->getRegistry();
$wr->addRegistryFile('relative/path/to/your/joomla.asset.json');
</syntaxhighlight>

<translate> To add a custom asset item at runtime:</translate>
<syntaxhighlight lang="php">
$wr->add('script', new Joomla\CMS\WebAsset\WebAssetItem('foobar', 'com_foobar/file.js', ['type' => 'script']));
</syntaxhighlight>

<translate> Or more simply, using '''WebAssetManager''':</translate>
<syntaxhighlight lang="php">
$wa->registerScript('foobar', 'com_foobar/file.js');
</syntaxhighlight>

<translate> The new asset item ''foobar'' will be added to the registry of known assets, but will not be attached to a document until your code (a layout, template etc) requests it.</translate>

<translate> To check whether an asset exists:</translate>
<syntaxhighlight lang="php">
if ($wa->assetExists('script', 'foobar'))
{
var_dump('Script "foobar" exists!');
}
</syntaxhighlight>

<translate>
== Enabling an Asset == 
</translate>
<translate> All asset management in the current document is handled by the '''WebAssetManager''', which is accessible with '''$doc->getWebAssetManager();'''</translate>
<translate> By using AssetManager you can enable or disable needed assets easily in Joomla! through standard methods.</translate>

<translate> To enable an asset in the page, use the ''useAsset'' function:</translate>

<syntaxhighlight lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();
$wa->useScript('keepalive');

// Or multiple
$wa->useScript('keepalive')
->useScript('fields.validate')
->useStyle('foobar')
->useScript('foobar');

// Add the new asset item with dependency and use it
$wa->registerAndUseScript('bar', 'com_foobar/bar.js', [], [], ['core', 'foobar']);
</syntaxhighlight>

<translate> '''WebAssetManager''' will look to '''WebAssetRegistry''' whether the requested asset exists, and will enable it for current Document instance. Otherwise it will throw an UnknownAssetException.</translate>

<translate> To disable an asset in the page use the ''disableAsset'' function. The example below will disable the ''jquery-noconflict'' asset from being loaded.</translate>

<syntaxhighlight lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();
$wa->disableScript('jquery-noconflict');
</syntaxhighlight>

<translate> '''Note''' If there are any dependencies to the disabled asset, this asset will be re-enabled automatically, no matter what.</translate>

<translate> To check whether an asset is enabled, and determine the asset state:</translate>

<syntaxhighlight lang="php">
// Checking whether an asset are active (enabled manually or automatically as dependency).
if ($wa->isAssetActive('script', 'foobar'))
{
var_dump('Script "foobar" is active!');
}

// Checking state
switch($wa->getAssetState('script', 'foobar')){
case Joomla\CMS\WebAsset\WebAssetManager::ASSET_STATE_ACTIVE:
var_dump('Active! Was enabled manually');
break;
case Joomla\CMS\WebAsset\WebAssetManager::ASSET_STATE_DEPENDENCY:
var_dump('Active! Was enabled automatically while resolving dependencies');
break;
default:
var_dump('not active!');
}
</syntaxhighlight>

<translate>
== Overriding an Asset == 
</translate>

<translate>
Overriding may be useful when you need to redefine the URI of an asset item or its dependencies.
As already noted, each of the following asset definitions from the ''joomla.asset.json'' file will override asset items from previous assets definitions, by item name.</translate>
<translate>
If you provide a ''joomla.asset.json'' file that contains already-loaded asset items, they will be replaced with your items.
Another way to override in the code is to register an item with the same name.
Example: we have ''foobar'' script, that loads the ''com_example/foobar.js'' library, and we want to use CDN for this exact library:</translate>

<translate> How it defined in the system initially:</translate>

<syntaxhighlight lang="json">
...
{
"name": "foobar",
"type": "script",
"uri": "com_example/foobar.js",
"dependencies": ["core"]
}
...
</syntaxhighlight>

<translate> To override the URI, we define the asset item with ''foobar'' name in our ''joomla.asset.json'':</translate>

<syntaxhighlight lang="json">
...
{
"name": "foobar",
"type": "script",
"uri": "http://foobar.cdn.blabla/foobar.js",
"dependencies": ["core"]
}
...
</syntaxhighlight>

<translate> Or, register a new asset item with the AssetManager:</translate>

<syntaxhighlight lang="php">
$wa->registerScript('foobar', 'http://fobar.cdn.blabla/foobar.js', [], [], ['core']);
</syntaxhighlight>

<translate>
== Working with Styles == 
</translate>

<translate> The Asset Manager allows you to manage style sheet files. Style sheet asset items have a type ''style''.</translate>

<translate> Example JSON definition of item in ''joomla.asset.json'':</translate>

<syntaxhighlight lang="json">
...
{
"name": "foobar",
"type": "style",
"uri": "com_example/foobar.css"
}
...
</syntaxhighlight>

<translate>
=== Methods to Work with Styles === 
</translate>

<translate> AssetManager offers the following methods to work with style files:</translate>

<syntaxhighlight lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();

// Attach foobar to the document
$wa->useStyle('foobar');

// Disable foobar from being attached
$wa->disableStyle('foobar');

// Register custom item without JSON definition
$wa->registerStyle('bar', 'com_example/bar.css', [], ['data-foo' => 'some attribute'], ['some.dependency']);
// And use it later
$wa->useStyle('bar');

// Register and attach a custom item in one run
$wa->registerAndUseStyle('bar', 'com_example/bar.css', [], ['data-foo' => 'some attribute'], ['some.dependency']);
</syntaxhighlight>

<translate>
=== Add Inline Style === 
</translate>

<translate>
Additionally to style files, WebAssetManager allows you to add an inline style, and maintain their relation to the file asset.
Inline styles may be placed directly before the dependency, after the dependency, or as usual after all styles.</translate>

<translate> Inline asset may have a name as well as other assets (but it is not required). The name can be used to retrieve the asset item from a registry, or as a dependency to another inline asset. If the name is not specified, a generated name based on a content hash will be used.</translate>

<syntaxhighlight lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();

// Add an inline content as usual, will be rendered in flow after all assets
$wa->addInlineStyle('content of inline1');

// Add an inline content that will be placed after "foobar" asset
$wa->addInlineStyle('content of inline2', ['position' => 'after'], ['data-foo' => 'bar'], ['foobar']);

// Add an inline content that will be placed before "foobar" asset
$wa->addInlineStyle('content of inline3', ['position' => 'before'], [], ['foobar']);

// Named inline asset
$wa->addInlineStyle('content of inline4', ['name' => 'my.inline.asset']);
</syntaxhighlight>

<translate> '''Note''' The ''foobar'' asset must exist in the asset registry, otherwise you will get an unsatisfied dependency exception.</translate>

<translate> The example above will produce:</translate>

<syntaxhighlight lang="html5">
...
<style>content of inline3</style>
<link rel="stylesheet" href="foobar.css" />
<style data-foo="bar">content of inline2</style>
...
...
<style>content of inline1</style>
<style>content of inline4</style>
...
</syntaxhighlight>

<translate> If an inline asset has multiple dependencies, the last one will be used for positioning. Example:</translate>

<syntaxhighlight lang="php">
$wa->addInlineStyle('content of inline1', ['position' => 'before'], [], ['foo', 'bar']);
$wa->addInlineStyle('content of inline2', ['position' => 'after'], [], ['foo', 'bar']);
</syntaxhighlight>
<translate> Will produce:</translate>

<syntaxhighlight lang="html5">
...
<link rel="stylesheet" href="foo.css" />
<style>content of inline1</style>
<link rel="stylesheet" href="bar.css" />
<style>content of inline2</style>
...
</syntaxhighlight>

<translate> '''Note''' Named inline assets may be a dependency to another inline asset, however it is not recommended to use an inline asset as dependency to non-inline asset. This might work, but this behavior may change in the future. Prefer to use ''position'' instead.</translate>

<translate>
== Working with Scripts == 
</translate>

<translate> The AssetManager allows you to manage JavaScript files. Script asset items have a type ''script''.</translate>
<translate> Example JSON definition of item in ''joomla.asset.json'':</translate>
<syntaxhighlight lang="json">
...
{
"name": "foobar",
"type": "script",
"uri": "com_example/foobar.js",
"dependencies": ["core"]
}
...
</syntaxhighlight>

<translate> An example JSON definition of ES6 module script, with fallback to legacy:</translate>

<syntaxhighlight lang="json">
...
{
"name": "foobar-legacy",
"type": "script",
"uri": "com_example/foobar-as5.js",
"attributes": {
"nomodule": true,
"defer": true
},
"dependencies": ["core"]
}
{
"name": "foobar",
"type": "script",
"uri": "com_example/foobar.js",
"attributes": {
"type": "module"
},
"dependencies": [
"core",
"foobar-legacy"
]
}
...
</syntaxhighlight>

<translate>
=== Methods to Work with Scripts === 
</translate>

<translate>
The AssetManager offers these methods to work with script files:</translate>

<syntaxhighlight lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();

// Attach foobar to the document
$wa->useScript('foobar');

// Disable foobar from being attached
$wa->disableScript('foobar');

// Register custom item without JSON definition
$wa->registerScript('bar', 'com_example/bar.js', [], ['defer' => true], ['core']);
// And use it later
$wa->useScript('bar');

// Register and attach a custom item in one run
$wa->registerAndUseScript('bar','com_example/bar.js', [], ['defer' => true], ['core']);
</syntaxhighlight>

<translate>
=== Add Inline Script === 
</translate>

<translate>
In addition to script files, the WebAssetManager allows you to add an inline script, and maintain their relation to the file asset.
Inline script may be placed directly before the dependency, after the dependency, or as usual after all scripts.</translate>

<translate> Inline asset may have a name as well as other assets (but not required). The name can be used to retrieve the asset item form a registry, or as dependency to another inline asset. If a name is not specified, a generated name based on a content hash will be used.</translate>

<syntaxhighlight lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();

// Add an inline content as usual. It will be rendered in flow after all assets.
$wa->addInlineScript('content of inline1');

// Add an inline content that will be placed after "foobar" asset
$wa->addInlineScript('content of inline2', ['position' => 'after'], ['data-foo' => 'bar'], ['foobar']);

// Add an inline content that will be placed before "foobar" asset
$wa->addInlineScript('content of inline3', ['position' => 'before'], [], ['foobar']);

// Named inline asset
$wa->addInlineScript('content of inline4', ['name' => 'my.inline.asset']);

// Specify script type
$wa->addInlineScript('content of inline5', [], ['type' => 'module']);
</syntaxhighlight>

<translate> '''Note''' The ''foobar'' asset should exist in the asset registry, otherwise you will get an unsatisfied dependency exception.</translate>

<translate> Example above will produce:</translate>

<syntaxhighlight lang="html5">
...
<script>content of inline3</script>
<script src="foobar.js"></script>
<script data-foo="bar">content of inline2</script>
...
...
<script>content of inline1</script>
<script>content of inline4</script>
<script type="module">content of inline5</script>
...
</syntaxhighlight>

<translate> If an inline asset has multiple dependencies, the last one will be used for positioning. Example:</translate>

<syntaxhighlight lang="php">
$wa->addInlineScript('content of inline1', ['position' => 'before'], [], ['foo', 'bar']);
$wa->addInlineScript('content of inline2', ['position' => 'after'], [], ['foo', 'bar']);
</syntaxhighlight>

<translate> Will produce:</translate>

<syntaxhighlight lang="html5">
...
<script src="foo.js"></script>
<script>content of inline1</script>
<script src="bar.js"></script>
<script>content of inline2</script>
...
</syntaxhighlight>

<translate> '''Note''' Named inline assets may be a dependency on another inline asset. It is not recommended to use an inline asset as dependency to non-inline asset. This might work, but this behavior may changes in future. Prefer to use ''position'' instead.</translate>

<translate>
== Working with a Web Component == 
</translate>

<translate>
Joomla! allows you to use [https://developer.mozilla.org/en-US/docs/Web/Web_Components Web Components] for your needs. In Joomla! Web Components are not loaded as regular scripts, but loaded via the Web Component loader so that they are loaded asynchronously. Therefore, a Web Component asset item must have a flag ''webcomponent'' set to the boolean ''true''.
In all other aspects, working with Web Components in the AssetManager is the same as working with a ''script'' asset item.</translate>

<translate> Example JSON definitions of some Web Components in the ''joomla.asset.json'' file (as ES6 module):</translate>

<syntaxhighlight lang="json">
...
{
"name": "webcomponent.foobar",
"type": "style",
"uri": "com_example/foobar-custom-element.css",
},
{
"name": "webcomponent.foobar",
"type": "script",
"uri": "com_example/foobar-custom-element.js",
"attributes": {
"type": "module"
},
}
...
</syntaxhighlight>

<translate> Example with fallback, for browsers that do not support ES6 "module" feature. Note that the legacy script should have ''wcpolyfill'' dependency, and module script should have dependency from the legacy script:</translate>

<syntaxhighlight lang="json">
...
{
"name": "webcomponent.foobar",
"type": "style",
"uri": "com_example/foobar-custom-element.css",
},
{
"name": "webcomponent.foobar-legacy",
"type": "script",
"uri": "com_example/foobar-custom-element-es5.js",
"attributes": {
"nomodule": true,
"defer": true
},
"dependencies": [
"wcpolyfill"
]
},
{
"name": "webcomponent.foobar",
"type": "script",
"uri": "com_example/foobar-custom-element.js",
"attributes": {
"type": "module"
},
"dependencies": [
"webcomponent.foobar-legacy"
]
}
...
</syntaxhighlight>

<translate> Alternatively you can register them in PHP (as an ES6 module):</translate>

<syntaxhighlight lang="php">
$wa->registerStyle('webcomponent.foobar', 'com_example/foobar-custom-element.css')
->registerScript('webcomponent.foobar', 'com_example/foobar-custom-element.js', ['type' => 'module']);
</syntaxhighlight>

<translate> Attach to document:</translate>

<syntaxhighlight lang="php">
$wa->useStyle('webcomponent.foobar')
->useScript('webcomponent.foobar');
</syntaxhighlight>

<translate>

'''Note''' It is preferred to prefix the asset name with ''webcomponent.'' to make it easy to spot, and distinguish it from regular scripts in a layout.</translate>

<translate>
=== Methods to Work with Web Component === 
</translate>

<translate> All methods to work with a Web Component are the same as methods to work with script asset items.</translate>

<translate>
== Working with a Presets == 
</translate>

<translate>
A ''preset'' is a special kind of asset item that holds a list of items to be enabled, in the same way as a direct call of ''useAsset()'' to each of item in the list.
Presets can hold mixed types of assets (script, style, another preset, etc.). The type should be provided after a # symbol and follows after an asset name. Example: foo#style, bar#script.</translate>

<translate> Example of a JSON definition of an item in ''joomla.asset.json'':</translate>

<syntaxhighlight lang="json">
...
{
"name": "foobar",
"type": "preset",
"uri": "",
"dependencies": [
"core#script",
"foobar#style",
"foobar#script",
]
}
...
</syntaxhighlight>

<translate>
=== Methods to Work with Preset === 
</translate>

<translate> The AssetManager offers these methods to work with preset items:</translate>

<syntaxhighlight lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();

// Attach all items from foobar preset to the document
$wa->usePreset('foobar');

// Disable all items from foobar preset from being attached
$wa->disablePreset('foobar');

// Register custom item without JSON definition
$wa->registerPreset('bar', '', [], [], ['core#script', 'bar#script']);

// And use it later
$wa->usePreset('bar');

// Register and attach a custom item in one run
$wa->registerAndUsePreset('bar','', [], [], ['core#script', 'bar#script']);
</syntaxhighlight>

<translate>
== Advanced: Custom WebAssetItem Class == 
</translate>

<translate> The default class for all WebAsset items is '''Joomla\CMS\WebAsset\WebAssetItem'''.</translate>

<translate> You are also allowed to use a custom class, which must implement '''Joomla\CMS\WebAsset\WebAssetItemInterface''' or extend '''Joomla\CMS\WebAsset\WebAssetItem'''.</translate>

<translate> A custom class allows you to do advanced actions. For example, including a script file depending on an active language:</translate>

<syntaxhighlight lang="php">
class MyComExampleAssetItem extends WebAssetItem
{
public function getUri($resolvePath = true): string
{
$langTag = Factory::getApplication()->getLanguage()->getTag();
// For script asset use ".js", for style we would use ".css"
$path = 'com_example/bar-' . $langTag . '.js';

if ($resolvePath)
{
// For script asset use "script", for style we would use "stylesheet"
$path = $this->resolvePath($path, 'script');
}

return $path;
}
}
</syntaxhighlight>

<translate> Additionally, implementing ''Joomla\CMS\WebAsset\WebAssetAttachBehaviorInterface'' allows you to add script options (which may depend on the environment) when your asset is enabled and attached to the Document.</translate>

<syntaxhighlight lang="php">
class MyFancyFoobarAssetItem extends WebAssetItem implements WebAssetAttachBehaviorInterface
{
public function onAttachCallback(Document $doc): void
{
$user = Factory::getApplication()->getIdentity();
$doc->addScriptOptions('com_example.fancyfoobar', ['userName' => $user->username]);
}
}
</syntaxhighlight>

<translate> '''Important Note''' An asset item that implements ''WebAssetAttachBehaviorInterface'' should be enabled before a [https://docs.joomla.org/Plugin/Events/System#onBeforeCompileHead onBeforeCompileHead] event, otherwise ''onAttachCallback'' will be ignored.</translate>

<translate>
=== Defining a Custom WebAssetItem Class in ''joomla.asset.json'' === 
</translate>

<translate>
In joomla.asset.json you can define which Class should be used with a specific Asset Item.
For this you can use two properties ''namespace'' and ''class''. ''namespace'' can be defined at the Root level. Then it will be used as default namespace for all Asset items in the ''joomla.asset.json'' file or in the Item level. For example:</translate>

<syntaxhighlight lang="json">
{
"$schema": "https://developer.joomla.org/schemas/json-schema/web_assets.json",
"name": "com_example",
"version": "4.0.0",
"namespace": "Joomla\Component\Example\WebAsset",
"assets": [
{
"name": "foo",
"type": "script",
"class": "FooAssetItem",
"uri": "com_example/foo.js"
},
{
"name": "bar",
"type": "script",
"namespace": "MyFooBar\Library\Example\WebAsset",
"class": "BarAssetItem",
"uri": "com_example/bar.js"
}
]
}
</syntaxhighlight>

<translate> Here the asset ''foo'' will be associated with class ''Joomla\Component\Example\WebAsset\FooAssetItem'', and ''bar'' with class ''MyFooBar\Library\Example\WebAsset\BarAssetItem''.</translate>

<translate> '''Note''' If ''namespace'' is not defined, by default ''Joomla\CMS\WebAsset'' will be used. When ''namespace'' is defined but empty, no namespace will be used, only ''class'' will be used. Example:</translate>

<syntaxhighlight lang="json">
{
"$schema": "https://developer.joomla.org/schemas/json-schema/web_assets.json",
"name": "com_example",
"assets": [
{
"name": "foo",
"type": "script",
"class": "FooAssetItem",
"uri": "com_example/foo.js"
},
{
"name": "bar",
"type": "script",
"namespace": "",
"class": "BarAssetItem",
"uri": "com_example/bar.js"
}
]
}
</syntaxhighlight>

<translate> Here the asset ''foo'' will be associated with class ''Joomla\CMS\WebAsset\FooAssetItem'', and ''bar'' with class ''BarAssetItem'' (without a namespace).</translate>

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

Standard Module Chromes

2023-10-09T21:04:42Z

Cmb: Replaced deprecated 'source' tags with 'syntaxhighlight' tags. Other markup changes.

<noinclude><languages /></noinclude>
<translate>
Note that this example includes class additions because the examples are taken using ''mod_mainmenu''. The suffix "_menu" on the div class and the ''menu'' class on the unordered list (ul) tag are not present with other modules.</translate>

{| style="width:100%" class="wikitable"
|+ '''<translate>
Comparison of the Joomla! standard Module chromes</translate>'''
<translate>
These are the same from Joomla! 1.5 through 3.x</translate>
!width="100" | <translate>
Style</translate>
!<translate>
Output</translate>
!width="210" | <translate>
Appearance</translate>
|-
!<translate>
rounded</translate><br />
|<syntaxhighlight lang="html4strict">
<div class="module_menu">
<div>
<div>
<div>
<h3>Main Menu</h3>
<ul class="menu">
<li></li>
</ul>
</div>
</div>
</div>
</div>
</syntaxhighlight>
|[[Image:Module_chrome_rounded.png]]
|-
!<translate>
none</translate>
|<syntaxhighlight lang="html4strict">
<ul class="menu">
<li></li>
</ul>
</syntaxhighlight>
|
[[Image:Module_chrome_none.png]]
|-
!<translate>
table</translate>
|<syntaxhighlight lang="html4strict">
<table cellpadding="0" cellspacing="0" class="moduletable_menu">
<tr>
<th valign="top">Main Menu</th>
</tr>
<tr>
<td>
<ul class="menu">
<li></li>
</ul>
</td>
</tr>
</table>
</syntaxhighlight>
|[[Image:Module_chrome_table.png]]
|-
!<translate>
horz</translate>
|<syntaxhighlight lang="html4strict">
<table cellspacing="1" cellpadding="0" border="0" width="100%">
<tr>
<td valign="top">
<table cellpadding="0" cellspacing="0" class="moduletable_menu">
<tr>
<th valign="top">Main Menu</th>
</tr>
<tr>
<td>
<ul class="menu">
<li></li>
</ul>
</td>
</tr>
</table>
</td>
</tr>
</table>
</syntaxhighlight>
|[[Image:Module_chrome_horz.png]]
|-
!xhtml
|<syntaxhighlight lang="html4strict">
<div class="moduletable_menu">
<h3>Main Menu</h3>
<ul class="menu">
<li></li>
</ul>
</div>
</syntaxhighlight>
|[[Image:Module_chrome_xhtml.png]]
|-
!html5
|
<syntaxhighlight lang="html4strict">
<div class="well _menu">
<h3 class="page-header">Main Menu</h3>
<ul class="nav menu">
<li></li>
</ul>
</div>
</syntaxhighlightv>
|[[Image:Module_chrome_html5.png]]
|-
!<translate>
outline</translate>
|<syntaxhighlight lang="html4strict">
<div class="mod-preview">
<div class="mod-preview-info">left[outline]</div>
<div class="mod-preview-wrapper">
<ul class="menu">
<li></li>
</ul>
</div>
</div>
</syntaxhighlight>
| [[Image:Module_chrome_outline.png]]
|-
|}

<translate>
Note that the Module chrome doesn't change the appearance all that much—this depends on the CSS used in the template. For example, the ''none'' and ''horz'' chromes look similar, although the underlying HTML code is different.</translate>

<translate>
Other notes: The ''horz'' is just the ''table'' layout, wrapped in a ''table'', ''tr'', and ''td''.</translate>

<translate>
Until Joomla! 3: The software controlling these is in the file</translate> ''/templates/system/html/modules.php''.

'''Changes since Joomla! 4'''
* The standard chromes ''horz'', ''rounded'' and ''xhtml'' have been removed from core.
* The core module chromes are controlled by ''JLayout'' files in directory ''/layouts/chromes/''.

<noinclude>
<translate>

[[Category:Advanced|Chrome]]
[[Category:Module Development]]
[[Category:Template Development]]
[[Category:CSS]]
</translate>
</noinclude>

J4.x:Using Bootstrap Components in Joomla 4

2023-09-24T20:45:28Z

Cmb: Several markup changes.

== Introduction ==

=== Bootstrap Components ===
Some of the components described in the Bootstrap documentation use CSS only. For example, the Breadcrumbs component is rendered with CSS and requires no JavaScript support. Others respond to user actions such as click or hover, and need JavaScript support. The latter are referred to here as Interactive Components. This article explains how to use them in Articles and a Custom Module.

See: [https://getbootstrap.com/docs/5.0/getting-started/introduction/ Bootstrap Documentation]

=== Joomla 4 Introduces a Modular Approach for Interactive Components ===
* What is a modular approach?
* The functionality is broken down into individual components supported by individual files. There is no '''one file''' approach as it was with Bootstrap in Joomla 3. The modular approach is more efficient and offers performance gains. (Send only the code that is needed instead of delivering everything in case some page will need some component.)

=== Using Interactive Components: Coders ===
* Load what you need per case! There are helper functions to set up individual components with appropriate arguments.
* See the list of Bootstrap Interactive Components.

=== Using Interactive Components: Non-Coders ===
* Using components in articles is not so easy because the helper functions cannot be called from an article or standard Custom HTML module. Three possible solutions are suggested later in this tutorial:
** A custom module
** A custom plugin
** A custom module override
* Skip or scan the list of Bootstrap Interactive Components. You won't be using these function calls directly.

== Bootstrap Interactive Components ==
=== Alert ===
Assuming you have the HTML part already in your Layout, you will also need to include the interactivity (the JavaScript part):

<pre>
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.alert', '.selector');
</pre>

* The '''.selector''' refers to the CSS selector for the alert. You can call this function multiple times with different CSS selectors
* No extra options available

=== Button ===
Assuming you have the HTML part already in your Layout, you will also need to include the interactivity (the JavaScript part):

<pre>
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.button', '.selector');
</pre>

* The '''.selector''' refers to the CSS selector for the button. You can call this function multiple times with different CSS selectors
* No extra options available

=== Carousel ===
Assuming you have the HTML part already in your Layout, you will also need to include the interactivity (the JavaScript part):

<pre>
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.carousel', '.selector', []);
</pre>

* The '''.selector''' refers to the CSS selector for the carousel. You can call this function multiple times with different CSS selectors
* The third argument refers to the options available for carousel

Options for the carousel can be:
* '''interval''', number, default:'''5000''', The amount of time to delay between automatically cycling an item. If false, carousel will not automatically cycle.
* '''keyboard''', boolean, default:'''true''' Whether the carousel should react to keyboard events.
* '''pause''', string|boolean, '''hover''' Pauses the cycling of the carousel on ''mouseenter'' and resumes the cycling of the carousel on ''mouseleave''.
* '''slide''', string|boolean, default:'''false''' Autoplays the carousel after the user manually cycles the first item. If "carousel", autoplays the carousel on load.

=== Collapse ===
Assuming you have the HTML part already in your Layout, you will also need to include the interactivity (the JavaScript part):

<pre>
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.collapse', '.selector', []);
</pre>

* The '''.selector''' refers to the CSS selector for the collapse. You can call this function multiple times with different CSS selectors
* The third argument refers to the options available for collapse

Options for the collapse can be:
* '''parent''', string, default:'''false''' If parent is provided, then all collapsible elements under the specified parent will be closed when this collapsible item is shown.
* '''toggle''', boolean default:'''true''' Toggles the collapsible element on invocation

=== Dropdown ===
Assuming you have the HTML part already in your Layout, you will also need to include the interactivity (the JavaScript part):

<pre>
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.dropdown', '.selector', []);
</pre>

* The '''.selector''' refers to the CSS selector for the dropdown. You can call this function multiple times with different CSS selectors
* The third argument refers to the options available for dropdown

Options for the collapse can be:
* '''flip''', boolean, default:'''true''' Allow Dropdown to flip in case of an overlapping on the reference element
* '''boundary''', string, default:'''scrollParent''' Overflow constraint boundary of the dropdown menu
* '''reference''', string, default:'''toggle''' Reference element of the dropdown menu. Accepts '''toggle''' or '''parent'''
* '''display''', string, default:'''dynamic''' By default, we use Popper for dynamic positioning. Disable this with '''static'''

=== Modal ===
Assuming you have the HTML part already in your Layout, you will also need to include the interactivity (the JavaScript part):

<pre>
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.modal', '.selector', []);
</pre>

* The '''.selector''' refers to the CSS selector for the modal. You can call this function multiple times with different CSS selectors
* The third argument refers to the options available for modal

Options for the modal can be:
* '''backdrop''', string|boolean default:'''true''' Includes a modal-backdrop element. Alternatively, specify static for a backdrop which doesn't close the modal on click.
* '''keyboard''', boolean default:'''true''' Closes the modal when escape key is pressed
* '''focus''', boolean default:'''true''' Closes the modal when escape key is pressed

=== Offcanvas ===
Assuming you have the HTML part already in your Layout, you will also need to include the interactivity (the JavaScript part):

<pre>
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.offcanvas', '.selector', []);
</pre>

* The '''.selector''' refers to the CSS selector for the offcanvas. You can call this function multiple times with different CSS selectors
* The third argument refers to the options available for offcanvas

Options for the offcanvas can be:
* '''backdrop''', boolean, default:'''true''' Apply a backdrop on body while offcanvas is open
* '''keyboard''', boolean, default:'''true''' Closes the offcanvas when escape key is pressed
* '''scroll''', boolean, default:'''false''' Allow body scrolling while offcanvas is open

=== Popover ===
Assuming you have the HTML part already in your Layout, you will also need to include the interactivity (the JavaScript part):

<pre>
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.popover', '.selector', []);
</pre>

* The '''.selector''' refers to the CSS selector for the popover. You can call this function multiple times with different CSS selectors
* The third argument refers to the options available for popover

Options for the popover can be:
* '''animation''', boolean, default:'''true''' Apply a CSS fade transition to the popover
* '''container''', string|boolean, default:'''false''' Appends the popover to a specific element. Eg.: '''body'''
* '''content''', string, default:'''null''' Default content value if data-bs-content attribute isn't present
* '''delay''', number, default:'''0''' Delay showing and hiding the popover (ms) does not apply to manual trigger type
* '''html''', boolean, default:'''true''' Insert HTML into the popover. If '''false''', innerText property will be used to insert content into the DOM.
* '''placement''', string, default:'''right''' How to position the popover - '''auto''' | '''top''' | '''bottom''' | '''left''' | '''right'''. When auto is specified, it will dynamically reorient the popover
* '''selector''', string, default:'''false''' If a selector is provided, popover objects will be delegated to the specified targets.
* '''template''', string, default:'''null''' Base HTML to use when creating the popover.
* '''title''', string, default:'''null''' Default title value if '''title''' tag isn't present
* '''trigger''', string, default:'''click''' How popover is triggered - '''click''' | '''hover''' | '''focus''' | '''manual'''
* '''offset''', integer, default:'''0''' Offset of the popover relative to its target.

=== Scrollspy ===
Assuming you have the HTML part already in your Layout, you will also need to include the interactivity (the JavaScript part):

<pre>
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.scrollspy', '.selector', []);
</pre>

* The '''.selector''' refers to the CSS selector for the scrollspy. You can call this function multiple times with different CSS selectors
* The third argument refers to the options available for scrollspy

Options for the Scrollspy can be:
* '''offset''' number Pixels to offset from top when calculating position of scroll.
* '''method''' string Finds which section the spied element is in.
* '''target''' string Specifies element to apply Scrollspy plugin.

=== Tab ===
Assuming you have the HTML part already in your Layout, you will also need to include the interactivity (the JavaScript part):

<pre>
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.tab', '.selector', []);
</pre>

* The '''.selector''' refers to the CSS selector for the tab. You can call this function multiple times with different CSS selectors
* The third argument refers to the options available for tab

Options for the Tab can be:

=== Tooltip ===
Assuming you have the HTML part already in your Layout, you will also need to include the interactivity (the JavaScript part):

<pre>
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.tooltip', '.selector', []);
</pre>

* The '''.selector''' refers to the CSS selector for the tooltip. You can call this function multiple times with different CSS selectors
* The third argument refers to the options available for tooltip

Options for the tooltip can be:
* '''animation''', boolean apply a css fade transition to the popover
* '''container''', string|boolean Appends the popover to a specific element: { container: '''body''' }
* '''delay''', number|object delay showing and hiding the popover (ms) - does not apply to manual trigger type If a number is supplied, delay is applied to both hide/show Object structure is: delay: { show: 500, hide: 100 }
* '''html''', boolean Insert HTML into the popover. If false, jQuery's text method will be used to insert content into the dom.
* '''placement''', string|function how to position the popover - '''top''' | '''bottom''' | '''left''' | '''right'''
* '''selector''' string If a selector is provided, popover objects will be delegated to the specified targets.
* '''template''', string Base HTML to use when creating the popover.
* '''title''', string|function default title value if '''title''' tag isn't present
* '''trigger''', string how popover is triggered - hover | focus | manual
* '''constraints''', array An array of constraints - passed through to Popper.
* '''offset''', string Offset of the popover relative to its target.

=== Toast ===
Assuming you have the HTML part already in your Layout, you will also need to include the interactivity (the JavaScript part):

<pre>
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.toast', '.selector', []);
</pre>

* The '''.selector''' refers to the CSS selector for the toast. You can call this function multiple times with different CSS selectors
* The third argument refers to the options available for toast

Options for the toast can be:
* '''animation''', boolean, default:'''true''' Apply a CSS fade transition to the toast
* '''autohide''', boolean, default:'''true''' Auto hide the toast
* '''delay''', number , default:'''5000''' Delay hiding the toast (ms)

=== See Also ===
* '''Accordian''' uses Collapse to display panels of data.
* '''List Group''' can be combined with Tab to display tabbed content.

== Using Bootstrap Components in Articles ==
The HTML mark-up for most components can be included in an article or a module that can itself be included in an article. The snag is that the HTMLHelper call to set up the JavaScript support cannot be included there. There are several possible approaches to this problem. Three approaches are suggested here, using a custom Module, using a Plugin or using a Template override.

'''Caution:''' The TinyMCE and JCE editors remove white space on Save and make editing code difficult! The simple solution is to go to the top right of your Administrator screen and select {{rarr|User Menu,Edit Account}} and set the Editor to Code Mirror.

== Approach 1: Using a Custom Module ==
This is probably the least error prone approach because the Bootstrap component support options are selected with check boxes. The steps involved are as follows:

* Download, install and enable this module: https://github.com/ceford/j4xdemos-mod-custom-bscompos/raw/master/mod_custom_bscompos.zip
* From the Administrator menu go to {{rarr|Content,Site Modules,New}}
* Select '''Custom BS Components'''
* Enter a Title
* Toggle the Editor to plain text mode and paste in or type in the HTML code for the component you want to use.
* In the Options tab scroll down to the list of BS Components and select type of component in this instance of the module. Note that you can select more than one if your using more than one component.
* Select a module Position: either
** a template defined position if you want to use the module in a specific location or
** type in a position if you wish to use the module within a specific article: in the article type in <div>{loadposition whatever}</div>
* Save and go to the site to Test!

=== Selectors ===
For some components JavaScript action is triggered by a specific '''class''' in the HTML code. In other components action is triggered by a '''data-bs-whatever''' attribute. The following are the current triggers and may change:

* '''Alert''' triggered by class="alert ..."
* '''Button''' triggered by data-bs-toggle="button"
* '''Carousel''' triggered by data-bs-ride="whatever"
* '''Collapse''' triggered by data-bs-toggle="collapse"
* '''Dropdown''' triggered by data-bs-toggle="dropdown"
* '''Modal''' triggered by data-bs-toggle="modal"
* '''Offcanvas''' triggered by data-bs-toggle="offcanvas"
* '''Popover''' triggered by class="btn ..." or <a ...> tag (could be changed to class="haspopover ...") AND data-bs-toggle="popover"
* '''Scrollspy''' triggered by data-bs-spy="scroll"
* '''Tab''' triggered by data-bs-toggle="tab"
* '''Toast''' triggered by class="toast ..."
* '''Tooltip''' triggered by class="btn ..." or <a ...> tag (could be changed to class="hastooltip ...") AND data-bs-toggle="tooltip"

=== Example 1: Alert ===
Alerts may be used in html code without JavaScript support. This is only needed for the dismiss capability. HTML code example:

<syntaxhighlight lang="html">
<div class="alert alert-warning alert-dismissible fade show" role="alert">
<strong>Holy guacamole!</strong> You should check in on some of those fields below.
<button type="button" class="btn-close" data-bs-dismiss="alert" aria-label="Close"></button>
</div>
</syntaxhighlight>

Example result of including a module in an article:

[[File:using-bootstrap-components-in-joomla-4-alert-demo.png|border|Alert Demo]]

Note that without JavaScript support, the alert will appear exactly as above but a click on the close button [X] will not dismiss the alert. Also, the alert will appear on every page load.

=== Example 2: Buttons ===
Buttons may be used in HTML code without JavaScript support. This is only needed for the sometimes subtle change of style applied to buttons with a change of state, styled active. Bootstrap example code:

<syntaxhighlight lang="html">
<p><button type="button" class="btn btn-primary" data-bs-toggle="button" autocomplete="off">Toggle button</button>
<button type="button" class="btn btn-primary active" data-bs-toggle="button" autocomplete="off" aria-pressed="true">Active toggle button</button>
<button type="button" class="btn btn-primary" disabled data-bs-toggle="button" autocomplete="off">Disabled toggle button</button></p></pre>
<pre><p><a href="#" class="btn btn-primary" role="button" data-bs-toggle="button">Toggle link</a>
<a href="#" class="btn btn-primary active" role="button" data-bs-toggle="button" aria-pressed="true">Active toggle link</a>
<a href="#" class="btn btn-primary disabled" tabindex="-1" aria-disabled="true" role="button" data-bs-toggle="button">Disabled toggle link</a></p>
</syntaxhighlight>

With this style in the template user.css:
<pre>.btn.btn-primary.active {
background-color: green;
}</pre>

[[File:using-bootstrap-components-in-joomla-4-button-demo.png|border|Button Demo]]

The buttons toggle between blue and green.

=== Example 3: Carousel ===
The Carousel offers a slide show cycling through a series of images or text panes. The following example used images from the Joomla 4 Sample. Bootstrap code:

<syntaxhighlight lang="php">
<div id="carouselExampleCaptions" class="carousel slide" data-bs-ride="carousel">
<div class="carousel-indicators">
<button class="active" type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide-to="0" aria-current="true" aria-label="Slide 1"></button>
<button type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide-to="1" aria-label="Slide 2"></button>
<button type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide-to="2" aria-label="Slide 3"></button>
</div>
<div class="carousel-inner">
<div class="carousel-item active"><img class="d-block w-100" src="images/sampledata/cassiopeia/nasa1-1200.jpg" alt="..." />
<div class="carousel-caption d-none d-md-block">
<h5>First slide label</h5>
<p>Some representative placeholder content for the first slide.</p>
</div>
</div>
<div class="carousel-item"><img class="d-block w-100" src="images/sampledata/cassiopeia/nasa2-1200.jpg" alt="..." />
<div class="carousel-caption d-none d-md-block">
<h5>Second slide label</h5>
<p>Some representative placeholder content for the second slide.</p>
</div>
</div>
<div class="carousel-item"><img class="d-block w-100" src="images/sampledata/cassiopeia/nasa3-1200.jpg" alt="..." />
<div class="carousel-caption d-none d-md-block">
<h5>Third slide label</h5>
<p>Some representative placeholder content for the third slide.</p>
</div>
</div>
</div>
<button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide="prev">
<span class="visually-hidden">Previous</span>
</button>
<button class="carousel-control-next" type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide="next">
<span class="visually-hidden">Next</span>
</button>
</div>
</syntaxhighlight>

Result:

[[File:using-bootstrap-components-in-joomla-4-carousel-demo.jpg|border|Carousel Demo]]

=== Example 4: Collapse ===
Collapse is widely used in Joomla and you may not need to use a module or plugin to trigger action. The click opens a pane with extra information. Example Bootstrap code:

<syntaxhighlight lang="php">
<p>
<a class="btn btn-primary" role="button" href="#collapseExample" data-bs-toggle="collapse" aria-expanded="false" aria-controls="collapseExample"> Link with href </a>
<button class="btn btn-primary" type="button" data-bs-toggle="collapse" data-bs-target="#collapseExample" aria-expanded="false" aria-controls="collapseExample">
Button with data-bs-target
</button>
</p>
<div id="collapseExample" class="collapse">
<div class="card card-body">
Some placeholder content for the collapse component. This panel is hidden by default but revealed when the user activates the relevant trigger.
</div>
</div>
</syntaxhighlight>

Result:

[[File:using-bootstrap-components-in-joomla-4-collapse-demo.png|border|Collapse Demo]]

=== Example 5: Dropdown ===
Dropdowns are toggleable, contextual overlays for displaying lists of links and more. Example Bootstrap code:

<syntaxhighlight lang="php">
<div class="btn-group">
<button class="btn btn-danger dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false"> Action </button>
<ul class="dropdown-menu">
<li><a class="dropdown-item" href="#">Action</a></li>
<li><a class="dropdown-item" href="#">Another action</a></li>
<li><a class="dropdown-item" href="#">Something else here</a></li>
<li><hr class="dropdown-divider" /></li>
<li><a class="dropdown-item" href="#">Separated link</a></li>
</ul>
</div>
</syntaxhighlight>
Result:

[[File:using-bootstrap-components-in-joomla-4-dropdown-demo.png|border|Dropdown Demo]]

=== Example 6: Modal ===
The Modal component opens a dialog box in the middle of the screen. There are quite a few options to control the size and content of the modal. See the Bootstrap documentation for more details. Example Bootstrap code:

<syntaxhighlight lang="php">
<p><button class="btn btn-primary" type="button" data-bs-toggle="modal" data-bs-target="#exampleModal"> Launch demo modal </button></p>
<div id="exampleModal" class="modal fade" tabindex="-1" aria-labelledby="exampleModalLabel" aria-hidden="true">
<div class="modal-dialog">
<div class="modal-content">
<div class="modal-header">
<h5 id="exampleModalLabel" class="modal-title">Modal title</h5>
<button class="btn-close" type="button" data-bs-dismiss="modal" aria-label="Close"></button>
</div>
<div class="modal-body">
...
</div>
<div class="modal-footer">
<button class="btn btn-secondary" type="button" data-bs-dismiss="modal">Close</button>
<button class="btn btn-primary" type="button">Save changes</button>
</div>
</div>
</div>
</div>
</syntaxhighlight>

Result:

[[File:using-bootstrap-components-in-joomla-4-modal-demo.png|Modal Demo]]

=== Example 7: Offcanvas ===
At the moment this component is not supported in Joomla. Watch this space - coming soon!

=== Example 8: Popover ===
Popovers are like Tooltips but with a Title. They have some accessibility and performance issues so should be used with caution. Example Bootstrap code:

<pre><p><button class="btn btn-lg btn-danger" title="Popover title" type="button" data-bs-toggle="popover" data-bs-content="And here's some amazing content. It's very engaging. Right?">Click to toggle popover</button></p></pre>

Result:

[[File:using-bootstrap-components-in-joomla-4-popover-demo.png|border|Popover Demo]]

=== Example 9: Scrollspy ===
Example code:
<syntaxhighlight lang="php">
<div class="row">
<div class="col-4">
<nav id="navbar-example3" class="navbar navbar-light bg-light flex-column">
<a class="navbar-brand" href="#">Navbar</a><nav class="nav nav-pills flex-column">
<a class="nav-link active" href="#item-1">Item 1</a>
<nav class="nav nav-pills flex-column">
<a class="nav-link ms-3 my-1" href="#item-1-1">Item 1-1</a>
<a class="nav-link ms-3 my-1" href="#item-1-2">Item 1-2</a>
</nav>
<a class="nav-link" href="#item-2">Item 2</a>
<a class="nav-link" href="#item-3">Item 3</a>
<nav class="nav nav-pills flex-column">
<a class="nav-link ms-3 my-1" href="#item-3-1">Item 3-1</a>
<a class="nav-link ms-3 my-1" href="#item-3-2">Item 3-2</a>
</nav>
</nav>
</div>
<div class="col-8">
<div class="scrollspy-example" tabindex="0" data-bs-spy="scroll" data-bs-target="#navbar-example3" data-bs-offset="0">
<h4 id="item-1">Item 1</h4>
<p>Placeholder content for the scrollspy example. This one relates to item 1. Takes you miles high, so high, 'cause she’s got that one international smile. There's a stranger in my bed, there's a pounding in my head. Oh, no. In another life I would make you stay. ‘Cause I, I’m capable of anything. Suiting up for my crowning battle. Used to steal your parents' liquor and climb to the roof. Tone, tan fit and ready, turn it up cause its gettin' heavy. Her love is like a drug. I guess that I forgot I had a choice.</p>
<h5 id="item-1-1">Item 1-1</h5>
<p>Placeholder content for the scrollspy example. This one relates to the item 1-1. You got the finest architecture. Passport stamps, she's cosmopolitan. Fine, fresh, fierce, we got it on lock. Never planned that one day I'd be losing you. She eats your heart out. Your kiss is cosmic, every move is magic. I mean the ones, I mean like she's the one. Greetings loved ones let's take a journey. Just own the night like the 4th of July! But you'd rather get wasted.</p>
<h5 id="item-1-2">Item 1-2</h5>
<p>Placeholder content for the scrollspy example. This one relates to the item 1-2. Her love is like a drug. All my girls vintage Chanel baby. Got a motel and built a fort out of sheets. 'Cause she's the muse and the artist. (This is how we do) So you wanna play with magic. So just be sure before you give it all to me. I'm walking, I'm walking on air (tonight). Skip the talk, heard it all, time to walk the walk. Catch her if you can. Stinging like a bee I earned my stripes.</p>
<h4 id="item-2">Item 2</h4>
<p>Placeholder content for the scrollspy example. This one relates to item 2. Don't need apologies. There is no fear now, let go and just be free, I will love you unconditionally. Last Friday night. Don't be a shy kinda guy I'll bet it's beautiful. Summer after high school when we first met. 'Cause she's the muse and the artist. What? Wait. No, no, no, no. Thought that I was the exception.</p>
<h4 id="item-3">Item 3</h4>
<p>Placeholder content for the scrollspy example. This one relates to item 3. Word on the street, you got somethin' to show me, me. All this money can't buy me a time machine. Make it like your birthday everyday. So we hit the boulevard. You make me feel like I'm livin' a teenage dream, the way you turn me on Skip the talk, heard it all, time to walk the walk. Word on the street, you got somethin' to show me, me. It's no big deal, it's no big deal, it's no big deal.</p>
<h5 id="item-3-1">Item 3-1</h5>
<p>Placeholder content for the scrollspy example. This one relates to item 3-1. Baby do you dare to do this? This is no big deal. Yeah, you're lucky if you're on her plane. Just own the night like the 4th of July! Standing on the frontline when the bombs start to fall. So just be sure before you give it all to me.</p>
<h5 id="item-3-2">Item 3-2</h5>
<p>Placeholder content for the scrollspy example. This one relates to item 3-2. You're original, cannot be replaced. All night they're playing, your song. California girls we're undeniable. Like a bird without a cage. There is no fear now, let go and just be free, I will love you unconditionally. I can see the writing on the wall. You could travel the world but nothing comes close to the golden coast.</p>
</div>
</div>
</div>
</syntaxhighlight>

Result:

[[File:using-bootstrap-components-in-joomla-4-scrollspy-demo.png|border|Scrollspy Demo]]

Also, some styling is needed in user.css:

<pre>.scrollspy-example {
height: 350px;
overflow-y: scroll;
}</pre>

Snag: the menu does not coordinate well with the content in this example!

=== Example 10: Tab ===
Tabs are often used as navigation elements combined with dropdowns. Bootstrap example code:

<syntaxhighlight lang="html">
<ul class="nav nav-tabs">
<li class="nav-item"><a class="nav-link active" href="#" aria-current="page">Active</a></li>
<li class="nav-item dropdown"><a class="nav-link dropdown-toggle" role="button" href="#" data-bs-toggle="dropdown" aria-expanded="false">Dropdown</a>
<ul class="dropdown-menu">
<li><a class="dropdown-item" href="#">Action</a></li>
<li><a class="dropdown-item" href="#">Another action</a></li>
<li><a class="dropdown-item" href="#">Something else here</a></li>
<li><hr class="dropdown-divider" /></li>
<li><a class="dropdown-item" href="#">Separated link</a></li>
</ul>
</li>
<li class="nav-item"><a class="nav-link" href="#">Link</a></li>
<li class="nav-item"><a class="nav-link disabled" tabindex="-1" href="#" aria-disabled="true">Disabled</a></li>
</ul>
</syntaxhighlight>

Result:

[[File:using-bootstrap-components-in-joomla-4-tab-demo.png|border|Tab Demo]]

Remember to check both the Tab and Dropdown options for the dropdown part to work.

=== Example 11: Toast ===
Toasts are lightweight notifications designed to mimic the push notifications that have been popularized by mobile and desktop operating systems. They’re built with flexbox, so they’re easy to align and position. Example Bootstrap code:

<syntaxhighlight lang="php">
<div class="toast fade show" role="alert" aria-live="assertive" aria-atomic="true">
<div class="toast-header">
<img class="rounded me-2" src="..." alt="..." />
<strong class="me-auto">Bootstrap</strong> <small>11 mins ago</small>
<button class="btn-close" type="button" data-bs-dismiss="toast" aria-label="Close"></button>
</div>
<div class="toast-body">Hello, world! This is a toast message.</div>
</div>
</syntaxhighlight>

Result:

[[File:using-bootstrap-components-in-joomla-4-toast-demo.png|border|Toast Demo]]

Note that the Bootstrap demo that uses a button to show the Toast message needs some extra JavaScript. It seems this component needs a coder to make good use of it!

=== Example 12: Tooltip ===
A tooltip is a small piece of text that appears on hover over a button or link element to explain what it is or does. The tooltip can be positioned above or below or to the left or right of the element. If not specified the default position is top. The tooltip will switch to another position if there is insufficient room in the specified position. Example Bootstrap code:

<syntaxhighlight lang="html">
<p><button class="btn btn-secondary" title="Tooltip on left" type="button" data-bs-toggle="tooltip" data-bs-placement="left"> Tooltip on left </button>
<button class="btn btn-secondary" title="Tooltip" type="button" data-bs-toggle="tooltip"> Tooltip </button>
<button class="btn btn-secondary" title="Tooltip on top" type="button" data-bs-toggle="tooltip" data-bs-placement="top"> Tooltip on top </button>
<button class="btn btn-secondary" title="Tooltip on right" type="button" data-bs-toggle="tooltip" data-bs-placement="right"> Tooltip on right </button>
<button class="btn btn-secondary" title="Tooltip on bottom" type="button" data-bs-toggle="tooltip" data-bs-placement="bottom"> Tooltip on bottom </button>
<button class="btn btn-secondary" title="<em>Tooltip</em> <u>with</u> <b>HTML</b>" type="button" data-bs-toggle="tooltip" data-bs-html="true"> Tooltip with HTML </button></p>
<p>Tooltip triggered by class: <button class="btn btn-warning" title="Tooltip Message">Alert!</button></p>
</syntaxhighlight>

Result:

[[File:using-bootstrap-components-in-joomla-4-tooltip-demo.png|border|Tooltip Demo]]

== Approach 2: Using a Content Plugin ==
The steps involved:
* Download, install and enable this plugin: https://github.com/ceford/j4xdemos-plg-bscompos/raw/master/plg_j4xdemos_bscompos.zip
* In the article add the text that the plugin acts on. For example ''{bscompos modal carousel}'' will trigger loading of the JavaScript necessary to support a modal dialog and a carousel. The plugin removes the trigger text and enclosing (now) empty <nowiki><p></p></nowiki> tags.
* Include the Bootstrap Component HTML code directly in the article or in a module invoked in the article. There is example HTML code below for a simple Modal and a Modal containing a Carousel. Note that this will not work if the HTML code is in a module in a template location.
* This will also work for a standard Custom module if the ''Prepare Content Option'' is set to ''Yes''.
* Test it!

== Approach 3: Using a Template Override ==
The steps involved:
* Create a ''mod_custom'' template override.
* Add a module of type custom containing the component markup and trigger classes.
* Load the module into an article using [[How do you put a module inside an article?|''loadposition'', ''loadmodule'' or ''loadmoduleid'']].

=== The ''mod_custom'' Template Override ===
* In the Administrator go to {{rarr|System, Site Templates, Cassiopeia Details and Files}}.
* Select {{rarr|Create Overrides, mod_custom, default.php}}.
* On the line following ''defined('_JEXEC') or die;'' add this code:
<syntaxhighlight lang="php">
$module_class = $params->get('moduleclass_sfx');
if (!empty($module_class))
{
$classes = explode(' ', $module_class);
foreach ($classes as $class)
{
switch ($class)
{
case 'bs-alert':
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.alert', '.alert');
break;
case 'bs-button':
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.button', '.btn');
break;
case 'bs-carousel':
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.carousel', '.selector', []);
break;
case 'bs-collapse':
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.collapse', '.selector', []);
break;
case 'bs-dropdown':
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.dropdown', '.selector', []);
break;
case 'bs-modal':
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.modal', '.selector', []);
break;
case 'bs-offcanvas':
// Not Found
//\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.offcanvas', '.btn', []);
break;
case 'bs-popover':
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.popover', '.btn', []);
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.popover', 'a', []);
break;
case 'bs-scrollspy':
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.scrollspy', '.selector', []);
break;
case 'bs-tab':
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.tab', '.selector', []);
break;
case 'bs-tooltip':
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.tooltip', '.btn', []);
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.tooltip', 'a', []);
break;
case 'bs-toast':
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.toast', '.selector', []);
break;
default:
// do nothing
}
}
}
</syntaxhighlight>
This code searches for class names set in mod_custom and makes the HTMLHelper call to set up the JavaScript support. Note that the next to last item in each call is a selector that may or may not be used to trigger action. Many of the components are triggered by data attributes in the mark-up and they do not use the selectors here. For some, the selector is needed. For example, it makes sense to use the ''.btn'' class and the ''a'' tag to trigger Tooltips.

=== A ''mod_custom'' Module for a Modal Component ===
* Go to {{rarr|Content, Site Modules, New}}.
* Select the '''Custom''' module.
* Fill out the form:
** Title: Demo Modal
** In the Position field type in '''demomodal''' for use in an article;
** Module Content: Toggle Editor for plain text entry.
** Paste in the following code from the Bootstrap documentation:

<syntaxhighlight lang="php">
<h2>Modal</h2>

<p><button class="btn btn-primary" type="button" data-bs-toggle="modal" data-bs-target="#exampleModal"> Launch demo modal </button></p>

<div id="exampleModal" class="modal fade" tabindex="-1" aria-labelledby="exampleModalLabel" aria-hidden="true">
<div class="modal-dialog">
<div class="modal-content">
<div class="modal-header">
<h5 id="exampleModalLabel" class="modal-title">Modal title</h5>
<button class="btn-close" type="button" data-bs-dismiss="modal" aria-label="Close"></button>
</div>
<div class="modal-body">
...
</div>
<div class="modal-footer">
<button class="btn btn-secondary" type="button" data-bs-dismiss="modal">Close</button>
<button class="btn btn-primary" type="button">Save changes</button>
</div>
</div>
</div>
</div>
</syntaxhighlight>
* Select the Advanced tab and in the Module Class field enter '''bs-modal'''
* Optional: set Ttitle to Hide to use the H2 in the pasted code.
* Save and Close (do not worry that the modal looks all wrong in the editor).

=== Create an Article and Menu Item ===
* Create a new article, Demo Modal, and in plain text entry mode set the content to <pre><div>{loadposition demomodal}</div></pre>
* Create a Single Article menu item.
* Test it:
[[File:Demomodal.png|none|Bootstrap Modal in an Article]]

=== A Modal Component Containing a Carousel ===
* Create a new Custom module with a new Title: Demo Modal Carousel
* Position: demomodalcarousel
* {{rarr|Advance tab, Module Class}}: bs-modal bs-carousel
* Module Custom content in plain text:

<syntaxhighlight lang="php">
<h2>Modal with Carousel</h2>
<div class="mod-custom custom">

<button class="btn btn-primary" type="button" data-bs-toggle="modal" data-bs-target="#exampleModal"> Launch demo modal </button>
</div>
<div id="exampleModal" class="modal fade" style="display: none;" tabindex="-1" aria-hidden="true">
<div class="modal-dialog" role="document">
<div class="modal-content">
<div class="modal-header">
<button class="close" type="button" data-bs-dismiss="modal" aria-label="Close">
<span aria-hidden="true">×</span>
</button>
</div>
<div class="modal-body">
<div id="carouselExampleCaptions" class="carousel slide" data-bs-ride="carousel">
<div class="carousel-indicators">
<button class="active" type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide-to="0" aria-current="true" aria-label="Slide 1"></button>
<button type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide-to="1" aria-label="Slide 2"></button>
<button type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide-to="2" aria-label="Slide 3"></button>
</div>
<div class="carousel-inner">
<div class="carousel-item active">
<img class="d-block w-100" src="images/sampledata/cassiopeia/nasa1-1200.jpg" alt="..." />
<div class="carousel-caption d-none d-md-block">
<h5>First slide label</h5>
<p>Some representative placeholder content for the first slide.</p>
</div>
</div>
<div class="carousel-item">
<img class="d-block w-100" src="images/sampledata/cassiopeia/nasa2-1200.jpg" alt="..." />
<div class="carousel-caption d-none d-md-block">
<h5>Second slide label</h5>
<p>Some representative placeholder content for the second slide.</p>
</div>
</div>
<div class="carousel-item">
<img class="d-block w-100" src="images/sampledata/cassiopeia/nasa3-1200.jpg" alt="..." />
<div class="carousel-caption d-none d-md-block">
<h5>Third slide label</h5>
<p>Some representative placeholder content for the third slide.</p>
</div>
</div>
</div>
<button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide="prev">
<span class="visually-hidden">Previous</span>
</button>
<button class="carousel-control-next" type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide="next">
<span class="visually-hidden">Next</span>
</button>
</div>
</div>
</div>
</div>
</div></syntaxhighlight>
* Create a new Article with <nowiki><div>{loadposition demomodalcarousel}</div></nowiki> in the content.
* Create a new single article menu item: Demo Modal Carousel
* Test it:
[[File:Demomodalcarousel.png|Demo Modal containing a Carousel]]

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

J4.x:Using Bootstrap Components in Joomla 4

2023-09-22T22:24:49Z

Cmb: Replaced deprecated 'source' tags with 'syntaxhighlight' tags. Other markup changes.

== Introduction ==

=== Bootstrap Components ===
Some of the components described in the Bootstrap documentation use CSS only. For example, the Breadcrumbs component is rendered with CSS and requires no JavaScript support. Others respond to user actions such as click or hover, and need JavaScript support. The latter are referred to here as Interactive Components. This article explains how to use them in Articles and a Custom Module.

See: [https://getbootstrap.com/docs/5.0/getting-started/introduction/ Bootstrap Documentation]

=== Joomla 4 Introduces a Modular Approach for Interactive Components ===
* What is a modular approach?
* The functionality is broken down into individual components supported by individual files. There is no '''one file''' approach as it was with Bootstrap in Joomla 3. The modular approach is more efficient and offers performance gains. (Send only the code that is needed instead of delivering everything in case some page will need some component.)

=== Using Interactive Components: Coders ===
* Load what you need per case! There are helper functions to set up individual components with appropriate arguments.
* See the list of Bootstrap Interactive Components.

=== Using Interactive Components: Non-Coders ===
* Using components in articles is not so easy because the helper functions cannot be called from an article or standard Custom HTML module. Three possible solutions are suggested later in this tutorial:
** A custom module
** A custom plugin
** A custom module override
* Skip or scan the list of Bootstrap Interactive Components. You won't be using these function calls directly.

== Bootstrap Interactive Components ==
=== Alert ===
Assuming you have the HTML part already in your Layout, you will also need to include the interactivity (the JavaScript part):

<pre>
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.alert', '.selector');
</pre>

* The '''.selector''' refers to the CSS selector for the alert. You can call this function multiple times with different CSS selectors
* No extra options available

=== Button ===
Assuming you have the HTML part already in your Layout, you will also need to include the interactivity (the JavaScript part):

<pre>
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.button', '.selector');
</pre>

* The '''.selector''' refers to the CSS selector for the button. You can call this function multiple times with different CSS selectors
* No extra options available

=== Carousel ===
Assuming you have the HTML part already in your Layout, you will also need to include the interactivity (the JavaScript part):

<pre>
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.carousel', '.selector', []);
</pre>

* The '''.selector''' refers to the CSS selector for the carousel. You can call this function multiple times with different CSS selectors
* The third argument refers to the options available for carousel

Options for the carousel can be:
* '''interval''', number, default:'''5000''', The amount of time to delay between automatically cycling an item. If false, carousel will not automatically cycle.
* '''keyboard''', boolean, default:'''true''' Whether the carousel should react to keyboard events.
* '''pause''', string|boolean, '''hover''' Pauses the cycling of the carousel on ''mouseenter'' and resumes the cycling of the carousel on ''mouseleave''.
* '''slide''', string|boolean, default:'''false''' Autoplays the carousel after the user manually cycles the first item. If "carousel", autoplays the carousel on load.

=== Collapse ===
Assuming you have the HTML part already in your Layout, you will also need to include the interactivity (the JavaScript part):

<pre>
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.collapse', '.selector', []);
</pre>

* The '''.selector''' refers to the CSS selector for the collapse. You can call this function multiple times with different CSS selectors
* The third argument refers to the options available for collapse

Options for the collapse can be:
* '''parent''', string, default:'''false''' If parent is provided, then all collapsible elements under the specified parent will be closed when this collapsible item is shown.
* '''toggle''', boolean default:'''true''' Toggles the collapsible element on invocation

=== Dropdown ===
Assuming you have the HTML part already in your Layout, you will also need to include the interactivity (the JavaScript part):

<pre>
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.dropdown', '.selector', []);
</pre>

* The '''.selector''' refers to the CSS selector for the dropdown. You can call this function multiple times with different CSS selectors
* The third argument refers to the options available for dropdown

Options for the collapse can be:
* '''flip''', boolean, default:'''true''' Allow Dropdown to flip in case of an overlapping on the reference element
* '''boundary''', string, default:'''scrollParent''' Overflow constraint boundary of the dropdown menu
* '''reference''', string, default:'''toggle''' Reference element of the dropdown menu. Accepts '''toggle''' or '''parent'''
* '''display''', string, default:'''dynamic''' By default, we use Popper for dynamic positioning. Disable this with '''static'''

=== Modal ===
Assuming you have the HTML part already in your Layout, you will also need to include the interactivity (the JavaScript part):

<pre>
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.modal', '.selector', []);
</pre>

* The '''.selector''' refers to the CSS selector for the modal. You can call this function multiple times with different CSS selectors
* The third argument refers to the options available for modal

Options for the modal can be:
* '''backdrop''', string|boolean default:'''true''' Includes a modal-backdrop element. Alternatively, specify static for a backdrop which doesn't close the modal on click.
* '''keyboard''', boolean default:'''true''' Closes the modal when escape key is pressed
* '''focus''', boolean default:'''true''' Closes the modal when escape key is pressed

=== Offcanvas ===
Assuming you have the HTML part already in your Layout, you will also need to include the interactivity (the JavaScript part):

<pre>
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.offcanvas', '.selector', []);
</pre>

* The '''.selector''' refers to the CSS selector for the offcanvas. You can call this function multiple times with different CSS selectors
* The third argument refers to the options available for offcanvas

Options for the offcanvas can be:
* '''backdrop''', boolean, default:'''true''' Apply a backdrop on body while offcanvas is open
* '''keyboard''', boolean, default:'''true''' Closes the offcanvas when escape key is pressed
* '''scroll''', boolean, default:'''false''' Allow body scrolling while offcanvas is open

=== Popover ===
Assuming you have the HTML part already in your Layout, you will also need to include the interactivity (the JavaScript part):

<pre>
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.popover', '.selector', []);
</pre>

* The '''.selector''' refers to the CSS selector for the popover. You can call this function multiple times with different CSS selectors
* The third argument refers to the options available for popover

Options for the popover can be:
* '''animation''', boolean, default:'''true''' Apply a CSS fade transition to the popover
* '''container''', string|boolean, default:'''false''' Appends the popover to a specific element. Eg.: '''body'''
* '''content''', string, default:'''null''' Default content value if data-bs-content attribute isn't present
* '''delay''', number, default:'''0''' Delay showing and hiding the popover (ms) does not apply to manual trigger type
* '''html''', boolean, default:'''true''' Insert HTML into the popover. If '''false''', innerText property will be used to insert content into the DOM.
* '''placement''', string, default:'''right''' How to position the popover - '''auto''' | '''top''' | '''bottom''' | '''left''' | '''right'''. When auto is specified, it will dynamically reorient the popover
* '''selector''', string, default:'''false''' If a selector is provided, popover objects will be delegated to the specified targets.
* '''template''', string, default:'''null''' Base HTML to use when creating the popover.
* '''title''', string, default:'''null''' Default title value if '''title''' tag isn't present
* '''trigger''', string, default:'''click''' How popover is triggered - '''click''' | '''hover''' | '''focus''' | '''manual'''
* '''offset''', integer, default:'''0''' Offset of the popover relative to its target.

=== Scrollspy ===
Assuming you have the HTML part already in your Layout, you will also need to include the interactivity (the JavaScript part):

<pre>
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.scrollspy', '.selector', []);
</pre>

* The '''.selector''' refers to the CSS selector for the scrollspy. You can call this function multiple times with different CSS selectors
* The third argument refers to the options available for scrollspy

Options for the Scrollspy can be:
* '''offset''' number Pixels to offset from top when calculating position of scroll.
* '''method''' string Finds which section the spied element is in.
* '''target''' string Specifies element to apply Scrollspy plugin.

=== Tab ===
Assuming you have the HTML part already in your Layout, you will also need to include the interactivity (the JavaScript part):

<pre>
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.tab', '.selector', []);
</pre>

* The '''.selector''' refers to the CSS selector for the tab. You can call this function multiple times with different CSS selectors
* The third argument refers to the options available for tab

Options for the Tab can be:

=== Tooltip ===
Assuming you have the HTML part already in your Layout, you will also need to include the interactivity (the JavaScript part):

<pre>
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.tooltip', '.selector', []);
</pre>

* The '''.selector''' refers to the CSS selector for the tooltip. You can call this function multiple times with different CSS selectors
* The third argument refers to the options available for tooltip

Options for the tooltip can be:
* '''animation''', boolean apply a css fade transition to the popover
* '''container''', string|boolean Appends the popover to a specific element: { container: '''body''' }
* '''delay''', number|object delay showing and hiding the popover (ms) - does not apply to manual trigger type If a number is supplied, delay is applied to both hide/show Object structure is: delay: { show: 500, hide: 100 }
* '''html''', boolean Insert HTML into the popover. If false, jQuery's text method will be used to insert content into the dom.
* '''placement''', string|function how to position the popover - '''top''' | '''bottom''' | '''left''' | '''right'''
* '''selector''' string If a selector is provided, popover objects will be delegated to the specified targets.
* '''template''', string Base HTML to use when creating the popover.
* '''title''', string|function default title value if '''title''' tag isn't present
* '''trigger''', string how popover is triggered - hover | focus | manual
* '''constraints''', array An array of constraints - passed through to Popper.
* '''offset''', string Offset of the popover relative to its target.

=== Toast ===
Assuming you have the HTML part already in your Layout, you will also need to include the interactivity (the JavaScript part):

<pre>
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.toast', '.selector', []);
</pre>

* The '''.selector''' refers to the CSS selector for the toast. You can call this function multiple times with different CSS selectors
* The third argument refers to the options available for toast

Options for the toast can be:
* '''animation''', boolean, default:'''true''' Apply a CSS fade transition to the toast
* '''autohide''', boolean, default:'''true''' Auto hide the toast
* '''delay''', number , default:'''5000''' Delay hiding the toast (ms)

=== See Also ===
* '''Accordian''' uses Collapse to display panels of data.
* '''List Group''' can be combined with Tab to display tabbed content.

== Using Bootstrap Components in Articles ==
The HTML mark-up for most components can be included in an article or a module that can itself be included in an article. The snag is that the HTMLHelper call to set up the JavaScript support cannot be included there. There are several possible approaches to this problem. Three approaches are suggested here, using a custom Module, using a Plugin or using a Template override.

'''Caution:''' The TinyMCE and JCE editors remove white space on Save and make editing code difficult! The simple solution is to go to the top right of your Administrator screen and select {{rarr|User Menu,Edit Account}} and set the Editor to Code Mirror.

== Approach 1: Using a Custom Module ==
This is probably the least error prone approach because the Bootstrap component support options are selected with check boxes. The steps involved are as follows:

* Download, install and enable this module: https://github.com/ceford/j4xdemos-mod-custom-bscompos/raw/master/mod_custom_bscompos.zip
* From the Administrator menu go to {{rarr|Content,Site Modules,New}}
* Select '''Custom BS Components'''
* Enter a Title
* Toggle the Editor to plain text mode and paste in or type in the HTML code for the component you want to use.
* In the Options tab scroll down to the list of BS Components and select type of component in this instance of the module. Note that you can select more than one if your using more than one component.
* Select a module Position: either
** a template defined position if you want to use the module in a specific location or
** type in a position if you wish to use the module within a specific article: in the article type in <div>{loadposition whatever}</div>
* Save and go to the site to Test!

=== Selectors ===
For some components JavaScript action is triggered by a specific '''class''' in the HTML code. In other components action is triggered by a '''data-bs-whatever''' attribute. The following are the current triggers and may change:

* '''Alert''' triggered by class="alert ..."
* '''Button''' triggered by data-bs-toggle="button"
* '''Carousel''' triggered by data-bs-ride="whatever"
* '''Collapse''' triggered by data-bs-toggle="collapse"
* '''Dropdown''' triggered by data-bs-toggle="dropdown"
* '''Modal''' triggered by data-bs-toggle="modal"
* '''Offcanvas''' triggered by data-bs-toggle="offcanvas"
* '''Popover''' triggered by class="btn ..." or <a ...> tag (could be changed to class="haspopover ...") AND data-bs-toggle="popover"
* '''Scrollspy''' triggered by data-bs-spy="scroll"
* '''Tab''' triggered by data-bs-toggle="tab"
* '''Toast''' triggered by class="toast ..."
* '''Tooltip''' triggered by class="btn ..." or <a ...> tag (could be changed to class="hastooltip ...") AND data-bs-toggle="tooltip"

=== Example 1: Alert ===
Alerts may be used in html code without JavaScript support. This is only needed for the dismiss capability. HTML code example:

<pre><div class="alert alert-warning alert-dismissible fade show" role="alert">
<strong>Holy guacamole!</strong> You should check in on some of those fields below.
<button type="button" class="btn-close" data-bs-dismiss="alert" aria-label="Close"></button>
</div></pre>

Example result of including a module in an article:

[[File:using-bootstrap-components-in-joomla-4-alert-demo.png|border|Alert Demo]]

Note that without JavaScript support, the alert will appear exactly as above but a click on the close button [X] will not dismiss the alert. Also, the alert will appear on every page load.

=== Example 2: Buttons ===
Buttons may be used in HTML code without JavaScript support. This is only needed for the sometimes subtle change of style applied to buttons with a change of state, styled active. Bootstrap example code:

<pre><p><button type="button" class="btn btn-primary" data-bs-toggle="button" autocomplete="off">Toggle button</button>
<button type="button" class="btn btn-primary active" data-bs-toggle="button" autocomplete="off" aria-pressed="true">Active toggle button</button>
<button type="button" class="btn btn-primary" disabled data-bs-toggle="button" autocomplete="off">Disabled toggle button</button></p></pre>
<pre><p><a href="#" class="btn btn-primary" role="button" data-bs-toggle="button">Toggle link</a>
<a href="#" class="btn btn-primary active" role="button" data-bs-toggle="button" aria-pressed="true">Active toggle link</a>
<a href="#" class="btn btn-primary disabled" tabindex="-1" aria-disabled="true" role="button" data-bs-toggle="button">Disabled toggle link</a></p></pre>

With this style in the template user.css:
<pre>.btn.btn-primary.active {
background-color: green;
}</pre>

[[File:using-bootstrap-components-in-joomla-4-button-demo.png|border|Button Demo]]

The buttons toggle between blue and green.

=== Example 3: Carousel ===
The Carousel offers a slide show cycling through a series of images or text panes. The following example used images from the Joomla 4 Sample. Bootstrap code:

<syntaxhighlight lang="php">
<div id="carouselExampleCaptions" class="carousel slide" data-bs-ride="carousel">
<div class="carousel-indicators">
<button class="active" type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide-to="0" aria-current="true" aria-label="Slide 1"></button>
<button type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide-to="1" aria-label="Slide 2"></button>
<button type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide-to="2" aria-label="Slide 3"></button>
</div>
<div class="carousel-inner">
<div class="carousel-item active"><img class="d-block w-100" src="images/sampledata/cassiopeia/nasa1-1200.jpg" alt="..." />
<div class="carousel-caption d-none d-md-block">
<h5>First slide label</h5>
<p>Some representative placeholder content for the first slide.</p>
</div>
</div>
<div class="carousel-item"><img class="d-block w-100" src="images/sampledata/cassiopeia/nasa2-1200.jpg" alt="..." />
<div class="carousel-caption d-none d-md-block">
<h5>Second slide label</h5>
<p>Some representative placeholder content for the second slide.</p>
</div>
</div>
<div class="carousel-item"><img class="d-block w-100" src="images/sampledata/cassiopeia/nasa3-1200.jpg" alt="..." />
<div class="carousel-caption d-none d-md-block">
<h5>Third slide label</h5>
<p>Some representative placeholder content for the third slide.</p>
</div>
</div>
</div>
<button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide="prev">
<span class="visually-hidden">Previous</span>
</button>
<button class="carousel-control-next" type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide="next">
<span class="visually-hidden">Next</span>
</button>
</div>
</syntaxhighlight>

Result:

[[File:using-bootstrap-components-in-joomla-4-carousel-demo.jpg|border|Carousel Demo]]

=== Example 4: Collapse ===
Collapse is widely used in Joomla and you may not need to use a module or plugin to trigger action. The click opens a pane with extra information. Example Bootstrap code:

<syntaxhighlight lang="php">
<p>
<a class="btn btn-primary" role="button" href="#collapseExample" data-bs-toggle="collapse" aria-expanded="false" aria-controls="collapseExample"> Link with href </a>
<button class="btn btn-primary" type="button" data-bs-toggle="collapse" data-bs-target="#collapseExample" aria-expanded="false" aria-controls="collapseExample">
Button with data-bs-target
</button>
</p>
<div id="collapseExample" class="collapse">
<div class="card card-body">
Some placeholder content for the collapse component. This panel is hidden by default but revealed when the user activates the relevant trigger.
</div>
</div>
</syntaxhighlight>

Result:

[[File:using-bootstrap-components-in-joomla-4-collapse-demo.png|border|Collapse Demo]]

=== Example 5: Dropdown ===
Dropdowns are toggleable, contextual overlays for displaying lists of links and more. Example Bootstrap code:

<syntaxhighlight lang="php">
<div class="btn-group">
<button class="btn btn-danger dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false"> Action </button>
<ul class="dropdown-menu">
<li><a class="dropdown-item" href="#">Action</a></li>
<li><a class="dropdown-item" href="#">Another action</a></li>
<li><a class="dropdown-item" href="#">Something else here</a></li>
<li><hr class="dropdown-divider" /></li>
<li><a class="dropdown-item" href="#">Separated link</a></li>
</ul>
</div>
</syntaxhighlight>
Result:

[[File:using-bootstrap-components-in-joomla-4-dropdown-demo.png|border|Dropdown Demo]]

=== Example 6: Modal ===
The Modal component opens a dialog box in the middle of the screen. There are quite a few options to control the size and content of the modal. See the Bootstrap documentation for more details. Example Bootstrap code:

<syntaxhighlight lang="php">
<p><button class="btn btn-primary" type="button" data-bs-toggle="modal" data-bs-target="#exampleModal"> Launch demo modal </button></p>
<div id="exampleModal" class="modal fade" tabindex="-1" aria-labelledby="exampleModalLabel" aria-hidden="true">
<div class="modal-dialog">
<div class="modal-content">
<div class="modal-header">
<h5 id="exampleModalLabel" class="modal-title">Modal title</h5>
<button class="btn-close" type="button" data-bs-dismiss="modal" aria-label="Close"></button>
</div>
<div class="modal-body">
...
</div>
<div class="modal-footer">
<button class="btn btn-secondary" type="button" data-bs-dismiss="modal">Close</button>
<button class="btn btn-primary" type="button">Save changes</button>
</div>
</div>
</div>
</div>
</syntaxhighlight>

Result:

[[File:using-bootstrap-components-in-joomla-4-modal-demo.png|Modal Demo]]

=== Example 7: Offcanvas ===
At the moment this component is not supported in Joomla. Watch this space - coming soon!

=== Example 8: Popover ===
Popovers are like Tooltips but with a Title. They have some accessibility and performance issues so should be used with caution. Example Bootstrap code:

<pre><p><button class="btn btn-lg btn-danger" title="Popover title" type="button" data-bs-toggle="popover" data-bs-content="And here's some amazing content. It's very engaging. Right?">Click to toggle popover</button></p></pre>

Result:

[[File:using-bootstrap-components-in-joomla-4-popover-demo.png|border|Popover Demo]]

=== Example 9: Scrollspy ===
Example code:
<syntaxhighlight lang="php">
<div class="row">
<div class="col-4">
<nav id="navbar-example3" class="navbar navbar-light bg-light flex-column">
<a class="navbar-brand" href="#">Navbar</a><nav class="nav nav-pills flex-column">
<a class="nav-link active" href="#item-1">Item 1</a>
<nav class="nav nav-pills flex-column">
<a class="nav-link ms-3 my-1" href="#item-1-1">Item 1-1</a>
<a class="nav-link ms-3 my-1" href="#item-1-2">Item 1-2</a>
</nav>
<a class="nav-link" href="#item-2">Item 2</a>
<a class="nav-link" href="#item-3">Item 3</a>
<nav class="nav nav-pills flex-column">
<a class="nav-link ms-3 my-1" href="#item-3-1">Item 3-1</a>
<a class="nav-link ms-3 my-1" href="#item-3-2">Item 3-2</a>
</nav>
</nav>
</div>
<div class="col-8">
<div class="scrollspy-example" tabindex="0" data-bs-spy="scroll" data-bs-target="#navbar-example3" data-bs-offset="0">
<h4 id="item-1">Item 1</h4>
<p>Placeholder content for the scrollspy example. This one relates to item 1. Takes you miles high, so high, 'cause she’s got that one international smile. There's a stranger in my bed, there's a pounding in my head. Oh, no. In another life I would make you stay. ‘Cause I, I’m capable of anything. Suiting up for my crowning battle. Used to steal your parents' liquor and climb to the roof. Tone, tan fit and ready, turn it up cause its gettin' heavy. Her love is like a drug. I guess that I forgot I had a choice.</p>
<h5 id="item-1-1">Item 1-1</h5>
<p>Placeholder content for the scrollspy example. This one relates to the item 1-1. You got the finest architecture. Passport stamps, she's cosmopolitan. Fine, fresh, fierce, we got it on lock. Never planned that one day I'd be losing you. She eats your heart out. Your kiss is cosmic, every move is magic. I mean the ones, I mean like she's the one. Greetings loved ones let's take a journey. Just own the night like the 4th of July! But you'd rather get wasted.</p>
<h5 id="item-1-2">Item 1-2</h5>
<p>Placeholder content for the scrollspy example. This one relates to the item 1-2. Her love is like a drug. All my girls vintage Chanel baby. Got a motel and built a fort out of sheets. 'Cause she's the muse and the artist. (This is how we do) So you wanna play with magic. So just be sure before you give it all to me. I'm walking, I'm walking on air (tonight). Skip the talk, heard it all, time to walk the walk. Catch her if you can. Stinging like a bee I earned my stripes.</p>
<h4 id="item-2">Item 2</h4>
<p>Placeholder content for the scrollspy example. This one relates to item 2. Don't need apologies. There is no fear now, let go and just be free, I will love you unconditionally. Last Friday night. Don't be a shy kinda guy I'll bet it's beautiful. Summer after high school when we first met. 'Cause she's the muse and the artist. What? Wait. No, no, no, no. Thought that I was the exception.</p>
<h4 id="item-3">Item 3</h4>
<p>Placeholder content for the scrollspy example. This one relates to item 3. Word on the street, you got somethin' to show me, me. All this money can't buy me a time machine. Make it like your birthday everyday. So we hit the boulevard. You make me feel like I'm livin' a teenage dream, the way you turn me on Skip the talk, heard it all, time to walk the walk. Word on the street, you got somethin' to show me, me. It's no big deal, it's no big deal, it's no big deal.</p>
<h5 id="item-3-1">Item 3-1</h5>
<p>Placeholder content for the scrollspy example. This one relates to item 3-1. Baby do you dare to do this? This is no big deal. Yeah, you're lucky if you're on her plane. Just own the night like the 4th of July! Standing on the frontline when the bombs start to fall. So just be sure before you give it all to me.</p>
<h5 id="item-3-2">Item 3-2</h5>
<p>Placeholder content for the scrollspy example. This one relates to item 3-2. You're original, cannot be replaced. All night they're playing, your song. California girls we're undeniable. Like a bird without a cage. There is no fear now, let go and just be free, I will love you unconditionally. I can see the writing on the wall. You could travel the world but nothing comes close to the golden coast.</p>
</div>
</div>
</div>
</syntaxhighlight>

Result:

[[File:using-bootstrap-components-in-joomla-4-scrollspy-demo.png|border|Scrollspy Demo]]

Also, some styling is needed in user.css:

<pre>.scrollspy-example {
height: 350px;
overflow-y: scroll;
}</pre>

Snag: the menu does not coordinate well with the content in this example!

=== Example 10: Tab ===
Tabs are often used as navigation elements combined with dropdowns. Bootstrap example code:

<syntaxhighlight lang="php">
<ul class="nav nav-tabs">
<li class="nav-item"><a class="nav-link active" href="#" aria-current="page">Active</a></li>
<li class="nav-item dropdown"><a class="nav-link dropdown-toggle" role="button" href="#" data-bs-toggle="dropdown" aria-expanded="false">Dropdown</a>
<ul class="dropdown-menu">
<li><a class="dropdown-item" href="#">Action</a></li>
<li><a class="dropdown-item" href="#">Another action</a></li>
<li><a class="dropdown-item" href="#">Something else here</a></li>
<li><hr class="dropdown-divider" /></li>
<li><a class="dropdown-item" href="#">Separated link</a></li>
</ul>
</li>
<li class="nav-item"><a class="nav-link" href="#">Link</a></li>
<li class="nav-item"><a class="nav-link disabled" tabindex="-1" href="#" aria-disabled="true">Disabled</a></li>
</ul>
</syntaxhighlight>

Result:

[[File:using-bootstrap-components-in-joomla-4-tab-demo.png|border|Tab Demo]]

Remember to check both the Tab and Dropdown options for the dropdown part to work.

=== Example 11: Toast ===
Toasts are lightweight notifications designed to mimic the push notifications that have been popularized by mobile and desktop operating systems. They’re built with flexbox, so they’re easy to align and position. Example Bootstrap code:

<syntaxhighlight lang="php">
<div class="toast fade show" role="alert" aria-live="assertive" aria-atomic="true">
<div class="toast-header">
<img class="rounded me-2" src="..." alt="..." />
<strong class="me-auto">Bootstrap</strong> <small>11 mins ago</small>
<button class="btn-close" type="button" data-bs-dismiss="toast" aria-label="Close"></button>
</div>
<div class="toast-body">Hello, world! This is a toast message.</div>
</div>
</syntaxhighlight>

Result:

[[File:using-bootstrap-components-in-joomla-4-toast-demo.png|border|Toast Demo]]

Note that the Bootstrap demo that uses a button to show the Toast message needs some extra JavaScript. It seems this component needs a coder to make good use of it!

=== Example 12: Tooltip ===
A tooltip is a small piece of text that appears on hover over a button or link element to explain what it is or does. The tooltip can be positioned above or below or to the left or right of the element. If not specified the default position is top. The tooltip will switch to another position if there is insufficient room in the specified position. Example Bootstrap code:

<pre><p><button class="btn btn-secondary" title="Tooltip on left" type="button" data-bs-toggle="tooltip" data-bs-placement="left"> Tooltip on left </button>
<button class="btn btn-secondary" title="Tooltip" type="button" data-bs-toggle="tooltip"> Tooltip </button>
<button class="btn btn-secondary" title="Tooltip on top" type="button" data-bs-toggle="tooltip" data-bs-placement="top"> Tooltip on top </button>
<button class="btn btn-secondary" title="Tooltip on right" type="button" data-bs-toggle="tooltip" data-bs-placement="right"> Tooltip on right </button>
<button class="btn btn-secondary" title="Tooltip on bottom" type="button" data-bs-toggle="tooltip" data-bs-placement="bottom"> Tooltip on bottom </button>
<button class="btn btn-secondary" title="<em>Tooltip</em> <u>with</u> <b>HTML</b>" type="button" data-bs-toggle="tooltip" data-bs-html="true"> Tooltip with HTML </button></p>
<p>Tooltip triggered by class: <button class="btn btn-warning" title="Tooltip Message">Alert!</button></p>
</pre>

Result:

[[File:using-bootstrap-components-in-joomla-4-tooltip-demo.png|border|Tooltip Demo]]

== Approach 2: Using a Content Plugin ==
The steps involved:

* Download, install and enable this plugin: https://github.com/ceford/j4xdemos-plg-bscompos/raw/master/plg_j4xdemos_bscompos.zip
* In the article add the text that the plugin acts on, for example ''{bscompos modal carousel}'' will trigger loading of the JavaScript necessary to support a modal dialog and a carousel. The plugin removes the trigger text and enclosing (now) empty <nowiki><p></p></nowiki> tags.
* Include the Bootstrap Component HTML code directly in the article or in a module included in the article. There is example HTML code below for a simple Modal and a Modal containing a Carousel. Note that this will not work if the HTML code is in a module in a template location.
* This will also work for a standard Custom module if the ''Prepare Content Option'' is set to ''Yes''.
* Test it!

== Approach 3: Using a Template Override ==
The steps involved:
* Create a mod_custom template override.
* Add a mod_custom module containing the component markup and trigger classes.
* Include the module in an article.

=== The mod_custom Template Override ===
* In the Administrator interface go to {{rarr|System, Site Templates, Cassiopeia Details and Files}}.
* Select {{rarr|Create Overrides, mod_custom, default.php}}.
* On the line following ''defined('_JEXEC') or die;'' add this code:
<pre>$module_class = $params->get('moduleclass_sfx');
if (!empty($module_class))
{
$classes = explode(' ', $module_class);
foreach ($classes as $class)
{
switch ($class)
{
case 'bs-alert':
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.alert', '.alert');
break;
case 'bs-button':
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.button', '.btn');
break;
case 'bs-carousel':
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.carousel', '.selector', []);
break;
case 'bs-collapse':
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.collapse', '.selector', []);
break;
case 'bs-dropdown':
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.dropdown', '.selector', []);
break;
case 'bs-modal':
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.modal', '.selector', []);
break;
case 'bs-offcanvas':
// Not Found
//\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.offcanvas', '.btn', []);
break;
case 'bs-popover':
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.popover', '.btn', []);
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.popover', 'a', []);
break;
case 'bs-scrollspy':
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.scrollspy', '.selector', []);
break;
case 'bs-tab':
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.tab', '.selector', []);
break;
case 'bs-tooltip':
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.tooltip', '.btn', []);
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.tooltip', 'a', []);
break;
case 'bs-toast':
\Joomla\CMS\HTML\HTMLHelper::_('bootstrap.toast', '.selector', []);
break;
default:
// do nothing
}
}
}
</pre>
This code searches for class names set in mod_custom and makes the HTMLHelper call to set up the JavaScript support. Note that the last item in each call is a selector that may or may not be used to trigger action. Many of the components are triggered by data attributes in the mark-up and they do not use the selectors here. For some, the selector is needed. For example, it makes sense to use the '''.btn''' class and the '''a''' tag to trigger Tooltips.

=== A ''mod_custom'' Module for a Modal Component ===
* Go to {{rarr|Content, Site Modules, New}}.
* Select the '''Custom''' module.
* Fill out the form:
** Title: Demo Modal
** In the Position field type in '''demomodal''' for use in an article;
** Module Content: Toggle Editor for plain text entry.
** Paste in the following code from the Bootstrap documentation:

<syntaxhighlight lang="php">
<h2>Modal</h2>

<p><button class="btn btn-primary" type="button" data-bs-toggle="modal" data-bs-target="#exampleModal"> Launch demo modal </button></p>

<div id="exampleModal" class="modal fade" tabindex="-1" aria-labelledby="exampleModalLabel" aria-hidden="true">
<div class="modal-dialog">
<div class="modal-content">
<div class="modal-header">
<h5 id="exampleModalLabel" class="modal-title">Modal title</h5>
<button class="btn-close" type="button" data-bs-dismiss="modal" aria-label="Close"></button>
</div>
<div class="modal-body">
...
</div>
<div class="modal-footer">
<button class="btn btn-secondary" type="button" data-bs-dismiss="modal">Close</button>
<button class="btn btn-primary" type="button">Save changes</button>
</div>
</div>
</div>
</div>
</syntaxhighlight>
* Select the Advanced tab and in the Module Class field enter '''bs-modal'''
* Optional: set Ttitle to Hide to use the H2 in the pasted code.
* Save and Close (do not worry that the modal looks all wrong in the editor).

=== Create an Article and Menu Item ===
* Create a new article, Demo Modal, and in plain text entry mode set the content to <pre><div>{loadposition demomodal}</div></pre>
* Create a Single Article menu item.
* Test it:
[[File:Demomodal.png|none|Bootstrap Modal in an Article]]

=== A Modal Component Containing a Carousel ===
* Create a new Custom module with a new Title: Demo Modal Carousel
* Position: demomodalcarousel
* {{rarr|Advance tab, Module Class}}: bs-modal bs-carousel
* Module Custom content in plain text:

<syntaxhighlight lang="php">
<h2>Modal with Carousel</h2>
<div class="mod-custom custom">

<button class="btn btn-primary" type="button" data-bs-toggle="modal" data-bs-target="#exampleModal"> Launch demo modal </button>
</div>
<div id="exampleModal" class="modal fade" style="display: none;" tabindex="-1" aria-hidden="true">
<div class="modal-dialog" role="document">
<div class="modal-content">
<div class="modal-header">
<button class="close" type="button" data-bs-dismiss="modal" aria-label="Close">
<span aria-hidden="true">×</span>
</button>
</div>
<div class="modal-body">
<div id="carouselExampleCaptions" class="carousel slide" data-bs-ride="carousel">
<div class="carousel-indicators">
<button class="active" type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide-to="0" aria-current="true" aria-label="Slide 1"></button>
<button type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide-to="1" aria-label="Slide 2"></button>
<button type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide-to="2" aria-label="Slide 3"></button>
</div>
<div class="carousel-inner">
<div class="carousel-item active">
<img class="d-block w-100" src="images/sampledata/cassiopeia/nasa1-1200.jpg" alt="..." />
<div class="carousel-caption d-none d-md-block">
<h5>First slide label</h5>
<p>Some representative placeholder content for the first slide.</p>
</div>
</div>
<div class="carousel-item">
<img class="d-block w-100" src="images/sampledata/cassiopeia/nasa2-1200.jpg" alt="..." />
<div class="carousel-caption d-none d-md-block">
<h5>Second slide label</h5>
<p>Some representative placeholder content for the second slide.</p>
</div>
</div>
<div class="carousel-item">
<img class="d-block w-100" src="images/sampledata/cassiopeia/nasa3-1200.jpg" alt="..." />
<div class="carousel-caption d-none d-md-block">
<h5>Third slide label</h5>
<p>Some representative placeholder content for the third slide.</p>
</div>
</div>
</div>
<button class="carousel-control-prev" type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide="prev">
<span class="visually-hidden">Previous</span>
</button>
<button class="carousel-control-next" type="button" data-bs-target="#carouselExampleCaptions" data-bs-slide="next">
<span class="visually-hidden">Next</span>
</button>
</div>
</div>
</div>
</div>
</div></syntaxhighlight>
* Create a new Article with <nowiki><div>{loadposition demomodalcarousel}</div></nowiki> in the content.
* Create a new single article menu item: Demo Modal Carousel
* Test it:
[[File:Demomodalcarousel.png|Demo Modal containing a Carousel]]

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

J3.x:Sharing layouts across views or extensions with JLayout

2023-09-21T23:18:42Z

Cmb: Several markup changes.

<noinclude><languages /></noinclude>
<noinclude>{{Joomla version|version=3.x|comment=<translate>
series</translate>}}</noinclude>
<translate>
It is common that parts of pages are replicated across several views inside an extension, or even across several extensions. Examples might be:</translate>

<translate>
* An extension sharing some display layouts between Frontend and Backend views, or with one or more modules
* Backend extensions that have some common settings, and thus have to replicate common display layouts to allow users to change them</translate>

<translate>
Up until Joomla! 3.0, the loading (and template overriding) of layout files was restricted to a given view.
The JLayout interface and set of classes was added to Joomla! 3.0 to help solve this very problem. It encapsulates a layout and the data required to display it so that they can be reused across views and extensions.
At the time of writing, JLayout is used by the JHtmlSidebar class to display the submenu and filters found in most Backend extensions pages.</translate>

<translate>
JLayout consists in an interface and two classes:


* JLayout interface defines escape and render methods, much like the JView class of Joomla! platform
* JLayoutBase implements a basic layout class, where layout may be hard-coded in the class itself, for instance
* JLayoutFile, the most commonly used class, wraps and render a layout stored in a file, checking for overrides in template before doing so.</translate>

<translate>
Here is a basic usage example of JLayoutFile:</translate>
<syntaxhighlight lang="php">// Create a layout object and ask it to render the sidebar
$layout = new JLayoutFile('joomla.sidebars.submenu', $basePath = null);
$sidebarHtml = $layout->render($data);</syntaxhighlight>

<translate>
Executing this code creates a JLayoutFile object, wrapping a layout file, and passing in a $data structure that may be required for the display itself.</translate>

<translate>
The first parameter, 'joomla.sidebars.submenu' is the file identifier. The last part ('submenu')is the file name, everything before ('joomla.sidebars') is the relative path. An optional $basePath parameter can be prepended to the relative path. If $basePath is missing, layout files will be searched inside the /layouts directory.


Our example:</translate>
<syntaxhighlight lang="php">new JLayoutFile('joomla.sidebars.submenu', $basePath = null)</syntaxhighlight>

<translate>
will result in the 'submenu.php' layout file being loaded from the '/layouts/joomla/sidebars' directory.


Passing in a non-empty base path allows accessing and storing layout files anywhere on the site directory structure, for instance:</translate>

<syntaxhighlight lang="php">$layout = new JLayoutFile('my_layout', JPATH_ROOT .'/components/com_something/layouts');
$html = $layout->render($data);</syntaxhighlight>

<translate>
will load and render the 'my_layout.php' layout file found in JPATH_ROOT .'/components/com_something/layouts' directory.


Setting the client parameter as 3rd parameter allows loading layout files from the frontend directory also in the backed, for instance:</translate>

<syntaxhighlight lang="php">$layout = new JLayoutFile('my_layout', NULL, array('client' => 0));
$html = $layout->render($data);</syntaxhighlight>

<translate>
will load and render the 'my_layout.php' layout file found in JPATH_ROOT .'/components/com_something/layouts' directory but could still be overridden in the template.


'''Template Overrides'''</translate>

<translate>
When executing the render() method, that is actually loading the layout file, JLayoutFile will check for the existence of an override in the currently selected template, inside a 'layouts' directory. Looking back at our initial example, should you want to override the sidebar layout of all backend Joomla! extensions, you should place a 'submenu.php' file under:
/administrator/templates/{currently_selected_template}/html/layouts/joomla/sidebars/</translate>

<translate>
Note: JLayoutFile will check the currently selected template for overrides. As layouts can be shared across both the Frontend and Backend, if you need to override a layout file in both cases, you'll have to put an override file in both Backend and Frontend template.</translate>

<translate>
'''Storing Layouts'''</translate>

<translate>
Layouts files can basically be stored anywhere, as a full base path can be specified when using them (and still allow template override). However, for consistency and to avoid name clashes, we would recommend the following:</translate>

<translate>
* default to storing layout files in your extension own admin layouts folder. For instance: /administrator/components/com_example/layouts
* if your extension doesn't have an administrative folder (front-end only component, module, plugin), then use a layouts folder such as:
**/components/com_example/layouts
**/plugins/content/example/layouts
**/modules/mod_example/layouts</translate>

<translate>
In addition, note that the folder itself '''must''' be named ''layouts''.
Using the root ''/layouts'' folder is normally reserved for Joomla! itself, and possibly other "official" applications in the future such as the installer.</translate>
<translate>
Lastly, though not mandatory, I advise you to put all layout files under an additional ''com_example'' or ''mod_example'' subfolder inside the main ''layouts'' folder. This serves no purpose for your extension, however, should a template override layouts for several extensions, this would avoid possible name collisions.
For instance, if two extensions use the "filters.search_all" JLayout, then a template cannot provide a separate override for each. A single override will be used for both extension, which may not be desirable.
Using "com_example_1.filters.search_all" and "com_example_2.filters.search_all" allows templates to provide overrides for layouts, even if they have the same id.</translate>

<translate>
'''Examples'''


Here is a simple example.


Create a file, /layouts/joomla/content/helloworld.php:</translate>

<syntaxhighlight lang="php">
<?php
defined('JPATH_BASE') or die;

?>
<div id="helloworld">
<h1>Hello World!</h1>
</div>
</syntaxhighlight>

<translate>
Then in any layout file, such as components/com_content/views/article/tmpl/default.php add:</translate>

<syntaxhighlight lang="php">
<?php
$layout = new JLayoutFile('joomla.content.helloworld');
echo $layout->render();
?>
</syntaxhighlight>

<translate>
View an article on the front end and you will see Hello World!.
Of course often you will want to pass some data via the render() method.


A simple example of that might be:</translate>

<syntaxhighlight lang="php">
<?php
defined('JPATH_BASE') or die;

?>
<div id="helloworld">
<h1>Hello <?php echo $displayData['name']; ?>!</h1>
</div>
</syntaxhighlight>

<translate>
(Note that the variable passed in to the layout is called $displayData)


With the corresponding PHP</translate>

<syntaxhighlight lang="php">
<?php
$layout = new JLayoutFile('joomla.content.helloworld');
$data = array('name' => 'Bob');
echo $layout->render($data);
?>
</syntaxhighlight>

<translate>
Now when you view your article you should see ''Hello Bob!''


For additional information, you can also read this article on the Joomla! Community Magazine™: [http://magazine.joomla.org/issues/issue-nov-2013/item/1590-jlayout-layouts-improvements-joomla-3-2 JLayout Improvements for Joomla! 3.2] by Roberto Segura.</translate>

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

J4.x:Cassiopeia Template Folders and Files

2023-09-21T23:03:51Z

Cmb: Some markup changes.

<noinclude>{{Joomla version|version=4.x}}</noinclude>
== Introduction ==

Newcomers to Joomla, sometimes new to PHP too, may know little of the architecture of a Joomla website and how it all comes together to present a website to the end user. That was me in 2010! However, having arrived here you will realise that Cassiopeia is a Site Template that controls the appearance of a site as seen by the general public. Administrators use a different template, Atum, with a completely different appearance. These templates are sometimes referred to as Frontend and Backend templates.

A template is a Joomla extension that consists of a collection of files that take care of different aspects of the presentation. A website may have a number of site templates, one of which must be chosen as the default template used by all pages unless another specific template is selected for a specific page. And site templates may be present but unused.

This tutorial explains the use of the various files in the default Cassiopeia site template.

== Changes from Joomla 4.0 to Joomla 4.1 ==

Joomla 4.1 has moved the default media files from the templates folder to the media/templates folder. Existing media folders are moved on upgrade.

== File Structure ==

The following illustration shows the folder structure of the Cassiopeia template, including the files in the template root.

{| class="wikitable"
|-
! Joomla 4.0 !! Joomla 4.1
|-
| [[File:j4x-cassiopeia_template_explained_file_structure.png|Joomla 4.0 File Structure]] || [[File:j4x-cassiopeia_template_explained_file_structure_41.png|Joomla 4.1 File Structure]]
|}

A lot to explain! A brief starter explanation:

* css - the folder containing all of the template CSS files
* html - a folder containing component and module overrides, which may be empty
* images - a folder for images used by the template and its styles
* js - a folder for JavaScript used by the template
* scss - a folder for the scss files compiled to make the CSS files
* component.php - a layout used to display just a component without surrounding modules
* error.php - a simple layout used to display errors when a normal page cannot be displayed
* index.php - the layout used for all site pages using this template
* joomla.asset.json - a file specifying where to find CSS and JavaScript resources
* offline.php - a layout used to show a site is off-line for maintenance
* template_preview.php and template_details.php - images used for administration
* templateDetails.xml - the extension specification used for installation

Where to start?

== ''index.php'' ==

You are probably aware that a very simple HTML page looks like this:

<syntaxhighlight lang="php">
<html>
<head>
</head>
<body>
<h1>Hello World!</h1>
<p>Message of the day.</p>
</body>
</html>
</syntaxhighlight>

That is what is in index.php except that it is a little more complicated. Have a look through the file with a text editor and note the following:

* The first executable statement is '''defined('_JEXEC') or die;''' - every Joomla PHP file starts like that to prevent calling directly via an absolute URL. _JEXEC is defined when a page is accessed via mydomain.com/[site-root/]index.php (usually with index.php left off as that is used by default).
* The actual HTML output starts with '''<!DOCTYPE html>''' on line 127 - everything before that is PHP code to set needed variables.
* The head and the body contain '''jdoc:include''' statements that cause insertion of specific types of content - more on that later.
* The body contains landmarks such as header, main, and footer - accessibility features.
* The overall layout is achieved with grids - included only where the grid positions actually include modules.

=== Favicons ===
Favicons are the small icons that appear in the browser tab alongside your site name. Near the top of index.php are three instructions to load favicons into the page:
<syntaxhighlight lang="php">
// Browsers support SVG favicons
$this->addHeadLink(HTMLHelper::_('image', 'joomla-favicon.svg', '', [], true, 1), 'icon', 'rel', ['type' => 'image/svg+xml']);
$this->addHeadLink(HTMLHelper::_('image', 'favicon.ico', '', [], true, 1), 'alternate icon', 'rel', ['type' => 'image/vnd.microsoft.icon']);
$this->addHeadLink(HTMLHelper::_('image', 'joomla-favicon-pinned.svg', '', [], true, 1), 'mask-icon', 'rel', ['color' => '#000']);
</syntaxhighlight>

Joomla will look for the favicons first in media/templates/cassiopeia/images - they are not there so Joomla will look in media/system/images - they are there so Joomla will load the URLs for the images there. If you want to use your own favicons rather than Joomla favicons you upload them to media/templates/cassiopeia/images. You can do that using the Templates: Customise form. They will not be affected by any update to the Cassiopeia template.

=== Template Variables ===
If you look through the template you will find lines containing $this->params->get(...) like this one:

<syntaxhighlight lang="php">
$paramsColorName = $this->params->get('colorName', 'colors_standard');
</syntaxhighlight>

Those parameters are set in the Advance tab of the Template: Edit Style page. That is where you can change the brand, logo, colour, layout, etc. The variables are defined in the templateDetails.xml file.

=== The Web Asset Manager ===
Notice the line near the top of index.php that creates an instance of the web asset manager and later lines that use it:

<syntaxhighlight lang="php">
$wa = $this->getWebAssetManager();
...
$wa->registerAndUseStyle($assetColorName, $templatePath . '/css/global/' . $paramsColorName . '.css');
</syntaxhighlight>

Joomla uses information in joomla.asset.json to load assets needed by the template. A portion of that file is shown here:

<syntaxhighlight lang="php">
{
"$schema": "https://developer.joomla.org/schemas/json-schema/web_assets.json",
"name": "cassiopeia",
"version": "4.0.0",
"description": "This file contains details of the assets used by Cassiopeia, the default Joomla 4 site template.",
"license": "GPL-2.0-or-later",
"assets": [
{
"name": "template.cassiopeia.ltr",
"description": "The css file to be used when the site is left to right (LTR).",
"type": "style",
"uri": "template.min.css",
"dependencies": [
"fontawesome"
]
},
</syntaxhighlight>

It shows that the asset named template.cassiopeia.ltr is to be found in in css/template.min.css and that asset in turn requires fontawesome, defined at the end of joomla.assets.json. Note that if you switch to debug mode, Joomla will load the versions of CSS and JavaScript without the .min part.

=== The ''jdoc'' Statements ===
At some point during page creation the template index.php file is parsed (analysed) by the Joomla code and the jdoc statements picked out in reverse order. Each jdoc statement leads to code to generate a block of HTML to replace that statement. Amongst other things, that puts module content into the page.

== The CSS Files ==
The ''css'' folder contains the CSS files used by the Cassiopeia template. It is worth noting the file sizes of the different variants of a single CSS style sheet. For example ''template.css'' has these varieties:

* template.css 258,272 bytes
* template.min.css 205,427 bytes
* template.min.css.gz 32,526 butes

The first, template.css is a human-readable variant that is used when system debugging is enabled. The second, template.min.css is used on production sites where debugging is disabled. It has all white space removed and some optimisations made. The third, template.min.css.gz is a Gzip compressed variant of the min version used if the site ''.htaccess'' file is set up to offer Gzip variants of static resources. There is an article describing how do this in the [https://magazine.joomla.org/all-issues/december-2021/joomla-performance-tuning-ii-basic-settings Community Magazine].

Clearly the ''gz'' version is the most network bandwidth friendly.

=== ''user.css'' ===
Absent from the initial list of CSS files is user.css. This is a file that you create yourself to contain additions and overrides to the existing styles. For example, module parameters typically include a Module Class text entry box in the Advanced tab. Any module class you add there should have an entry in user.css. If you wish to override an existing style you can make an entry like this:

<syntaxhighlight lang="php">
h1, .h1 {
color: purple;
}
</syntaxhighlight>

== The HTML Files ==
This is the place to keep module, component, plugin and layout template overrides. For example, when Joomla renders a module it first looks for a template here and then in the modules own tmpl folder. This allows you to override the appearance of a core Joomla extension or a third party extension without changing the original code. Any changes made there would be overwritten by an update.

The default Cassiopeia template comes with overrides for layouts, mod_custom, mod_menu and tinymce.

== The JavaScript Files ==
There is only one basic JavaScript file used by the template and like CSS it comes in three varieties: template.js, template.min.js and template.min.js.gz. There is one other variety of interest: template.es5.js, which is coded for EcmaScript 5 (the 2011 version). All of the other JavaScript files are coded for later EcmaScript versions.

EcmaScript is currently up to Version 12 but it takes a while for browsers to catch up and adopt a new standard. JavaScript is a synonym for EcmaScript. See [https://en.wikipedia.org/wiki/ECMAScript Wikipedia] for a summary.

== The SCSS Files ==
The SCSS files contain the sources used to create the CSS files. They need to be compiled with a third party compiler. More...

== Template Positions ==
The positions in which modules can be placed are named in the templateDetails.xml file:

<syntaxhighlight lang="xml">
<positions>
<position>topbar</position>
<position>below-top</position>
<position>menu</position>
<position>search</position>
<position>banner</position>
<position>top-a</position>
<position>top-b</position>
<position>main-top</position>
<position>main-bottom</position>
<position>breadcrumbs</position>
<position>sidebar-left</position>
<position>sidebar-right</position>
<position>bottom-a</position>
<position>bottom-b</position>
<position>footer</position>
<position>debug</position>
</positions>
</syntaxhighlight>

The following illustration shows in schematic form where those positions occur on the page:

[[File:j4x-cassiopeia_template_explained_positions.png|Template Positions]]

Notice the '''component''' position marked with a green background. That is where the output from a component view is placed and is often the largest portion of the page. Immediately above that is the message position where Joomla system messages appear. For example, ''Your changes have been saved''.

The illustration shows that some of the positions are within landmarks such as '''header''' and '''footer''' but others are not. Something to look into!

With the sample data installed, the following illustration shows the Home page landmarks in the browser tools '''Inspector''' view.

[[File:j4x-cassiopeia_template_explained_inspector_landmarks.png|Template Landmarks]]

The header contains a '''brand''' location, not a position to which a module can be assigned. It can be left out. Beneath that is a '''menu''' and/or '''search''' position. It is used for the site menu and search box.

The contents of the remaining divs are self-evident from their class names. There is no container-sidebar-left because the sample data does not assign any module to that position.

== Further Information ==
* [[J4.x:Cassiopeia Template Customisation|Cassiopeia Template Customisation]] - using the Edit Style form and user.css
* [[J4.x:Cassiopeia Template Simplified - A Case Study|Cassiopeia Template Simplified - A Case Study]] - a simple template based on Cassiopeia

<noinclude>
[[Category:Tutorials]]
[[Category:Joomla! 4.x]]
</noinclude>

J3.x:Layout Overrides in Joomla

2023-09-21T13:32:09Z

Cmb: Replaced deprecated 'source' tags with 'syntaxhighlight' tags. Other markup changes.

<noinclude><languages /></noinclude>
{{version/tutor|3.x}}
<translate>
=== Introduction to Alternative Layout Feature === 
</translate>
<translate>
Joomla has a comprehensive set of features that give the site administrator more control over the display of all HTML output from their template. There are five types of alternative layouts:</translate>
# <translate>
Module</translate>
# <translate>
Component</translate>
# <translate>
Category</translate>
# <translate>
Menu Item</translate>
# <translate>

JLayouts</translate>

<translate>
Alternative layouts work in a similar fashion to the template override feature but allow you more options and control. Each type is discussed below.</translate>

<translate>
=== Module Alternative Layouts === 
</translate>
<translate>
Creating an alternative layout for a module is similar to creating a template override for a module. In both cases, you create a folder called ''templates/<your template>/html/<module name>''. For example, the folder for a ''mod_login'' template override or alternative layout for the beez3 template would be ''templates/beez3/html/mod_login/''.</translate>

<translate>
There are two important differences between a template override and an alternative layout. The first is the file name. For the template override, you would call the file <tt>default.php</tt> to match the core file name. For an alternative layout, you use a different name. The only rule is that '''the file name should not have any underscores in it'''. This allows you to have complex layouts that include multiple files. The initial file to be called is named without underscores and any other files that are called from this initial file will have underscores in the name. For example, you could have the initial file called <tt>mynewlogin.php</tt> which calls <tt>mynewlogin_1.php</tt>.</translate>

<translate>
The second important difference is that, unlike template override files which are called automatically whenever the module is displayed using the template with the override, an alternative layout file is only called if you select it as a parameter in the Module Manager. In version 2.5 and later, there is a new parameter under Advanced Options called Alternative Layout, as shown below.</translate>

[[Image:Screenshot_override_tutorial_j3_<translate>
en</translate>.png|frame|center]]

<translate>
This parameter will list any files (without underscores) that you have placed in the template folder for this module. You can also translate the file name using the template's system language file (Note this keeps things simple in these examples but best practice is using Joomla's [[J3.x:Language_Overrides_in_Joomla|Language Override]] tool to create this string rather than modifying the template language file). For example, if you add the line</translate>

<syntaxhighlight lang="ini">TPL_BEEZ3_MOD_LOGIN_LAYOUT_NOLOGIN="Alt Login Layout"</syntaxhighlight>

<translate>
to the file <tt>en-GB.tpl_beez3.sys.ini</tt>, it will translate the file name <tt>nologin.php</tt> to "Alt Login Layout".</translate>

<translate>
It is important to understand that if specified in the Module Manager screen, an alternative layout file for a module will be used for that module regardless of what template is used to display the page where the module is shown. It is therefore the administrator's responsibility to make sure that the layout file will work as desired in any templates where this module may be shown.</translate>

<translate>
=== Plugin Alternative Layouts (Overriding a Plugin) === 
</translate>
<translate>
Yes, it's possible to override plugin outputs. It's very useful, especially for content plugins. However you can only do it if the plugin is ready to allow overrides.</translate>

{{tip|<translate>
Joomla provides a mechanism to override a plugin but this feature is not supported by all the plugins</translate>}}

<translate>
Right now the only plugin in Joomla 3.x core that allow overrides is the Pagenavigation Content plugin that shows previous/next article links in article view of content component. There may be other plugins from third party developers allowing it and more core plugins will be overridable in the future.</translate>

<translate>
You will know when a plugin is overridable because has a ''/tmpl/'' folder in it. See: https://github.com/joomla/joomla-cms/tree/staging/plugins/content/pagenavigation (note for developers: the plugin uses <tt>JPluginHelper::getLayoutPath()</tt> )</translate>

<translate>
==== Plugin Override Example ==== 
</translate>
<translate>
To override the output of '''Pagenavigation content plugin''' in "beez3" template, create a folder named <tt>templates/beez3/html/plg_content_pagenavigation/</tt> and copy the original layout file (<tt>plugins/content/pagenavigation/tmpl/default.php</tt>) to this new folder.</translate>

<translate>
Now you can change this layout file to override plugin output.</translate>

<translate>
Is important to note that to build the override layout you need to create it in this path:</translate>

templates/TEMPLATE-NAME/html/plg_PLUGIN-GROUP_PLUGIN-NAME/

<translate>
example:</translate>
<tt>templates/beez3/html/plg_content_pagenavigation/</tt>

<translate>
Where PLUGIN-GROUP is the group to which the plugin belongs. (It is the name of the first folder where the plugin is located. See: https://github.com/joomla/joomla-cms/tree/staging/plugins. Read more about Event groups at [[S:MyLanguage/Plugin/Events|Plugin/Events]])</translate>

<translate>
=== Component Alternative Layouts === 
</translate>
<translate>
Component alternative layouts work similarly to module layouts discussed above. Again, a file is placed in the same folder where you place a template override file. For example, to create an alternative layout for an article for the template ''beez3'', you would put a file in the folder <tt>templates/beez3/html/com_content/article/</tt>. As with module layouts, the file must not be named the same as the core file and must not include underscores in the name. Additionally, there should not be an XML file of the same name in this folder. (We'll discuss XML files below under Menu Item Alternative Layouts.)</translate>

<translate>
You can set a global value for component layouts in the Options window of the component. For example, in the Article Manager Options window, there is a parameter for Alternative Layout as shown below:</translate>

[[Image:article_manager_alternative_layout_j3_<translate>
en</translate>.png|800px|center]]

<translate>
This will create a global value that individual components (articles, contacts, news feeds and Web links) can inherit from.</translate>

<translate>
As with module layouts, the component layouts are shown as parameter options in the individual component edit screen. For example, for an article, the parameter shows in the Article Options group as shown below.</translate>

[[Image:article_alternative_layout_j3_<translate>
en</translate>.png|frame|center]]

<translate>
As with other parameters, the Use Global setting will use the setting from the Options parameter. The From Component's Default setting will use the component's default layout. Alternative layouts that you have created for different templates are shown under each template heading.</translate>

<translate>
File names may be translated. The line below:</translate>

<syntaxhighlight lang="ini">TPL_BEEZ3_COM_CONTENT_ARTICLE_LAYOUT_MYLAYOUT="Title Only No XML"</syntaxhighlight>

<translate>
will translate a file called ''mylayout.php'' as ''Title Only No XML''.</translate>

<translate>
You can have more than one file for a layout. The initial file must be named without underscores and any additional files must have underscores.</translate>

<translate>
Component alternative layouts may be used with articles, contacts, or news feeds. Web links don't have a single-component layout so no alternative layout is available for web links.</translate>

<translate>
Component alternative layouts are only used when two conditions are met: (1) they are specified in the component parameters; and (2) there is no menu item for this specific component. For example, if you have one or more menu items of type "Single Article" set up for a given article, then the alternative layout for that article will not be used. Instead, the layout specified in the menu item will be used. This is consistent with the general way that component parameters work, where the most specific (in this case a single-article menu item) overrides the less specific (in this case, the article parameters).</translate>

<translate>
=== Category Alternative Layouts === 
</translate>
<translate>
Category alternative layouts work identically to component layouts. The rules for specifying layout files are the same. The only difference is that the folder is the category folder, not the component folder. For example, a contact category alternative layout for beez3 would go in the folder <tt>templates/beez3/html/com_contact/category</tt>.</translate>

<translate>
You can set category layouts globally, in the Options screen of each component. Below is an example from the Contact Manager Options screen:</translate>

[[Image:contact_component_options_category_alternative_layout_j3_<translate>
en</translate>.png|frame|center]]

<translate>
Category alternative layouts show up when you add or edit a category in the Category Manager under the Basic Options as shown below.</translate>

[[Image:category_options_alternative_layout_j3_<translate>
en</translate>.png|frame|center]]

<translate>
Category alternative layouts may be used for articles, contacts, news feeds and Web links.</translate>

<translate>
As with component layouts, category layouts only will show if (1) they are specified for the category in the global or category parameters and (2) there is no menu item specifically for this category (for example, List Contacts in a Category, List News feeds in a Category, List Web links in a Category, Category List, Category Blog).</translate>

<translate>
If there is a menu item set up for this specific category, that layout will be used instead of the alternative category layout.</translate>

<translate>
=== Drill Down to Blog or List === 
</translate>
<translate>
For articles, we have two core layouts available: Blog and List. Both of these options show under the "From Component" heading in the layout parameters for article category. So, like other layout options, you can now select Blog or List for categories either globally (in the Article Manager Options, shown below), or when editing a single article category.</translate>

[[Image:article_manager_category_blog_alternative_layout_j3_<translate>
en</translate>.png|frame|center]]

<translate>
This means that, like other layout options, you can control whether article category links drill down to blog or list layouts. It is important to understand that, like other layout parameters, this option will only take effect when there is no single-category menu item for the category.</translate>

<translate>
=== Alternative Menu Items === 
</translate>
<translate>
Alternative Menu Items have one important difference with the others. To create a menu item alternative layout, you must include an XML file whose name matches the initial layout file. For example, to create an alternative menu item called "myarticle" for an article in the beez3 template, you would create two files in the <tt>templates/beez3/html/com_content/article</tt> folder called <tt>myarticle.php</tt> and <tt>myarticle.xml</tt>. If you wanted to include more layout files, you would add these files with underscores in the file names.</translate>

<translate>
The XML file uses the same format as the core Menu Item XML files. This allows you not only to create a customized layout for this menu item but also allows you to create customized parameters. For example, you could hide some parameters or add new parameters.</translate>

<translate>
Alternative Menu Items show up when you select a menu item type in the Menu Manager as shown below.</translate>

[[Image:menu_manager_alternative_menu_items_j3_<translate>
en</translate>.png|800px|center]]

<translate>
Alternative Menu Items are used and work the same way as standard menu items. Since they are already based on customized layouts, template overrides do not apply to alternative menu items.</translate>

<translate>
As indicated above, menu item layouts take priority over component or category alternative layouts.</translate>

<translate>
Translation of alternative menu items is done with the following tags in the XML files. The format is <tt>"TPL_"<template name>_<component>_<view>_<menu item name>_<tag type></tt>. For example, these lines below will translate the title, option, and description for an alternative menu item called "catmenuitem".</translate>

<syntaxhighlight lang="ini">
TPL_BEEZ3_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_TITLE="Beez3 Custom Category Layout"
TPL_BEEZ3_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_OPTION="Beez3 Custom"
TPL_BEEZ3_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_DESC="Description for beez3 custom category layout."
</syntaxhighlight>

<translate>
These strings have to be added to <tt>language/en-GB/en-GB.tpl_beez3.sys.ini</tt></translate>

<translate>
The catmenuitem.xml would start with:</translate>

<syntaxhighlight lang="XML">
<?xml version="1.0" encoding="utf-8"?>
<metadata>
<layout title="TPL_BEEZ3_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_TITLE" option="TPL_BEEZ3_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_OPTION">
<help
key = "JHELP_MENUS_MENU_ITEM_ARTICLE_SINGLE_ARTICLE"
/>
<message>
<![CDATA[TPL_BEEZ3_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_DESC]]>
</message>
</layout>
</syntaxhighlight>

<translate>
=== Controlling the Template for Alternative Menu Items === 
</translate>
<translate>
As discussed above, the presence of an XML file makes an alternative layout a menu item. The format of the XML file is the same as the format for core menu item XML files. With this XML file, you can add the parameters you wish to include for this menu item. They can be the same as one of the core menu items, or you can omit core parameters or add new ones. Note that if you add new parameters, these can be used in the layout file but will not be used in the core model or view files.</translate>

<translate>
It is also possible to override parameter settings for core parameters. One example of this is to control which templates an alternative menu item layout can be displayed with. In some cases, you may want to allow a custom menu item to be displayed with any template for the site. In other cases, you may wish to limit that menu item's layout to one specific template. In this situation, you would just add the following parameter to the menu item's XML file:</translate>

<syntaxhighlight lang="XML">
<fields>
<field
name="template_style_id"
type="templatestyle"
label="COM_MENUS_ITEM_FIELD_TEMPLATE_LABEL"
description="COM_MENUS_ITEM_FIELD_TEMPLATE_DESC"
filter="int"
template="beez3"
class="inputbox">
</field>
</fields>
</syntaxhighlight>

<translate>
This will override the core <tt>template_style_id</tt> parameter. Setting the template equal to "beez3" in this case will limit the user to only selecting template styles for the "beez3" template.</translate>
<translate>

=== JLayout Micro-Layout Overrides === 
</translate>
<translate>
JLayouts is a powerful feature of Joomla! JLayouts can be loosely defined as micro-layouts. They are the micro-layouts for individual elements of Joomla! pages. For example, the read more button, the intro image, the full image, are all examples of elements that are controlled via their own JLayout.


If you dig deeper into the Category Blog Layout view, you will find the code to call the article title, an intro image, the intro text, as well as various other relevant parts of the page. This is what it looks like when you call an element using JLayout.


<syntaxhighlight lang="php"><?php echo JLayoutHelper::render('joomla.content.blog_style_default_item_title', $this->item); ?></syntaxhighlight>


This particular bit of code calls the Article Title within the Joomla! Category Blog.


To help you understand the location of the file for this particular element, it would help to understand that there is a naming convention in play. Looking at <tt>joomla.content.blog_style_default_item_title</tt> the dots can be replaced with /'s to understand the directory structure. All JLayouts are initially found in JOOMLAROOT/layouts. Using the naming convention we can see that this file will be located in <tt>JOOMLAROOT/layouts/joomla/content/blog_style_default_item_title.php</tt>.


Let's go through an example. For this example, we will move the intro image to above the title. You could also add some additional structure around it.</translate>

<translate>
You should not edit JLayout files directly as changes would be overwritten during any core upgrade. The correct way to update the JLayout is by finding the element you want to override (such as intro_image), and copying the file to your template. You should then copy the folder structure of the element that you want to override that exists within the layouts folder within the Joomla! parent directory e.g. <tt>templates/YOUR_TEMPLATE/html/</tt>. You only want to copy the file(s) that you require to avoid site bloat, and to minimise the probability of causing an issue.</translate>

<translate>
An example for the intro_image would be originally found in:
<tt>JOOMLAROOT/layouts/joomla/content/intro_image.php</tt>


The copied file would be: <tt>templates/YOUR_TEMPLATE/html/layouts/joomla/content/intro_image.php</tt>


As a simple example let's add a responsive image class to the intro image. First of all, we open our copied JLayout file, which we just placed in <tt>templates/YOUR_TEMPLATE/html/layouts/joomla/content/intro_image.php</tt>.


Look for the following line


<syntaxhighlight lang="php"><div class="pull-<?php echo htmlspecialchars($imgfloat); ?> item-image"> </syntaxhighlight>


Let's add our responsive image class <tt>img-responsive</tt> to the existing classes.


<syntaxhighlight lang="php"><div class="pull-<?php echo htmlspecialchars($imgfloat); ?> item-image img-responsive"> </syntaxhighlight>


Okay, we have added our class. Let's save and close the file. Ensure it is uploaded to our website. Now if we refresh the page we will see the class <tt>img-responsive</tt> on our intro images. You have just used a JLayout, think of all the other great things you could do with JLayouts?
</translate>
==== Creating a new JLayout that only appears on some pages ====
<translate>
You can also create new JLayout files. They do not need to be based on existing elements. Simply add them into the <tt>YOUR_TEMPLATE/html/layouts/</tt> directory as above and Joomla! will be able to find them. Then you need to reference the new JLayout in your code. For simplicity, in this example, I have duplicated an existing element, and made my own version.


I will start by doing a standard '''HTML template override for the Blog layout''' (not a JLayout override). You can find out how to do this further up this page. Doing a template override will add a few files to my <tt>templates/YOUR_TEMPLATE/html</tt> folder. I will create a new JLayout which I '''only''' want to use on my blog view. If I simply edited the JLayout for intro_image it would effect all of my intro_images, but I only want to alter my Category Blog View intro_images.


The file I want to use is <tt>templates/YOUR_TEMPLATE/html/com_content/category/blog_item.php</tt>. Within that file I find the line <syntaxhighlight lang="php" inline><?php echo JLayoutHelper::render('joomla.content.intro_image', $this->item); ?></syntaxhighlight> which is calling a JLayout element. That particular code is for the intro_image element.


For the sake of simplicity I copied the file <tt>JOOMLAROOT/layouts/joomla/content/intro_image.php</tt>. I put it in <tt>templates/YOUR_TEMPLATE/html/layouts/joomla/content/</tt> and I renamed it <tt>intro_image_blog.php</tt>.</translate>

<translate>
Now I open my template override file <tt>templates/YOUR_TEMPLATE/html/com_content/category/blog_item.php</tt>. I find the reference to <syntaxhighlight lang="php" inline><?php echo JLayoutHelper::render('joomla.content.intro_image', $this->item); ?></syntaxhighlight>, I remove it, I reposition the JLayout above the title, and I use my own JLayout that I just created <tt>templates/YOUR_TEMPLATE/html/layouts/joomla/content/intro_image_blog.php</tt>.


Now my new JLayout is being used, and it has been positioned above the title. I can now make further amendments such as adding a responsive image class if need be and changes will only be reflected in the Category Blog View.
</translate>

== Further Reading ==
You can find further reading here [[J3.x:Sharing_layouts_across_views_or_extensions_with_JLayout|Sharing layouts across views or extensions with JLayout]]

<noinclude>
<translate>

[[Category:Joomla! 3.x]]
[[Category:Tutorials]]
</translate>
</noinclude>

Help4.x:Scheduled Tasks

2023-09-16T14:12:42Z

Cmb: Corrected Intervale to Interval.

<noinclude><languages /></noinclude>
<translate>

==Description== 


Scheduled Tasks are used to run routine site maintenance tasks as an alternative to server cron jobs. The tasks are defined in plugins in the task group. A number of task plugins are supplied and can be used as examples for creating other specialised tasks.

==How To Access== 


Starting from the Administrator menu:


* Select {{<tvar name=1>rarr</tvar>|System,Manage panel,Scheduled Tasks}}


The initial Scheduled Tasks list is empty so select the '''New''' button to get started. The screenshot shows the example tasks.

==Screenshot== 
</translate>
[[File:Help-4x-components-scheduler-manager-tasks-<translate>

en</translate>.png|800px]]
<translate>

==Column Headers== 


In the table containing Tasks the different columns are listed below. Click on the column heading to sort the list by that column's value.
</translate>
{{:Chunk4x:Help screen column header Checkbox/<translate>

en</translate>}}
{{:Chunk4x:Help screen column header Ordering/<translate>

en</translate>}}
{{:Chunk4x:Help screen column header Status/<translate>

en</translate>}}
{{:Chunk4x:Help screen column header Task Title/<translate>

en</translate>}}
{{:Chunk4x:Help screen column header Task Type/<translate>

en</translate>}}
{{:Chunk4x:Help screen column header Last Run Date/<translate>

en</translate>}}
{{:Chunk4x:Help screen column header Test Task/<translate>

en</translate>}}

*<translate> '''Task Priority'''. Shows the priority Low, Normal, or High. Higher priority tasks can potentially block lower priority tasks.</translate>
{{:Chunk4x:Help screen column header Id/<translate>

en</translate>}}

<translate>
==List Filters== 
</translate>
{{Chunk4x:Help_screen_filters_Search_Bar_Filter/<translate>

en</translate>|<translate> tasks</translate>}}
<translate>

===Filter Options=== 
</translate>
{{safesubst:Chunk4x:Help_screen_filter_bar_top_descriptor/<translate>

en</translate>}}
*<translate> '''Select Status'''. Select from Trashed / Disabled / Enabled / All.</translate>
*<translate> '''Task Type'''. Select from the list of available tasks.</translate>
*<translate> '''Hide Orphaned'''. Select from Hide Orphaned / Show Orphaned / Only Orphaned.</translate>
<translate>

===Pagination=== 
</translate>
{{:Chunk4x:Help_screen_filters_Pagination/<translate>

en</translate>|<translate> tasks</translate>}}
<translate>

==Toolbar== 
</translate>
{{safesubst:Chunk4x:Help_screen_toolbar_top_descriptor/<translate>

en</translate>}}
{{safesubst:Chunk4x:Help_screen_toolbar_icon_New/<translate>

en</translate>|<translate>

task</translate>}}
{{safesubst:Chunk4x:Help_screen_toolbar_icon_Actions/<translate>

en</translate>|<translate>

task</translate>}}
<ul>
{{safesubst:Chunk4x:Help_screen_toolbar_icon_Enable/<translate>

en</translate>|<translate>

task</translate>}}
{{safesubst:Chunk4x:Help_screen_toolbar_icon_Disable/<translate>

en</translate>|<translate>

task</translate>}}
{{safesubst:Chunk4x:Help_screen_toolbar_icon_Unlock/<translate>

en</translate>|<translate>

task</translate>}}
{{safesubst:Chunk4x:Help_screen_toolbar_icon_Trash/<translate>

en</translate>|<translate>

task</translate>}}
</ul>
{{safesubst:Chunk4x:Help_screen_toolbar_icon_Options/<translate>

en</translate>}}
{{safesubst:Chunk4x:Help_screen_toolbar_icon_Help/<translate>

en</translate>}}
<translate>

== Scheduled Tasks Options == 


Click the '''Options''' button from the Toolbar to configure scheduled tasks.
</translate>
*<translate> '''Configure Tasks'''</translate>
**<translate> '''Task Timeout'''. The default is <tvar name=1>300</tvar> seconds.</translate>
*<translate> '''Lazy Scheduler'''</translate>
**<translate> '''Enabled'''. Tasks are triggered by Site visitors.</translate>
**<translate> '''Disabled'''. Tasks are to be triggered by an external cron job.</translate>
**<translate> '''Request Interval'''. The default is <tvar name=1>300</tvar> seconds.</translate>
*<translate> '''Web Cron'''</translate>
**<translate> '''Web Cron'''. Disabled is the default. Enabled requires a hash to trigger the task. Before the first save there is a message that a key is required. After save there is a field containing a Webcron link URL to copy.</translate>
*<translate> '''Permissions''' The standard form to set access permissions.</translate>
<translate>

==Available Tasks== 


The following screenshot shows a list of available tasks. Some are demonstrations, some are useful.
</translate>

[[File:Help-4x-Scheduled-Tasks-Available-screen-<translate> en</translate>.png|800px|<translate> Scheduled Tasks Available</translate>]]

<translate>

Each task has its own task related parameters that should be self-explanatory. For example, the '''Site Offline''' task only makes sense if the {{<tvar name=1>rarr</tvar>|Edit Task,Basic Fields,Execution Rule}} is set to '''Manual Execution'''.


The other parameters are optional!
</translate>

<noinclude>{{Cathelp|4.0,4.1,4.2,4.3|Components Help Screens|Scheduled Tasks Manager Help Screens}}</noinclude>

Inserting, Updating and Removing data using JDatabase

2023-09-13T16:24:15Z

Cmb: Replaced deprecated 'source' tags with 'syntaxhighlight' tags. Corrected some URLs.

<noinclude><languages /></noinclude>
<noinclude>{{Joomla version|version=3.x}}{{Joomla version|version=2.5|status=eos}}</noinclude>
{{-}}
{{tip|<translate>
Note many examples online use <code>$db->query()</code> instead of <code>$db->execute()</code>. This was the old method in Joomla 1.5 and 2.5 and will throw a deprecated notice in Joomla 3.0+.</translate>|title=<translate>
Version Note</translate>}}

<translate>
This tutorial is split into two independent parts:</translate>
<translate>
* Inserting, updating and removing data from the database.</translate>
<translate>
* Selecting data from one or more tables and retrieving it in a variety of forms.</translate>

<translate>
This section examines inserting, updating and removing data from a database table. See also the [[S:MyLanguage/Selecting_data_using_JDatabase|other part]].</translate>

<translate>
== Introduction== 
</translate>
<translate>
Joomla provides a sophisticated database abstraction layer to simplify the usage for third party developers. New versions of the Joomla Platform API provide additional functionality which extends the database layer further and includes features such as connectors to a greater variety of database servers and the query chaining to improve readability of connection code and simplify SQL coding.</translate>

<translate>
Joomla can use different kinds of SQL database systems and run in a variety of environments with different table-prefixes. In addition to these functions, the class automatically creates the database connection. Besides instantiating the object you need just two lines of code to get a result from the database in a variety of formats. Using the Joomla database layer ensures a maximum of compatibility and flexibility for your extension.</translate>

<translate>
==The Query== 
</translate>
<translate>
Joomla's database querying has changed since the new Joomla Framework was introduced ''query chaining'' is now the recommended method for building database queries (although string queries are still supported).</translate>

<translate>
Query chaining refers to a method of connecting a number of methods, one after the other, with each method returning an object that can support the next method, improving readability and simplifying code.</translate>

<translate>
To obtain a new instance of the JDatabaseQuery class we use the JDatabaseDriver getQuery method:</translate>

<syntaxhighlight lang="PHP">
// Use one of the following depending on the file and version of Joomla
$db = $this->_db; // use in Table class, also works in Model classes, J4 onwards
$db = $this->getDatabase(); // only works in the Field, Model or Table classes, J4 onwards

$db = JFactory::getDbo(); //deprecated J3, removed in J4
$db = Factory::getDbo(); //deprecated J4 - requires use Joomla\CMS\Factory;
$db = $this->getDbo(); // only works in the model or table classes, deprecated J5, use $this->getDatabse();
$db = Factory::getContainer()->get('DatabaseDriver'); // Not well documented

$query = $db->getQuery(true);
</syntaxhighlight>

<translate>
The ''JDatabaseDriver::getQuery'' takes an optional argument, ''$new'', which can be true or false (the default being false).</translate>

<translate>
To query our data source we can call a number of JDatabaseQuery methods; these methods encapsulate the data source's query language (in most cases SQL), hiding query-specific syntax from the developer and increasing the portability of the developer's source code.</translate>

<translate>
Some of the more frequently used methods include: select, from, join, where and order. There are also methods such as insert, update and delete for modifying records in the data store. By chaining these and other method calls, you can create almost any query against your data store without compromising portability of your code.</translate>
<translate>

==Inserting a Record== 
</translate>
<translate>
===Using SQL=== 
</translate>

<translate>
The JDatabaseQuery class provides a number of methods for building insert queries, the most common being insert, columns, values.</translate>

<syntaxhighlight lang="php">
// Get a db connection.
$db = JFactory::getDbo(); //deprecated J3, removed in J4
$db = Factory::getDbo(); //deprecated J4 - requires use Joomla\CMS\Factory;
$db = $this->getDbo(); // only works in the model or table classes, deprecated J4
$db = Factory::getContainer()->get('DatabaseDriver'); //J4 onwards, outside of the Model or Table
$db = $this->_db; //only works in the model or table classes, J4 onwards

// Create a new query object.
$query = $db->getQuery(true);

// Insert columns.
$columns = array('user_id', 'profile_key', 'profile_value', 'ordering');

// Insert values.
$values = array(1001, $db->quote('custom.message'), $db->quote('Inserting a record using insert()'), 1);

// Prepare the insert query.
$query
->insert($db->quoteName('#__user_profiles'))
->columns($db->quoteName($columns))
->values(implode(',', $values));

// Set the query using our newly populated query object and execute it.
$db->setQuery($query);
$db->execute();
</syntaxhighlight>
<translate>

(Here the ''quoteName()'' function adds appropriate quotes around the table and column names to avoid conflicts with any database reserved word, now or in the future.)</translate>
<translate>

To get the ID of the row that you just inserted, you can use the ''insertid'' method, for example.</translate>
<syntaxhighlight lang="php">
// Get the row that was just inserted
$new_row_id = $db->insertid();
</syntaxhighlight>

<translate>
====How to Store Empty Value as NULL==== 
</translate>
<translate>

If your default value of a column is NULL, you should not add that column name in the array. Let the database system store NULL as the default value.
If the default value of a column is not NULL and it is allowed to store NULL values, you should specify that in the code. See how to do it in the following example.
</translate>

<syntaxhighlight lang="php">
// Get a db connection.
$db = JFactory::getDbo();

// Create a new query object.
$query = $db->getQuery(true);

/** First Case [NULL as default value] **/
// The column 'profile_value' has NULL as default value. So, we will not add it to the array. The database engine will store NULL as value for column 'profile_value'.
// $columns = array('user_id', 'profile_key', 'profile_value', 'ordering');
$columns = array('user_id', 'profile_key', 'ordering');

// Insert values.
$values = array(1001, $db->quote('custom.message'), 1);

/** Second Case [string as default value and you can also store NULL value] **/
// The column 'profile_value' has empty string '' as default value but we can also store NULL value. So, we have to add the column name and NULL value to $columns and $values.
$columns = array('user_id', 'profile_key', 'profile_value', 'ordering');

// Insert values.
$values = array(1001, $db->quote('custom.message'), $db->quote('NULL'), 1);
</syntaxhighlight>

<translate>
===Using an Object=== 
</translate>
<translate>
The ''JDatabaseDriver'' class also provides a convenient method for saving an object directly to the database allowing us to add a record to a table without writing a single line of SQL.</translate>

<syntaxhighlight lang="php">
// Create and populate an object.
$profile = new stdClass();
$profile->user_id = 1001;
$profile->profile_key='custom.message';
$profile->profile_value='Inserting a record using insertObject()';
$profile->ordering=1;

// Insert the object into the user profile table.
$result = JFactory::getDbo()->insertObject('#__user_profiles', $profile);
</syntaxhighlight>

<translate>
Notice here that we do not need to escape the table name; the insertObject method does this for us.</translate>

<translate>
The insertObject method will throw a error if there is a problem inserting the record into the database table.</translate>

<translate>
If you are providing a unique primary key value (as in the example above), it is highly recommended that you select from the table by that column value before attempting an insert.</translate>

<translate>

If you are simply inserting the next row in your table (i.e. the database generates a primary key value), you can specify the primary key column-name as the third parameter of the insertObject() method and the method will update the object with the newly generated primary key value.</translate>

<translate>

For example, given the following statement:</translate>

<syntaxhighlight lang=php>

$result = $dbconnect->insertObject('#__my_table', $object, 'primary_key');

</syntaxhighlight>

<translate>

after execution, $object->primary_key will be updated with the newly inserted row's primary key value.</translate>

<translate>

'''HINT''' Set $object->primary_key to null or 0 (zero) before inserting.</translate>

<translate>
====How to Store Empty Value as NULL When Inserting an Object==== 
</translate>
<translate>

If your default value of a column is NULL, you should not add that column name to the object. Let the database system store NULL as the default value.
If the default value of a column is not NULL and it is allowed to store NULL values, you should specify that in the code. See how to do it in the following example.
</translate>

<syntaxhighlight lang="php">
// Create and populate an object.
$profile = new stdClass();
$profile->user_id = 1001;
$profile->profile_key='custom.message';
$profile->ordering=1;

/** First Case [NULL as default value] **/
// The column 'profile_value' has NULL as default value. So, we will not add it to the object. The database engine will store NULL as value for column 'profile_value'.
// $profile->profile_value='Inserting a record using insertObject()';

/** Second Case [string as default value and you can also store NULL value] **/
// The column 'profile_value' has empty string '' as default value but we can also store NULL value. So, we have to add the column name and NULL value as its value.
$profile->profile_value = $db->quote('NULL');

// Insert the object into the user profile table.
$result = JFactory::getDbo()->insertObject('#__user_profiles', $profile);
</syntaxhighlight>

<translate>
==Updating a Record== 
</translate>
<translate>
===Using SQL=== 
</translate>
<translate>
The [https://api.joomla.org/cms-3/classes/JDatabaseQuery.html JDatabaseQuery] class also provides methods for building update queries, in particular [https://api.joomla.org/cms-3/classes/JDatabaseQuery.html#method_update update] and [https://api.joomla.org/cms-3/classes/JDatabaseQuery.html#method_set set]. We also reuse another method which we used when creating select statements, the ''where'' method.</translate>

<syntaxhighlight lang="php">
$db = JFactory::getDbo();

$query = $db->getQuery(true);

// Fields to update.
$fields = array(
$db->quoteName('profile_value') . ' = ' . $db->quote('Updating custom message for user 1001.'),
$db->quoteName('ordering') . ' = 2',

// If you would like to store NULL value, you should specify that.
$db->quoteName('avatar') . ' = NULL',
);

// Conditions for which records should be updated.
$conditions = array(
$db->quoteName('user_id') . ' = 42',
$db->quoteName('profile_key') . ' = ' . $db->quote('custom.message')
);

$query->update($db->quoteName('#__user_profiles'))->set($fields)->where($conditions);

$db->setQuery($query);

$result = $db->execute();
</syntaxhighlight>

<translate>
=== Using an Object === 
</translate>
<translate>
Like ''insertObject'', the JDatabaseDriver class provides a convenient method for updating an object.</translate>

<translate>
Below we will update our custom table with new values using an existing id primary key:</translate>

<syntaxhighlight lang="php">
$updateNulls = true;

// Create an object for the record we are going to update.
$object = new stdClass();

// Must be a valid primary key value.
$object->id = 1;
$object->title = 'My Custom Record';
$object->description = 'A custom record being updated in the database.';

// If you would like to store NULL value, you should specify that.
$object->short_description = null;

// Update their details in the users table using id as the primary key.
// You should provide forth parameter with value TRUE, if you would like to store the NULL values.
$result = JFactory::getDbo()->updateObject('#__custom_table', $object, 'id', $updateNulls);
</syntaxhighlight>

<translate>
Just like insertObject, updateObject takes care of escaping table names for us.</translate>

<translate>
The updateObject method will throw a error if there is a problem updating the record into the database table.</translate>

<translate>
We need to ensure that the record already exists before attempting to update it, so we would probably add some kind of record check before executing the updateObject method.</translate>

<translate>
==Deleting a Record== 
</translate>
<translate>
Finally, there is also a delete method to remove records from the database.</translate>

<syntaxhighlight lang="php">
$db = JFactory::getDbo();

$query = $db->getQuery(true);

// delete all custom keys for user 1001.
$conditions = array(
$db->quoteName('user_id') . ' = 1001',
$db->quoteName('profile_key') . ' = ' . $db->quote('custom.%')
);

$query->delete($db->quoteName('#__user_profiles'));
$query->where($conditions);

$db->setQuery($query);

$result = $db->execute();
</syntaxhighlight>

<translate>
== Sample Module Code == </translate>
<translate>

Below is the code for a simple Joomla module which you can install and run to demonstrate use of the JDatabase functionality for updating records in the database and which you can adapt to experiment with some of the concepts described above. If you are unsure about development and installing a Joomla module then following the tutorial at [[S:MyLanguage/J3.x:Creating a simple module/Introduction| Creating a simple module]] will help.</translate>

<translate>

'''Important note: In any Joomla extensions which you develop that you should avoid accessing the core Joomla tables directly like this and should instead use the Joomla APIs if at all possible. The database structures may change without warning.'''</translate>

<translate>

In a folder ''mod_db_update'' create these two files:</translate>

''mod_db_update.xml''
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="3.1" client="site" method="upgrade">
<name>Database update demo</name>
<version>1.0.1</version>
<description>Code demonstrating use of Joomla Database class to perform SQL UPDATE statements</description>
<files>
<filename module="mod_db_update">mod_db_update.php</filename>
</files>
</extension>
</syntaxhighlight>

''mod_db_update.php''
<syntaxhighlight lang="php">
<?php
defined('_JEXEC') or die('Restricted Access');

use Joomla\CMS\Factory;

$db = Factory::getDbo();

$me = Factory::getUser();

if ($me->id == 0)
{
echo "Not logged on!";
}
else
{
$email = $me->email;
// change the case of the email address
$email_uppercase = strtoupper($email);
if ($email == $email_uppercase)
{
$new_email = strtolower($email);
}
else
{
$new_email = $email_uppercase;
}

$query = $db->getQuery(true);

$fields = array($db->quoteName('email') . " = '{$new_email}'");

$conditions = array($db->quoteName('id') . ' = ' . $me->id);

$query->update($db->quoteName('#__users'))->set($fields)->where($conditions);

echo $db->replacePrefix((string) $query);

$db->setQuery($query);

if ($result = $db->execute())
{
echo "Email case successfully changed!";
}
}
</syntaxhighlight>
<translate>

The code above updates the email address field in the ''users'' record of the currently logged-on user, toggling between upper case and lower case in successive reloads of the web page. </translate>
<translate>

The method ''Factory::getUser()'' returns the ''user'' object of the currently logged-on user, or if not logged on, then a blank ''user'' object, whose ''id'' field is set to zero. </translate>
<translate>

The ''$db->replacePrefix((string) $query)'' expression returns the actual SQL statement and outputting this can be useful in debugging. </translate>

<translate>

Zip up the ''mod_db_update'' directory to create ''mod_db_update.zip''.</translate>

<translate>

Within your Joomla administrator go to Install Extensions and via the Upload Package File tab. Upload this zip file to install this sample log module.</translate>

<translate>

Make this module visible by editing it (click on it within the Modules page) then:
# Make its status ''Published''
# Select a position on the page for it to be shown
# Specify the pages it should appear on in the Menu Assignment tab</translate>

<translate>

When you visit a site web page you should see the module in your selected position and it should output the SQL UPDATE statement and affirm that it has updated the record successfully. To confirm that it has updated the record correctly, go into PHPMyAdmin and view the ''users'' table within the Joomla database. The updates aren't visible via the admin Users functionality on the Backend; Joomla displays in lower case all the email addresses in the records.</translate>

<noinclude>
<translate>

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

J4.x:Task Scheduler

2023-09-13T15:59:48Z

Cmb: Replaced deprecated 'source' tags with 'syntaxhighlight' tags. Other markup changes.

== Limit Task to Command-line Interface Only ==
To implement a task, which is executed via the command-line interface (CLI) only, add this code to the task XML:
<syntaxhighlight lang="xml">
<fieldset name="aside">
<field name="cli_exclusive" type="hidden" default="1" />
</fieldset>
</syntaxhighlight>

The fieldset must be a direct child of the form
<syntaxhighlight lang="xml">
<form>
<fieldset name="aside">
<field name="cli_exclusive" type="hidden" default="1" />
</fieldset>
...
</syntaxhighlight>
<noinclude>
[[Category:Joomla! 4.x{{#translation:}}]]
[[Category:Tutorials{{#translation:}}]]
</noinclude>

Joomla 3.x to 4.x Step by Step Migration

2023-08-17T00:40:40Z

Cmb: Migration duration clarified.

<noinclude><languages /></noinclude>
{{warning|title=<translate>

Warning!</translate>|<translate>

This guide assumes you are starting on Joomla 3.10.x. If you are on a earlier version make sure you upgrade to Joomla 3.10 first before moving to Joomla 4.


There is no rush. Make sure all your extensions are ready for Joomla 4.x. Joomla 3.10.x will be supported until 16 August 2023.</translate>}}

<translate>

The following are step-by-step instructions to migrate your 3.10.x site to Joomla! 4.x. While there are different scenarios, this will give you the basic procedure to follow. Complex migrations will likely be a result of installed third-party extensions. You are encouraged to contact the developers of third-party extensions installed on your Joomla site for their suggested migration path.
</translate>

<translate>
== Intro == 
The migration from Joomla! 3.10.x to 4.x is considered a mini-migration. This is because the Joomla core extensions will upgrade with a “one-click” upgrade via the Joomla! Update component in the Backend (Administrator) of Joomla. Many third-party extensions are a one-click upgrade too. Some are not. Look at each one and determine what path the extension needs to follow to get from 3.10 to 4.x. If you haven't already, read the [[S:MyLanguage/Migration Step by Step Self Assessment|Self Assessment]] and [[S:MyLanguage/Planning for Mini-Migration - Joomla 3.10.x to 4.x|Planning for 3.10 to 4.x Migration]] prior to following the steps below.</translate>
<translate>

</br>Joomla! Core Extensions are:
* Categories
* Articles
* Menus
* Modules (core modules - not third-party)
* Action Logs
* Banners
* Fields
* Content History
* Contacts
* Messaging
* Newsfeeds
* Redirect
* Search (decoupled in 4.x. Existing 3.x sites will still migrate it. However we recommend using Smart Search going forward. See Notes under Assess Each Extension)
* Smart Search
* Tags
* Weblinks (decoupled but your site may be using it and it will migrate. See Notes under Assess Each Extension.)
</translate>

<translate>
== Step by Step == 
=== Set Up a Development Location ===
</translate>
<translate>

# Make sure you are running the latest Joomla 3.10.x version before proceeding.
# Take a backup of your live 3.10.x site. You can use a suggested tool (see the ''Suggested Tools'' at the bottom of page) or you can do this manually.
#*[[S:MyLanguage/Backup_Basics_for_a_Joomla!_Web_Site|Backup Basics for a Joomla! Web Site]]
#*[[S:MyLanguage/What_are_the_best_practices_for_site_backups%3F|What are the best practices for site backups?]]
# Make sure your environment meets the [https://downloads.joomla.org/technical-requirements technical requirements for Joomla 4].
# Create a new database and new user to restore your 3.10.x site to.
# Create a testing site or build area to work in and restore the backup copy of your 3.10.x site in one of the following places:
#* A subdomain.
#* A subdirectory.
#* A local device. Joomla has a detailed tutorial on installing [https://sourceforge.net/projects/xampp/ XAMPP] at [[XAMPP]]. However [https://www.wampserver.com/en/ WAMP], [https://www.mamp.info/en/windows/ MAMP], [https://sourceforge.net/projects/lampas/ LAMP] are all suitable alternatives.
#* A new hosting account on a temporary domain in the root. (If you would like to change hosts in the process of migration.)
#** Restoring a site on a local device. See [[S:MyLanguage/Installing Joomla locally|Installing Joomla locally]] and [[S:MyLanguage/Setting up your workstation for Joomla development|Setting up your workstation for Joomla development]].
#** Restoring a site with a tool listed at the bottom of the page. (Read the developer documentation.)
# In your test location, update your Joomla! 3.10.x instance to the latest maintenance release.
# Make sure you have the latest database schema updated to the latest version 3.10.x version by going to {{rarr|Extension Manager,Database}} tab. If your schema is not up to date as in the following image, click the '''Fix''' button:</translate>{{-}}[[File:J310-admin-extension-database-fix-<translate>

en</translate>.png|border|800px]]
<translate>

# Empty trash: Do you have any articles in the trash? Delete them (and any associated media if not in use elsewhere on the site). Articles (categories and menu items too) left in the trash can cause migration issues.
# Test.
# Backup again.
</translate>

<translate>
=== Assess Each Extension === 
</translate>
<translate>

In your [[S:MyLanguage/Planning_for_Mini-Migration_-_Joomla_3.10.x_to_4.x|planning]], you determined that third-party extensions were staying or going and how they migrate. For this portion of the Step by Step, you’ll be using two different sections of the site extensively; The Pre-Update Check in {{rarr|Components,Joomla! Update}} and {{rarr|Extensions,Manage,Manage}}. You are going to be looking at every single extension installed on your site. You will be determining if they need to be updated to the latest version or uninstalled. More details in [[Special:MyLanguage/:Pre-Update_Check|Pre-Update Check]].</translate>
<translate>

# Using the '''Pre-Update Check''': in order to use the Pre-Update Check, you will need to set the Joomla! Update component to Joomla 4. To do this follow:
# Go to {{rarr|Components,Joomla Update}}. (It should say no updates found. If it doesn’t, update Joomla to the latest version (must be 3.10.x) and test. Then do another backup.) Click on the Options button at the top right corner.
# Select ''Joomla Next'' from the drop-down for Update Channel.</translate>{{-}}[[File:Migration_J3toJ4_update_channel-<translate> en</translate>.png|border|800px]]{{-}}
<translate>
# Click Save & Close
# You will then see your Installed Joomla Version, the latest Joomla! version and the URL for the update package. Joomla will show you the requirements again for Joomla 4. If it flags that you have either an incompatible system or extensions it will tell you here. Take a moment to review this page.</translate>{{-}}[[File:J310-admin-update_to_4-pre_update_check-<translate> en</translate>.png|border|800px]]<translate>

{{amboxNew|image=notice|style=notice|title={{{title|Important Notice}}}|text='''Do NOT update to Joomla! 4 right now. This is only to prepare your third-party extensions and get the site compatible with Joomla! 4.'''}}
# Look at the Pre-Update Check and the Extension Pre-Update Check in the Pre-Update Check tab of the Joomla Update component. If any extension that isn’t in your planning is listed here, add it to your list of extensions to investigate.
# If you migrated from Joomla! 2.5 to 3.x in the past, there may be some leftover extensions that need to be cleaned up. The following are older 2.5 or 3.x extensions that need to be uninstalled before updating to Joomla 4:
#;* plg_content_geshi
#;* PKG_JOOMLA
#;* Bluestork Administrator Template
#;* Beez_20
#;* Beez5
#;* Atomic</translate>
<translate> ## When it comes to templates, uninstall all core Frontend or Backend templates except Protostar and Beez3 (site templates) and Isis or Hathor (Administrator templates). '''Note''' Protostar is '''not''' compatible with Joomla 4. Upon migration it will disappear. You'll need to have one template selected as "default" and you can use Protostar or Beez3. Protostar will disappear upon migration to Joomla 4.x.</translate>
<translate> ## If you come across other files that need to be uninstalled, please add them to this page. This is a wiki so anyone can add to the page. Thank you in advance for your service.</translate>
<translate> # You will notice the tags for whether an extension is compatible or not. These tags generally tell a true story if they say No or Yes. If they say “Missing Compatibility Tag” it means that the extension developer didn’t use a tag in their extension so we don’t know if it is or isn’t compatible with Joomla 4. Talk to the developer to verify.</translate>
<translate> # '''Update Extensions''': update any extensions that you will keep in your website. In Joomla! 3.10.x you can go to {{rarr|Extension Manager,Update tab}} and click '''Find Updates''' that will add a tooltip in the Version column, under the Manage tab, giving some compatibility information from the Backend. This functionality only supports extensions that update via the Extension Manager Update tab. If you have extensions installed that do not use the Joomla extension update they need to be assessed manually as detailed below. The same goes for those extensions that have a tooltip. You will still need to check the type of package and migration path with the extension developer to verify how to upgrade/migrate.</translate>
<translate>
# Investigate and Uninstall Extensions Extensions: go to {{rarr|Extension Manager,Manage}}
# Click the Button ''Search Tools'' to show the filter options
# Select Package from the ''Select Type'' drop-down.</translate>{{-}}[[File:J310-admin-extension-manage-package-<translate>

en</translate>.png|800px]]{{-}}{{note|<translate>

Selecting Package first is recommended because if there is something you need to uninstall in a package, it will automatically uninstall the associated Modules, Plugins, or anything else in the package at one time.</translate>}}
<translate>

# Uninstall any Packages that are no longer needed or will not be migrating to Joomla 4.
# Repeat this process of going through the Manage tab for all Types in the drop-down: Component, File, Language, Library, Module, Plugin and Template. If the Author states Joomla! Project, then leave those extensions alone. For all others, make sure that you uninstall those not in use or not compatible with Joomla! 4.x.</translate>{{-}}{{note|<translate>

'''NOTE!''' You will not be able to uninstall any template that is set as default. Select a Core supported template such as Beez3 or Protostar and then uninstall the template if you need to do so. <br />''Another reminder:'' '''Protostar is not compatible with Joomla 4.x'''. Upon migration it will disappear. Selecting it as default simply gets you to Joomla 4.x.</translate>|type=serious}}
<translate>

# Make a note of any versions of Packages and Components currently running that you will be keeping on your site. You can copy/paste them into a document for reference.</translate>
<translate> # For any extensions you are keeping but don't use the Extension Manager to one-click update ({{rarr|Extensions,Manage,Update}}) update all extensions to the latest versions.</translate>
<translate> # Before and as you update, note if the extensions have both 3.10.x & 4.x versions in the same package. If so, they will be fine to "one-click update." If not, and 3.10 and 4.x have different packages, look at them case by case. They will normally fall into one of the following scenarios:</translate>
<translate> #* The extension has separate packages but upon upgrading to 4.x, they automatically detect this and still work. Make sure the developer confirms this.</translate>
<translate> #* The extension has separate packages that need to be uninstalled in 3.10.x and then installed with the Joomla 4.x version once the site is migrated. An example of this might be a content plugin. It is simple to uninstall it in 3.10.x and then install it again in 4.x.</translate>
<translate> #* See [[S:MyLanguage/Template_Considerations_During_Migration|Template Considerations]] for more specific information on templates and [[S:MyLanguage/J3.x:Converting_A_Previous_Joomla!_Version_Template|Converting a previous Joomla! Version template]]</translate>

<translate>
==== Notes on Search (com_search) ==== 
Search (com_search) will be decoupled in Joomla 4.x. Search (com_search) will migrate to Joomla 4. After migration, you'll need to update it to the Joomla 4.x version via com_installer. It will continue to be maintained, but more the same way a third-party extension is by receiving updates via com_installer. It is recommended to use Smart Search (com_finder) going forward. Search will still be available at https://extensions.joomla.org/category/official-extensions/.</translate>

<translate>
==== Notes on Weblinks ==== 
Weblinks was decoupled back in Joomla 3.4. If it was in use on a 2.5 site, the migration process would note this and migrate the Weblinks component and data. For the migration from 3.10.x to 4.x, it will be the same. It is still available and maintained on the JED at [https://extensions.joomla.org/category/official-extensions/ Official Extensions].</translate>

<translate>
==== Notes on Legacy Routing ====  </translate>
<translate> Legacy routing will not be available in Joomla 4.x. Only Modern will be available. When you do the migration, if you are using Legacy routing, the system will automatically change them to Modern routing. You will want to run a broken link checker on your site after migrating to Joomla 4.x and ''before you go live''.</translate>

<translate>
=== Going to Joomla! 4.x === 
Once you have either updated or uninstalled your third-party extensions so that only those compatible with Joomla! 4 remain in your installation, continue with the following steps:
</translate>
<translate>

# Go to {{rarr|System,Global Configuration,Server tab}} and turn Error Reporting from System Default to Maximum. Make sure to Save & Close.</translate>{{-}} [[File:J310-system-global-config-server-tab-<translate>

en</translate>.png|border|500px]]
<translate>

# Take another backup.
# Go to {{rarr|Components,Joomla Update}}. (It should say no updates found. If it doesn’t, update Joomla to the latest version and test. Then do another backup.) Click on the Options button at the top right corner.
# Select ''Joomla Next'' from the drop-down for Update Channel.</translate>{{-}}[[File:J310-component-joomla-update-select-support-<translate>

en</translate>.png|border|500px]]
<translate>

# Click Save & Close.
# You will then see your Installed Joomla Version, the Latest Joomla! version and the URL for the update package. Joomla will show you the requirements again for Joomla 4. If it flags that you have either an incompatible system or extensions it will tell you here. Take a moment to review this page.</translate>{{-}}[[File:J310-to-j4-dev-update-found-<translate>

en</translate>.png|border|800px]]
<translate>

# If the update is not showing up, go to {{rarr|Extensions,Update}} and select Clear Cache from the toolbar. Now the update to Joomla! 4 should show up.</translate>
<translate> # Cross your fingers, and make sure you have that backup available in case.</translate>
<translate> # Click the Install the Update button.</translate>
<translate> # Make tea whilst the status bar loads to fully green. The amount of time this takes is dependent on your site, internet connection and server speed. The process can take several minutes. There are over 12,000 files comprising 75 megabytes to be extracted. When the update is finished, you might be logged out of the Administrator. Sign in again, if necessary</translate>
<translate> # If all goes well, you will get to a totally new look to the Backend panel.</translate>{{-}}[[File:j4-administrator-overview-<translate>

en</translate>.png|border|800px]]
<translate> # Go to {{rarr|System,Maintenance,Database}} and click ''Fix'' if any errors show.</translate>
<translate> # In {{rarr|System,Install,Discover}} see if there are any extensions to install. (There shouldn't be any!)</translate>
<translate> # Go to the Frontend of your site and see if it shows up even if it’s not the right template. If so, continue. If not, see [[S:MyLanguage/Joomla 3.10 to 4.x Common Migration Errors|common errors during migration]].</translate>
<translate> # Take a backup.</translate>
<translate> # Install your new template or other extensions if you have them to install. Back up often.</translate>
<translate> # Configure them. Back up often.</translate>
<translate> # Run a broken link checker and fix any broken links.</translate>
<translate> # Test everything. Back up often.</translate>
<translate>
# If everything works as expected, turn Error Reporting back to System Default ({{rarr|System,Global Configuration,Server tab}}). Make sure to Save & Close.
</translate>
# Be sure to read the post-installation messages.
<translate>
=== Going Live with Your Joomla! 4.x Site === 
# When you’re ready to go live, back up your 3.10 site for the last time. Restore it in a subdirectory or subdomain if you would like to.
# Back up your Joomla! 4.x site and move or restore your Joomla! 4.x site to the root (or change nameservers if you were building on a temporary domain at a new hosting account root).
# Test again.
# '''If''' you have made security changes to ''.htaccess'' file in the past, you may need to change a line (or lines) in it to update to Joomla 4. Please go to [https://docs.joomla.org/Htaccess_changes_after_joomla4.0.4 Htaccess changes after joomla4.0.4] to determine if you need to change your file.
# Remove the Joomla! 3.10 site from the server within a couple of days unless you have edited your ''robots.txt'' file to block the search engine spiders and disabled the Frontend of the site.
# Remove all development sites you have been working with or keep them up-to-date if they are running a current version in order to ward off hack attempts on your server. </translate>

<translate>

If you had data change on the 3.10 site while you were migrating to 4.x, you will want to get that data moved over to the 4.x site before going live. You can do this manually (make sure you keep the same user IDs - go in order) or by using a [https://extensions.joomla.org/category/migration-a-conversion/data-import-a-export%20transfer%20tool/third-party%20extension/ third party extension].
</translate>

<translate>
== Suggested Tools == </translate>
<translate>
* [http://extensions.joomla.org/extensions/access-a-security/site-security/backup/1606 Akeeba Backup] is popular for backup and restore. See more [https://extensions.joomla.org/tags/backup/ backup tools].
</translate>
<translate>
==Related information==  </translate>
[[Special:MyLanguage/:Pre-Update_Check|<translate> Pre-Update_Check</translate>]]
<noinclude>
<translate>

[[Category:Migration{{#translation:}}]]
[[Category:Tutorials{{#translation:}}]]
[[Category:Joomla! 4.x{{#translation:}}]]
</translate></noinclude>

Joomla 3.x to 4.x Step by Step Migration

2023-08-13T20:59:34Z

Cmb: Corrected a command sequence.

<noinclude><languages /></noinclude>
{{warning|title=<translate>

Warning!</translate>|<translate>

This guide assumes you are starting on Joomla 3.10.x. If you are on a earlier version make sure you upgrade to Joomla 3.10 first before moving to Joomla 4.


There is no rush. Make sure all your extensions are ready for Joomla 4.x. Joomla 3.10.x will be supported until 16 August 2023.</translate>}}

<translate>

The following are step-by-step instructions to migrate your 3.10.x site to Joomla! 4.x. While there are different scenarios, this will give you the basic procedure to follow. Complex migrations will likely be a result of installed third-party extensions. You are encouraged to contact the developers of third-party extensions installed on your Joomla site for their suggested migration path.
</translate>

<translate>
== Intro == 
The migration from Joomla! 3.10.x to 4.x is considered a mini-migration. This is because the Joomla core extensions will upgrade with a “one-click” upgrade via the Joomla! Update component in the Backend (Administrator) of Joomla. Many third-party extensions are a one-click upgrade too. Some are not. Look at each one and determine what path the extension needs to follow to get from 3.10 to 4.x. If you haven't already, read the [[S:MyLanguage/Migration Step by Step Self Assessment|Self Assessment]] and [[S:MyLanguage/Planning for Mini-Migration - Joomla 3.10.x to 4.x|Planning for 3.10 to 4.x Migration]] prior to following the steps below.</translate>
<translate>

</br>Joomla! Core Extensions are:
* Categories
* Articles
* Menus
* Modules (core modules - not third-party)
* Action Logs
* Banners
* Fields
* Content History
* Contacts
* Messaging
* Newsfeeds
* Redirect
* Search (decoupled in 4.x. Existing 3.x sites will still migrate it. However we recommend using Smart Search going forward. See Notes under Assess Each Extension)
* Smart Search
* Tags
* Weblinks (decoupled but your site may be using it and it will migrate. See Notes under Assess Each Extension.)
</translate>

<translate>
== Step by Step == 
=== Set Up a Development Location ===
</translate>
<translate>

# Make sure you are running the latest Joomla 3.10.x version before proceeding.
# Take a backup of your live 3.10.x site. You can use a suggested tool (see the ''Suggested Tools'' at the bottom of page) or you can do this manually.
#*[[S:MyLanguage/Backup_Basics_for_a_Joomla!_Web_Site|Backup Basics for a Joomla! Web Site]]
#*[[S:MyLanguage/What_are_the_best_practices_for_site_backups%3F|What are the best practices for site backups?]]
# Make sure your environment meets the [https://downloads.joomla.org/technical-requirements technical requirements for Joomla 4].
# Create a new database and new user to restore your 3.10.x site to.
# Create a testing site or build area to work in and restore the backup copy of your 3.10.x site in one of the following places:
#* A subdomain.
#* A subdirectory.
#* A local device. Joomla has a detailed tutorial on installing [https://sourceforge.net/projects/xampp/ XAMPP] at [[XAMPP]]. However [https://www.wampserver.com/en/ WAMP], [https://www.mamp.info/en/windows/ MAMP], [https://sourceforge.net/projects/lampas/ LAMP] are all suitable alternatives.
#* A new hosting account on a temporary domain in the root. (If you would like to change hosts in the process of migration.)
#** Restoring a site on a local device. See [[S:MyLanguage/Installing Joomla locally|Installing Joomla locally]] and [[S:MyLanguage/Setting up your workstation for Joomla development|Setting up your workstation for Joomla development]].
#** Restoring a site with a tool listed at the bottom of the page. (Read the developer documentation.)
# In your test location, update your Joomla! 3.10.x instance to the latest maintenance release.
# Make sure you have the latest database schema updated to the latest version 3.10.x version by going to {{rarr|Extension Manager,Database}} tab. If your schema is not up to date as in the following image, click the '''Fix''' button:</translate>{{-}}[[File:J310-admin-extension-database-fix-<translate>

en</translate>.png|border|800px]]
<translate>

# Empty trash: Do you have any articles in the trash? Delete them (and any associated media if not in use elsewhere on the site). Articles (categories and menu items too) left in the trash can cause migration issues.
# Test.
# Backup again.
</translate>

<translate>
=== Assess Each Extension === 
</translate>
<translate>

In your [[S:MyLanguage/Planning_for_Mini-Migration_-_Joomla_3.10.x_to_4.x|planning]], you determined that third-party extensions were staying or going and how they migrate. For this portion of the Step by Step, you’ll be using two different sections of the site extensively; The Pre-Update Check in {{rarr|Components,Joomla! Update}} and {{rarr|Extensions,Manage,Manage}}. You are going to be looking at every single extension installed on your site. You will be determining if they need to be updated to the latest version or uninstalled. More details in [[Special:MyLanguage/:Pre-Update_Check|Pre-Update Check]].</translate>
<translate>

# Using the '''Pre-Update Check''': in order to use the Pre-Update Check, you will need to set the Joomla! Update component to Joomla 4. To do this follow:
# Go to {{rarr|Components,Joomla Update}}. (It should say no updates found. If it doesn’t, update Joomla to the latest version (must be 3.10.x) and test. Then do another backup.) Click on the Options button at the top right corner.
# Select ''Joomla Next'' from the drop-down for Update Channel.</translate>{{-}}[[File:Migration_J3toJ4_update_channel-<translate> en</translate>.png|border|800px]]{{-}}
<translate>
# Click Save & Close
# You will then see your Installed Joomla Version, the latest Joomla! version and the URL for the update package. Joomla will show you the requirements again for Joomla 4. If it flags that you have either an incompatible system or extensions it will tell you here. Take a moment to review this page.</translate>{{-}}[[File:J310-admin-update_to_4-pre_update_check-<translate> en</translate>.png|border|800px]]<translate>

{{amboxNew|image=notice|style=notice|title={{{title|Important Notice}}}|text='''Do NOT update to Joomla! 4 right now. This is only to prepare your third-party extensions and get the site compatible with Joomla! 4.'''}}
# Look at the Pre-Update Check and the Extension Pre-Update Check in the Pre-Update Check tab of the Joomla Update component. If any extension that isn’t in your planning is listed here, add it to your list of extensions to investigate.
# If you migrated from Joomla! 2.5 to 3.x in the past, there may be some leftover extensions that need to be cleaned up. The following are older 2.5 or 3.x extensions that need to be uninstalled before updating to Joomla 4:
#;* plg_content_geshi
#;* PKG_JOOMLA
#;* Bluestork Administrator Template
#;* Beez_20
#;* Beez5
#;* Atomic</translate>
<translate> ## When it comes to templates, uninstall all core Frontend or Backend templates except Protostar and Beez3 (site templates) and Isis or Hathor (Administrator templates). '''Note''' Protostar is '''not''' compatible with Joomla 4. Upon migration it will disappear. You'll need to have one template selected as "default" and you can use Protostar or Beez3. Protostar will disappear upon migration to Joomla 4.x.</translate>
<translate> ## If you come across other files that need to be uninstalled, please add them to this page. This is a wiki so anyone can add to the page. Thank you in advance for your service.</translate>
<translate> # You will notice the tags for whether an extension is compatible or not. These tags generally tell a true story if they say No or Yes. If they say “Missing Compatibility Tag” it means that the extension developer didn’t use a tag in their extension so we don’t know if it is or isn’t compatible with Joomla 4. Talk to the developer to verify.</translate>
<translate> # '''Update Extensions''': update any extensions that you will keep in your website. In Joomla! 3.10.x you can go to {{rarr|Extension Manager,Update tab}} and click '''Find Updates''' that will add a tooltip in the Version column, under the Manage tab, giving some compatibility information from the Backend. This functionality only supports extensions that update via the Extension Manager Update tab. If you have extensions installed that do not use the Joomla extension update they need to be assessed manually as detailed below. The same goes for those extensions that have a tooltip. You will still need to check the type of package and migration path with the extension developer to verify how to upgrade/migrate.</translate>
<translate>
# Investigate and Uninstall Extensions Extensions: go to {{rarr|Extension Manager,Manage}}
# Click the Button ''Search Tools'' to show the filter options
# Select Package from the ''Select Type'' drop-down.</translate>{{-}}[[File:J310-admin-extension-manage-package-<translate>

en</translate>.png|800px]]{{-}}{{note|<translate>

Selecting Package first is recommended because if there is something you need to uninstall in a package, it will automatically uninstall the associated Modules, Plugins, or anything else in the package at one time.</translate>}}
<translate>

# Uninstall any Packages that are no longer needed or will not be migrating to Joomla 4.
# Repeat this process of going through the Manage tab for all Types in the drop-down: Component, File, Language, Library, Module, Plugin and Template. If the Author states Joomla! Project, then leave those extensions alone. For all others, make sure that you uninstall those not in use or not compatible with Joomla! 4.x.</translate>{{-}}{{note|<translate>

'''NOTE!''' You will not be able to uninstall any template that is set as default. Select a Core supported template such as Beez3 or Protostar and then uninstall the template if you need to do so. <br />''Another reminder:'' '''Protostar is not compatible with Joomla 4.x'''. Upon migration it will disappear. Selecting it as default simply gets you to Joomla 4.x.</translate>|type=serious}}
<translate>

# Make a note of any versions of Packages and Components currently running that you will be keeping on your site. You can copy/paste them into a document for reference.</translate>
<translate> # For any extensions you are keeping but don't use the Extension Manager to one-click update ({{rarr|Extensions,Manage,Update}}) update all extensions to the latest versions.</translate>
<translate> # Before and as you update, note if the extensions have both 3.10.x & 4.x versions in the same package. If so, they will be fine to "one-click update." If not, and 3.10 and 4.x have different packages, look at them case by case. They will normally fall into one of the following scenarios:</translate>
<translate> #* The extension has separate packages but upon upgrading to 4.x, they automatically detect this and still work. Make sure the developer confirms this.</translate>
<translate> #* The extension has separate packages that need to be uninstalled in 3.10.x and then installed with the Joomla 4.x version once the site is migrated. An example of this might be a content plugin. It is simple to uninstall it in 3.10.x and then install it again in 4.x.</translate>
<translate> #* See [[S:MyLanguage/Template_Considerations_During_Migration|Template Considerations]] for more specific information on templates and [[S:MyLanguage/J3.x:Converting_A_Previous_Joomla!_Version_Template|Converting a previous Joomla! Version template]]</translate>

<translate>
==== Notes on Search (com_search) ==== 
Search (com_search) will be decoupled in Joomla 4.x. Search (com_search) will migrate to Joomla 4. After migration, you'll need to update it to the Joomla 4.x version via com_installer. It will continue to be maintained, but more the same way a third-party extension is by receiving updates via com_installer. It is recommended to use Smart Search (com_finder) going forward. Search will still be available at https://extensions.joomla.org/category/official-extensions/.</translate>

<translate>
==== Notes on Weblinks ==== 
Weblinks was decoupled back in Joomla 3.4. If it was in use on a 2.5 site, the migration process would note this and migrate the Weblinks component and data. For the migration from 3.10.x to 4.x, it will be the same. It is still available and maintained on the JED at [https://extensions.joomla.org/category/official-extensions/ Official Extensions].</translate>

<translate>
==== Notes on Legacy Routing ====  </translate>
<translate> Legacy routing will not be available in Joomla 4.x. Only Modern will be available. When you do the migration, if you are using Legacy routing, the system will automatically change them to Modern routing. You will want to run a broken link checker on your site after migrating to Joomla 4.x and ''before you go live''.</translate>

<translate>
=== Going to Joomla! 4.x === 
Once you have either updated or uninstalled your third-party extensions so that only those compatible with Joomla! 4 remain in your installation, continue with the following steps:
</translate>
<translate>

# Go to {{rarr|System,Global Configuration,Server tab}} and turn Error Reporting from System Default to Maximum. Make sure to Save & Close.</translate>{{-}} [[File:J310-system-global-config-server-tab-<translate>

en</translate>.png|border|500px]]
<translate>

# Take another backup.
# Go to {{rarr|Components,Joomla Update}}. (It should say no updates found. If it doesn’t, update Joomla to the latest version and test. Then do another backup.) Click on the Options button at the top right corner.
# Select ''Joomla Next'' from the drop-down for Update Channel.</translate>{{-}}[[File:J310-component-joomla-update-select-support-<translate>

en</translate>.png|border|500px]]
<translate>

# Click Save & Close.
# You will then see your Installed Joomla Version, the Latest Joomla! version and the URL for the update package. Joomla will show you the requirements again for Joomla 4. If it flags that you have either an incompatible system or extensions it will tell you here. Take a moment to review this page.</translate>{{-}}[[File:J310-to-j4-dev-update-found-<translate>

en</translate>.png|border|800px]]
<translate>

# If the update is not showing up, go to {{rarr|Extensions,Update}} and select Clear Cache from the toolbar. Now the update to Joomla! 4 should show up.</translate>
<translate> # Cross your fingers, and make sure you have that backup available in case.</translate>
<translate> # Click the Install the Update button.</translate>
<translate> # Make tea whilst the status bar loads to fully green. The amount of time this takes is dependent on your site, Internet connection and server speed. The process takes about two minutes. When the update is finished, you will probably be logged out of the Administrator. Sign in again. Twice.</translate>
<translate> # If all goes well, you will get to a totally new look to the Backend panel.</translate>{{-}}[[File:j4-administrator-overview-<translate>

en</translate>.png|border|800px]]
<translate> # Go to {{rarr|System,Maintenance,Database}} and click ''Fix'' if any errors show.</translate>
<translate> # In {{rarr|System,Install,Discover}} see if there are any extensions to install. (There shouldn't be any!)</translate>
<translate> # Go to the Frontend of your site and see if it shows up even if it’s not the right template. If so, continue. If not, see [[S:MyLanguage/Joomla 3.10 to 4.x Common Migration Errors|common errors during migration]].</translate>
<translate> # Take a backup.</translate>
<translate> # Install your new template or other extensions if you have them to install. Back up often.</translate>
<translate> # Configure them. Back up often.</translate>
<translate> # Run a broken link checker and fix any broken links.</translate>
<translate> # Test everything. Back up often.</translate>
<translate>
# If everything works as expected, turn Error Reporting back to System Default ({{rarr|System,Global Configuration,Server tab}}). Make sure to Save & Close.
</translate>

<translate>
=== Going Live with Your Joomla! 4.x Site === 
# When you’re ready to go live, back up your 3.10 site for the last time. Restore it in a subdirectory or subdomain if you would like to.
# Back up your Joomla! 4.x site and move or restore your Joomla! 4.x site to the root (or change nameservers if you were building on a temporary domain at a new hosting account root).
# Test again.
# '''If''' you have made security changes to ''.htaccess'' file in the past, you may need to change a line (or lines) in it to update to Joomla 4. Please go to [https://docs.joomla.org/Htaccess_changes_after_joomla4.0.4 Htaccess changes after joomla4.0.4] to determine if you need to change your file.
# Remove the Joomla! 3.10 site from the server within a couple of days unless you have edited your ''robots.txt'' file to block the search engine spiders and disabled the Frontend of the site.
# Remove all development sites you have been working with or keep them up-to-date if they are running a current version in order to ward off hack attempts on your server. </translate>

<translate>

If you had data change on the 3.10 site while you were migrating to 4.x, you will want to get that data moved over to the 4.x site before going live. You can do this manually (make sure you keep the same user IDs - go in order) or by using a [https://extensions.joomla.org/category/migration-a-conversion/data-import-a-export%20transfer%20tool/third-party%20extension/ third party extension].
</translate>

<translate>
== Suggested Tools == </translate>
<translate>
* [http://extensions.joomla.org/extensions/access-a-security/site-security/backup/1606 Akeeba Backup] is popular for backup and restore. See more [https://extensions.joomla.org/tags/backup/ backup tools].
</translate>
<translate>
==Related information==  </translate>
[[Special:MyLanguage/:Pre-Update_Check|<translate> Pre-Update_Check</translate>]]
<noinclude>
<translate>

[[Category:Migration{{#translation:}}]]
[[Category:Tutorials{{#translation:}}]]
[[Category:Joomla! 4.x{{#translation:}}]]
</translate></noinclude>

J3.x:Access Control List Tutorial

2023-07-15T21:04:14Z

Cmb: Some markup changes.

<noinclude><languages /></noinclude>
{{Joomla version|version=3.x|comment=<translate>
series </translate>}}
{{-}}
<translate>
==Separate ACL for Viewing and Doing== 
</translate>

<translate>
The Joomla ACL system can be thought of as being divided into two completely separate systems. One system controls what things on the site Users can ''view''. The other controls what things Users can ''do'' (what actions a User can take). The ACL for each is set up differently.</translate>

<translate>
===Controlling What Users Can See=== 
</translate>

<translate>
The setup for controlling what Users can see is done as follows:
* Create a set of Access Levels according to the Categories and/or the combination of categories you wish only logged in Users to see. N.B. Do not assign any User groups to the new Access Levels at this point.</translate>

<translate>
* Create a User Group, with 'Registered' as parent, for each Access Level. Using the same names for the User Groups as the Access Levels will prevent confusion later.</translate>

<translate>
* Edit your new Access Levels and assign the correct (new) User Group to each one. You may also wish to assign the Super User Group (and/or the other default User Groups but not 'Guest' User Group) to all your new Access Levels</translate>

<translate>
* Assign each item to be viewed to one Access Level. Items include content items (articles, contacts, and so on), menu items, and modules.</translate>

<translate>
Any time a User is about to view an item on a Joomla page, the program checks whether the User has access to the item, as follows:</translate>
<translate>
# Creates a list of all the Access Levels that the User has access to, based on all Groups that the User belongs to. Also, if a group has a parent group, access levels for the parent group are also included in the list.</translate>
<translate>
# Checks whether the Access Level for the item (article, module, menu item, and so on) is on that list. If yes, then the item is displayed to the User. If no, then the item is not displayed.</translate>

<translate>
Note that Access Levels are set separately for each Group and are not inherited from a group's parent group.</translate>

<translate>
===Controlling What Users Can Do=== 
</translate>

<translate>
The system for setting up what Users in a User Group can do -- what actions they can take on a given item -- is set up with the Permissions tab of Global Configuration and the Permissions tab of the Options screen of each component. Permissions can also be set up at the Category level for core components and at the Article level for articles.</translate>

<translate>
* If you wish logged in Users to Create, Delete, Edit State or Edit Own for specific Categories then:</translate>
<translate>
** Create a User Group with the Parent as one of your User Groups that has Access to the Category(or Categories) you wish this new User Group to modify.</translate>
<translate>
**Assign your new User Group to the appropriate Access Level(s). Then change the required permissions for your new User Group either Globally or per Category/Article.</translate>
<translate>
***When creating a User Group it is good practice to select a parent group that has less permissions than needed for the new group. This is because it is easier to elevate permissions per Component/Category/Article that the extra permissions are needed for than it is to remove permissions from the other Components/Categories/Articles.</translate>
<translate>
****''(Example: You have ten Categories but you want Create permissions for just one. If you set Global permissions to Allow Create for that group you would need to remove Create permission for all those categories. And you would need to remove the Create permission for that group with any new Category that you add at a later date.)''</translate>
<translate>
**Only create a User Group with one of the default User Groups as parent if none of them have the exact permissions that you need and you wish all Categories</translate>

<translate>
Note that this set up is independent of the setup for viewing but a User Group needs to be assigned to the appropriate Access Level(s) in order for the User in that Group to use those Permissions.</translate>

<translate>
When a User wants to initiate a specific action against a component item (for example, edit an article), the system (after checking the Group the User is in has access) checks the permission for this combination of User, item, and action. If it is allowed, then the User can proceed. Otherwise, the action is not allowed.</translate>

<translate>
The remainder of this tutorial discusses how we control what Users can do -- what action permissions they have.</translate>

<translate>
==Actions, Groups, and Inheritance== 
</translate>

<translate>
The other side of ACL is granting permissions to Users to take actions on objects.</translate>

{| class="wikitable"
!style="width:20%;"|
!<translate>
3.x series</translate>
|-
!<translate>
Groups and Actions</translate>
|<translate>
Actions allowed for each group are defined by site administrator.</translate>
|-
!<translate>
Permission Scope</translate>
|<translate>
Permissions can be set at multiple levels in hierarchy: Site, Component, Category, Object.</translate>
|-
!<translate>
Permission Inheritance</translate>
|<translate>
Permissions can be inherited from parent Groups and parent Categories</translate>
|}

<translate>
===How Permissions Work=== 
</translate>

<translate>
There are four possible permissions for actions, as outlined below:</translate>

<translate>
* '''Not set''': Defaults to "deny" but, unlike the Deny permission, this permission can be overridden by setting a child group or a lower level in the permission hierarchy to "Allow." This permission only applies to the Global Configuration permissions.</translate>
<translate>
* '''Inherit''': Inherits the value from a parent Group or from a higher level in the permission hierarchy. This permission applies to all levels except the Global Configuration level.</translate>
<translate>
* '''Deny''': Denies this action for this level and group. '''IMPORTANT''' This also denies this action for all child groups and all lower levels in the permission hierarchy. Putting in Allow for a child group or a lower level will not have any effect. The action will always be denied for any child group member and for any lower level in the permission hierarchy.</translate>
<translate>
* '''Allow''': Allows this action for this level and group and for lower levels and child groups. This does not have any effect if a higher group or level is set to Deny or Allow. If a higher group or level is set to Deny, then this permission will always be denied. If a higher group or level is set to Allow, then this permission will already be allowed.</translate>
{{anchor|hierarchylevels}}
<translate>
===Permission Hierarchy Levels=== 
</translate>

<translate>
Action permissions in version 2.5+ can be defined at up to four levels, as follows:</translate>
<translate>
# '''Global Configuration''': determines the default permissions for each action and group.</translate>
<translate>
# {{rarr|Component Options,Permissions}}: can override the default permissions for this component (for example, Articles, Menus, Users, Banners, and so on).</translate>
<translate>
# '''Category''': can override the default permissions for objects in one or more categories. Applies to all components with categories, including Articles, Banners, Contacts, News Feeds, and Web Links.</translate>
<translate>
# '''Article''': Can override the permissions for a specific article. This level only applies to articles. Other components only allow the first three levels.</translate>

<translate>
====Global Configuration==== 


This is accessed from {{rarr|System,Global Configuration,Permissions}}. This screen allows you set the top-level permission for each group for each action, as shown in the screenshot below.</translate>

[[Image:Screenshot_global_acl_J3_tutorial-<translate>
en</translate>.png]]

<translate>
The options for each value are Inherited, Allowed, or Denied. The Calculated Setting column shows you the setting in effect. It is either Not Allowed (the default), Allowed, or Denied.</translate>

<translate>
You work on one Group at a time by opening the slider for that group. You change the permissions in the Select New Settings drop-down list boxes.</translate>

<translate>
Note that the Calculated Setting column is not updated until you press the Save button in the toolbar. To check that the settings are what you want, press the Save button and check the Calculated Settings column.</translate>

<translate>
====Component Options and Permissions==== 
</translate>
<translate>
This is accessed for each component by clicking the Options icon in the toolbar. This screen is similar to the Global Configuration screen above. For example, clicking the Options toolbar icon in the Menu Manager shows the Menus Configuration below.</translate>
[[Image:Screenshot_menu_acl_J3_tutorial-<translate>
en</translate>.jpg]]

<translate>
Access to Options is only available to members of groups who have permission for the Configure action in for each component. In the example above, the Administrator group has Allowed permission for the Configure option, so members of this group can access this screen.</translate>

<translate>
====Category==== 


Category permissions are accessed in the Category Manager: Edit Category screen, in a tab at the top of the screen. This screen has five permissions, as shown below.</translate>

[[Image:Screenshot_category_acl_j3_tutorial-<translate>
en</translate>.png]]

<translate>
In these screens, you work on the permissions for one User Group at a time. In the example above, we are editing the permissions for the Administrator group.</translate>

<translate>
Note that the Configure and Access Component actions do not apply at the category level, so those actions are not included.</translate>

<translate>
Note also that Categories can be arranged in a hierarchy. If so, then action permissions in a parent category are inherited automatically by a child category. For example, if you had a category hierarchy of {{rarr|Animals,Pets,Dogs}}, then the full permission level hierarchy for an article in the Dogs category would be as follows:</translate>
<translate>
* Global Configuration
* {{rarr|Article Manager,Options,Permission}}
* Animals Category
* Pets Category
* Dogs Category
* specific article</translate>

<translate>
====Article==== 
</translate>
<translate>
Permissions for a single article are accessed in the {{rarr|Article Manager,Edit Article}} screen, again in a slider at the bottom of the screen. This screen has three actions:</translate>

[[Image:j3x_acl_tutorial_article_manager_article_permissions-<translate>
en</translate>.png]]

<translate>
Again, you edit each group by clicking on it to open the slider for that group. You can then change the permissions under the Select New Setting column. To see the effect of any changes, press the Save button to update the Calculated Setting column.</translate>

<translate>
Note that the Configure, Access Component, and Create actions do not apply at the article level, so these actions are not included. Permission to create an article is set at one of the higher levels in the hierarchy.</translate>

<translate>
===Access Levels=== 
</translate>

<translate>
Access Levels in 3.x series are simple and flexible. The screen below shows the Special Access Level.</translate>
[[Image:j3x_acl_tutorial_viewing_levels-<translate>
en</translate>.png|center]]
<translate>
Simply check the box for each group you want included in that level. The Special Access Level includes the Manager, Author, and Super Users groups. It also includes child groups of those groups. So, Administrator group is included, since it is a child group of the Manager group. The Editor, Publisher, and Shop Suppliers groups are included, since they are child groups of Author. (Note that we could check all of the child groups if we wanted and it wouldn't hurt anything).</translate>

<translate>
Once Access Levels are created, they are used in the same way as in version 1.5. Each object in the Frontend is assigned an Access Level. If the level is Public, then anyone may access that object. Otherwise, only members of groups assigned to that access level may access that object. Access levels are assigned to Menu Items and to Modules. Each one can only be assigned to one access level.</translate>

<translate>
For example, the screen below shows the Edit Menu Item screen with the list of available access levels.</translate>

[[Image:j3x_acl_tutorial_edit_menu_item_level_dropdown-<translate>
en</translate>.png|center]]

<translate>
==Default ACL Setup== 
</translate>

<translate>
When Joomla! is installed, these are set to their initial default settings. We will discuss these initial settings as a way to understand how the ACL works.</translate>

<translate>
===Default Groups=== 
</translate>

<translate>
Version 3.x allows you to define your own Groups. When you install version 3.x, it includes a set of default groups, shown below are the basic default User groups. (Additional default User groups are installed with sample data.)</translate>

[[Image:Screenshot_usergroupsl_acl_J3_tutorial-<translate>
en</translate>.png|center]]

<translate>
The arrows indicate the child-parent relationships. As discussed above, when you set a permission for a parent group, this permission is automatically inherited by all child groups. The Inherited, and Allowed permissions can be overridden for a child group. The Denied permission cannot be overridden and will always deny an action for all child groups.</translate>

<translate>
===Global Configuration=== 
</translate>

<translate>
Joomla! version 2.5 will install with the same familiar Backend permissions as that of version 1.5. However, with 2.5, you can easily change these to suit the needs of your site.</translate>

<translate>
As discussed earlier, the permissions for each action are inherited from the level above in the permission hierarchy and from a group's parent group. Let's see how this works. The top level for this is the entire site. This is set up in the {{rarr|Site,Global Configuration,Permissions}}, as shown below.</translate>

[[Image:Screenshot_global_acl_J3_tutorial-<translate>
en</translate>.png]]

<translate>
The first thing to notice are the ten Actions: Site Login, Admin Login, Offline Access, Super User, Access Administration Interface, Create, Delete, Edit, Edit State. and Edit Own. These are the actions that a User can perform on an object in Joomla. The specific meaning of each action depends on the context. For the Global Configuration screen, they are defined as follows:</translate>

<translate>
;Site Login : Login to the Frontend of the site


;Admin Login : Login to the Backend of the site</translate>

<translate>
;Offline Access : Login to the Frontend of the site when the website site is offline (when Global Configuration setting "Site Offline" is set to Yes)</translate>

<translate>
; Super User : Grants the User "Super User" status. Users with this permission can do anything on the site. Only Users with this permission can change Global Configuration settings (this screen). These permissions cannot be restricted. It is important to understand that, if a User is a member of a Super User group, any other permissions assigned to this User are irrelevant. The User can do any action on the site. However, Access Levels can still be assigned to control what this group sees on the site. (Obviously, a Super User can change Access Levels if they want to, so Access Levels do not totally restrict what a Super User can see.)</translate>

<translate>
;Access Component: Open the component manager screens (User Manager, Menu Manager, Article Manager, and so on)</translate>

<translate>
;Create : Create new objects (for example, Users, Menu Items, Articles, Web Links, and so on)</translate>

<translate>
;Delete : Delete existing objects</translate>

<translate>
;Edit : Edit existing objects</translate>

<translate>
;Edit State : Change object state (Publish, Unpublish, Archive, and Trash)</translate>

<translate>
;Edit Own : Edit objects that you have created.</translate>

<translate>
Each Group for the site has its own slider which is opened by clicking on the group name. In this case (with the sample data installed), we have the standard 7 groups that we had in version 1.5 plus two additional groups called "Shop Suppliers" and "Customer Group." Notice that our groups are set up with the same permissions as they had in version 1.5. Keep in mind that we can change any of these permissions to make the security work the way we want. Let's go through this to see how it works.</translate>

<translate>
* '''Public''' has everything set to "Not set", as shown below.</translate>{{-}}[[Image:Screenshot_global_acl_public_J3_tutorial-<translate>
en</translate>.png]]
<translate>
**This can be a bit confusing. Basically, "Not Set" is the same as "Inherited." Because Public is our top-level group, and because Global Configuration is the top level of the component hierarchy, there is nothing to inherit from. So "Not Set" is used instead of "Inherit."</translate>
<translate>
**The default in this case is for no permissions. As you would expect, the Public group has no special permissions. Also, it is important to note that, since nothing is set to Denied, all of these permissions may be overridden by child groups or by lower levels in the permission hierarchy.</translate>

<translate>
* '''Guest''' is a 'child' group of the Public group has everything set to 'Inherited'</translate> {{-}}[[Image:Screenshot_global_acl_guest_J3_tutorial-<translate>
en</translate>.png]]
<translate>
** This is the default 'Guest User Group' in the User Manager options and the Group that (non logged in) visitors to your site are placed in.</translate>

<translate>
* '''Manager''' is a "child" group of the Public group. It has Allowed permissions for everything except Access Component and Super User. So a member of this group can do everything in the front and Backend of the site except change Global Permissions and Component Options.</translate> {{-}}[[Image:Screenshot_global_acl_manager_J3_tutorial-<translate>
en</translate>.png]]

<translate>
* '''Administrator''' group members inherit all of the Manager permissions and also have Allowed for Access Component. So members of this group by default can access the Options screens for each component.</translate> {{-}}[[Image:Screenshot_global_acl_administrator_J3_tutorial-<translate>
en</translate>.png]]

<translate>
* '''Registered''' is the same a Public except for the Allow permission for the Site Login action. This means that members of the Registered group can login to the site. Since default permissions are inherited, this means that, unless a child group overrides this permission, all child groups of the Registered group will be able to login as well.</translate> {{-}}[[Image:Screenshot_global_acl_registered_J3_tutorial-<translate>
en</translate>.png]]

<translate>
* '''Author''' is a child of the Registered group and inherits its permissions and also adds Create and Edit Own. Since Author, Editor, and Publisher have no Backend permissions, we will discuss them below, when we discuss Frontend permissions.</translate>{{-}}[[Image:Screenshot_global_acl_author_J3_tutorial-<translate>
en</translate>.png]]

<translate>
* '''Editor''' is a child of the Authors group and adds the Edit permission.</translate> {{-}}[[Image:Screenshot_global_acl_editor_J3_tutorial-<translate>
en</translate>.png]]

<translate>
* '''Publisher''' is a child of Editor and adds the Edit State permission.</translate>{{-}}[[Image:Screenshot_global_acl_publisher_J3_tutorial-<translate>
en</translate>.png]]

<translate>
* '''Shop Suppliers''' is an example group that is installed if you install the sample data. It is a child group of Author.</translate>

<translate>
* '''Customer Group''' is an example group that is installed if you install the sample data. It is a child group of Registered.</translate>

<translate>
* '''Super Users''' group has the Allow permission for the Super User action. Because of this, members of this group have Super User permissions throughout the site. They are the only Users who can access and edit values on the Global Configuration screen. Users with permission for the Super User action have some special characteristics:</translate>
<translate>
:* If a User has Super User permissions, no other permissions for this User matter. The User can perform any action on the site.</translate>
<translate>
:* Only Super Users can create, edit, or delete other Super Users or groups.</translate>

<translate>
There are two important points to understand from this screen. The first is to see how the permissions can be inherited from the parent Group. The second is to see how you can control the default permissions by Group and by Action.</translate>

<translate>
This provides a lot of flexibility. For example, if you wanted Shop Suppliers to be able to have the ability to login to the Backend, you could just change their Admin Login value to "Allowed." If you wanted to not allow members of Administrator group to delete objects or change their state, you would change their permissions in these columns to Inherited (or Denied).</translate>

<translate>
It is also important to understand that the ability to have child groups is completely optional. It allows you to save some time when setting up new groups. However, if you like, you can set up all groups to have Public as the parent and not inherit any permissions from a parent group.</translate>

<translate>
===Component Options and Permissions=== 
</translate>

<translate>
Just looking at the Global Configuration screen above, it would appear that the Administrator group and the Manager group have identical permissions. However, in version 1.5 Administrators can do everything except Global Configuration, whereas Managers are not permitted to add Users or work with menu items. That is also true in the default version 2.5 configuration. Let's see how this is accomplished.</translate>

<translate>
If we navigate to {{rarr|Users,User Manager}} and click the Options button in the toolbar, we see the screen below:</translate>

[[Image:screenshot_acl_tutorial_20110111-09-<translate>
en</translate>.png|center|]]
[[Image:screenshot_acl_tutorial_20110111-10-<translate>
en</translate>.png|center|]]

<translate>
This screen is the same as the Global Configuration Permissions screen, except that these values only affect working with Users. Let's look at how this works.</translate>

<translate>
First, notice that the Administrator group has Allow permission for the Admin action and the Manager group has Deny permission for this action. Remember that the Admin action in the Global Configuration screen gives the group "Super User" permissions. In this screen, the Admin action allows you to edit the Options values. So, the Administrator group can do this but the Manager group cannot.</translate>

<translate>
Next, notice that the Administrator has Inherit for the Manage action and the Manager group has Deny permission. In this screen, the Manage action gives a group access to the User Manager. Since the Administrator has Allow for the Manage action by default, then the Inherit permission here means they inherit the Allow permission for the Manage action. Since the Manager group has Deny permission for the Manage action, members of the Manager group cannot access the User Manager and therefore cannot do any of the other User-related actions.</translate>

<translate>
If you look at the Options for {{rarr|Menus,Menu Manager}}, you will see the same default settings as for the User Manager. Again, the Administrator group can manage and set default permissions for Menu Manager objects whereas the Manager group cannot.</translate>

<translate>
In short, we can see that the different permissions for the Administrator and Manager groups are set using the {{rarr|Options,Permissions}} forms on the User Manager and Menu Manager screens.</translate>

<translate>
It is also important to understand that this same {{rarr|Options,Permissions}} form for setting default permissions is available for all Joomla! objects, including Media Manager, Banners, Contacts, News Feeds, Redirect, Search Statistics, Web Links, Extensions, Modules, Plugins, Templates, and Language. So you now have the option to create User groups with fine-tuned sets of Backend permissions.</translate>

<translate>
===Frontend Permissions=== 
</translate>

<translate>
Default permissions for the Frontend are also set using the Options form. Let's look at {{rarr|Content,Article Manager,Options,Permissions}}. First, let's look at the permissions for Manager, as shown below.</translate>
[[Image:screenshot_acl_tutorial_20110111-11a-<translate>
en</translate>.png|center|frame]]
<translate>
Manager has allowed permission for all actions except Configure. So members of the Manager group can do everything with Articles except open the Options screen.</translate>

<translate>
Now let's look at Administrator, as shown below.</translate>
[[Image:screenshot_acl_tutorial_20110111-12a-<translate>
en</translate>.png|center|frame]]
<translate>
Administrator has Allowed for Configure, so Administrators can edit this Options screen.</translate>

<translate>
Both groups can create, delete, edit, and change the state of articles.</translate>

<translate>
Now, let's look at the groups Publisher, Editor, and Author and see how their permissions are set.</translate>

<translate>
Authors only have Create and Edit Own permissions, as shown below.</translate>
[[Image:screenshot_acl_tutorial_20110112-07-<translate>
en</translate>.png|center|frame]]
<translate>
This means that Authors can create articles and can edit articles they have created. They may not delete articles, change the published state of articles, or edit articles created by others.</translate>

<translate>
Editors have the same permissions as Authors with the addition of permission for the Edit action, as shown below.</translate>
[[Image:screenshot_acl_tutorial_20110112-08-<translate>
en</translate>.png|center|frame]]
<translate>
So Editors can edit articles written by anyone.</translate>

<translate>
Publishers can do everything Editors can do plus they have permission for the Edit State action, as shown below.</translate>
[[Image:screenshot_acl_tutorial_20110112-09-<translate>
en</translate>.png|center|frame]]
<translate>
So Publishers can change the published state of an article. The possible states include Published, Unpublished, Archived, and Trashed.</translate>

<translate>
All of these groups have Inherit permission for Configure and Access Component. Remember that Author is a child of the Registered group, and Registered does not have any default permissions except for Login. Since Registered does not have permission for Configure and Access Component, and since Author's permission for these actions is "Inherited", then Author does not have these permissions either. This same permission is passed from Author to Editor and from Editor to Publisher. So, by default, none of these groups are allowed to work with articles in the Backend.</translate>

<translate>
It is important to remember that these permissions are only default settings for categories and articles and for any child groups that are created. So they can be overridden for child groups, for categories, and for specific articles.</translate>

<translate>
Also, note that there are no Denied permissions for any actions in the default settings. This allows you to add Allowed permissions at any level. Remember, once you have an action set for Denied, this action will be denied at all lower levels in the hierarchy. For example, if you set the Admin Login for Registered to Denied (instead of Allowed), you could not grant Publishers Allowed permissions for this action.</translate>

<translate>
=== Article Manager and Actions Diagram === 
</translate>

<translate>
The diagram below shows how each action in the permissions form relates to the various options on the Article Manager screen.</translate>

[[Image:screenshot_acl_tutorial_20110111-16-<translate>
en</translate>.png|center|]]

<translate>
* '''Configure''' allows you to view and change the Options for the component.</translate>
<translate>
* '''Access Component''' allows you to navigate to the Article Manager. Without this permission, no other actions are possible.</translate>
<translate>
* '''Create''' allows you to add new articles.</translate>
<translate>
* '''Delete''' allows you to delete trashed articles. Note that the Delete icon only shows in the toolbar when you have the "Select State" filter set to "Trash."</translate>
<translate>
* '''Edit''' allows you to edit existing articles.</translate>
<translate>
* '''Edit State''' allows to you Publish, Unpublish, Archive, or Trash articles.</translate>
<translate>
* '''Edit Own''' is the same as Edit except that it only applies to articles written by you.</translate>

<translate>
==Allowing Guest-Only Access to Menu Items and Modules== 
</translate>

<translate>
Version 1.6 introduced the ability to create a View Access Level that is only for guests of the site (meaning a User who is not logged in). The example below shows how you can set up this new feature.
''(N.B. Steps 1 to 3 are not needed for Joomla! 3.x as they exist in the default install.)''</translate>

<translate>
#Create a new User group called Guest. Make it a child of the Public group as shown below.</translate> [[Image:screenshot_acl_tutorial_20110112-01-<translate>
en</translate>.png|center|frame]]
<translate>
# Create a new access level called Guest and grant only the Guest group access to this level, as shown below.</translate>[[Image:screenshot_acl_tutorial_20110112-02-<translate>
en</translate>.png|center|frame]]
<translate>
# Navigate to {{rarr|User Manager,Options,Component}} and change the Guest User Group from the default value of "Public" to "Guest", as shown below.</translate>
[[Image:screenshot_acl_tutorial_20110112-04-<translate>
en</translate>.png|center|frame]]
<translate>
Now, if we assign a menu item, module, or other object to the Guest access level, only non-logged in Users will have access. For example, if we create a new menu item with access level of Guest, as shown below,</translate>
[[Image:screenshot_acl_tutorial_20110112-05-<translate>
en</translate>.png|center|frame]]
<translate>
This menu item will only be visible to non-logged-in visitors to the site.</translate>

<translate>
If required other User groups like Author can be granted access in the Guest access level, this would allow Authors to view articles in the Frontend for editing.</translate>

<translate>
'''N.B. Login/logout in Frontend (''for changing data in session'') to see the change.'''</translate>

<translate>
==Using Permission and Group Levels Together== 
</translate>

<translate>
As discussed above, it is possible to define groups in a hierarchy, where each child group inherits action permissions (for example, the create permission) from its parent group. Action permissions are also be inherited from the permission level above. For example, a permission in the Article Manager is inherited from the same permission in the Global Configuration, and a permission in a child Category is inherited from the parent Category permission.</translate>

<translate>
This dual inheritance can be confusing, but it can also be useful. Let's consider an example as follows. We have a school with a group hierarchy of {{rarr|Teachers,History Teachers,Assistant History Teachers}}. We also have a category hierarchy of {{rarr|Assignments,History Assignments}}. We want History Teachers and Assistant History Teachers to have the following permissions:</translate>

<translate>
* both groups can create new articles only in the History Assignments category.</translate>

<translate>
* only History Teachers (not Assistant History Teachers) can Publish or otherwise have Edit State permission.</translate>

<translate>
This ACL scheme is easy to implement. The diagram below shows how this would be set up for the Create Action.</translate>

[[Image:Acl example diagram1 20091018-<translate>
en</translate>.png|center|]]

<translate>
In the diagram, the Permission Hierarchy is shown down the left side and the Group hierarchy is shown across the top. Permissions are inherited down and to the right, as shown by the arrows. To implement the desired permissions, we leave the Global Configuration blank (Not Set) for all three groups. Similarly, in the Article Manager and Assignments Category, we leave the Create permission to Inherit for all the groups. As shown in the diagram, this means that these groups do not have Create permission for articles in general or for articles in the Assignments group.</translate>

<translate>
To sum up so far, we have not set any special permissions to get to this point. Now, in the History Assignments category permissions screen, we set the Create permission to Allow for the History Teachers group. This setting overrides the Soft (Implicit) Deny that we had by default and gives members of this group permission to create content (articles and child categories) for this category. This Allow setting also is inherited by the Assistant History Teachers group.</translate>

<translate>
Next, we need to grant History Teachers the Edit State permission while denying this permission to Assistant History Teachers. This is done as shown in the diagram below.</translate>

[[Image:Acl example diagram2 20091018-<translate>
en</translate>.png|center|]]

<translate>
This configuration is the same as the one above except that this time we set the Edit State permission in the History Assignments category to Deny for the Assistant History Teachers group. This means that Assistant History Teachers will not be able to Publish or Unpublish articles in this category.</translate>

<translate>
Note that this was accomplished by setting just two permissions in the History Assignments category: Allow for the History Teachers group and Deny for the Assistant History Teachers group.</translate>

<translate>
==ACL Action Permission Examples== 


Here are some examples of how you might set up the ACL for some specific situations.</translate>

<translate>
===Backend Article Administrator=== 
</translate>

<translate>
'''Problem'''</translate>

<translate>
We want to create a group called "Article Administrator" with Backend permissions only for articles and not for any other Backend menu options. Members of this group should be able to use all of the features of the article manager, including setting article permissions.</translate>

<translate>
'''Solution'''</translate>

<translate>
# Create a new group called Article Administrator and make its parent group Public, as shown below.</translate>[[Image:screenshot_acl_tutorial_20110112-10-<translate>
en</translate>.png|center|frame]] <translate>
Because its parent group is Public, it won't have any permissions by default.</translate>
<translate>
# In {{rarr|Users,Access Levels}}, edit the Special Access level to add the new group. That way they can get access to the Backend menu items and modules (This assumes that the modules for the admin menu and quick icons have the Special Access level assigned to them, which is the default.)</translate> [[Image:screenshot_acl_tutorial_20110112-11-<translate>
en</translate>.png|center|frame]] <translate>
By default, the Backend menu items and modules are set to Special access, so if you forget to add the new group to the Special access level, you won't see any modules or menu items when you log in as a User of the new group.</translate>
<translate>
# In {{rarr|Site,Global Configuration,Permissions}}, click on the Article Administrator group and change the permissions to Allowed for the following actions: Admin Login, Create, Delete, Edit, Edit State, and Edit Own. The screen below shows what will show before you press Save.</translate> [[Image:screenshot_acl_tutorial_20110112-12-<translate>
en</translate>.png|center|frame]]<translate>
After you save, the Calculated Permissions should show as shown below.</translate>[[Image:screenshot_acl_tutorial_20110112-13-<translate>
en</translate>.png|center|frame]]<translate>
Note that the permission for the Access Component is Inherited, which translates to Not Allowed. This is important. This means that this group will only be able to access components if we give the group "Allowed" permission for Access Component. So we only have to change the one component we want to give them access to and don't have to change any settings for the components where we don't want them to have access. If we had a case where we wanted to give a group access to everything except for one component, we could set the default to Allowed and then set the one component to Denied. Also note that we did not give the group Site Login permission, so Users in this group will not be able to log into the Frontend. (If we wanted to allow that, we would just change the permission to Allowed for Site Login.)</translate>
<translate>
# In {{rarr|Article Manager,Options,Permissions}}, change permissions to Allowed for this group for the Access Component action, as shown below.</translate>[[Image:screenshot_acl_tutorial_20110112-14-<translate>
en</translate>.png|center|frame]]<translate>
All of the other desired permissions are inherited.</translate>

<translate>
That's all you need to do. Members of this group can login to the Backend and do everything in Article Manager but can't do anything else in the Backend. For example, the screen below shows what a User in the Article Manager will see when they login to the Backend.</translate>[[Image:screenshot_acl_tutorial_20110112-15-<translate>
en</translate>.png|center|frame]]

<translate>
==ACL View Access Levels Examples== 
</translate>

<translate>
A basic concept of using Access Levels is that all items with the same Access will be viewable by the same group of Users. In other words, if two items have the same Access, you can't have one viewable by one User and not viewable by another User. On the other hand, it is easy to have one Group view any number of items with different Access levels.</translate>

<translate>
Similarly, each Group has exactly the same combination of Access levels, but one User can be a member of more than one group. Depending on the situation, you may want to have Users only in one Group or you may need to have a User in more than one Group.</translate>

<translate>
This means that we may need to group our items so that items so that all items in a group have the same level of sensitivity. Here are some examples.</translate>

<translate>
===Hierarchical Example=== 
</translate>
<translate>
In this example, Access levels are hierarchical, for example, like government security clearance codes. Say for example we have the following sets of classified documents: Classified, Secret, and Top Secret. Users have corresponding clearance codes. Users with Classified clearance can only see Classified documents and cannot see Secret or Top Secret. Users with Secret clearance can see Classified and Secret documents but not Top Secret. Users with Top Secret can see all documents.</translate>

<translate>
In this case, you would create three Access levels: Classified, Secret, and Top Secret and the same three Groups. Users would only be members of one group, as follows:</translate>

{| style="border-spacing:0;"
| style="border-top:0.0007in solid #000000;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| <translate>
User</translate>
| style="border-top:0.0007in solid #000000;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| <translate>
Group</translate>
| style="border:0.0007in solid #000000;padding:0.0382in;"| <translate>
Access Levels</translate>

|-
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| C1, C2, C3
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| <translate>
Classified</translate>
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:0.0007in solid #000000;padding:0.0382in;"| <translate>
Classified</translate>

|-
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| S1, S2, S3
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| <translate>
Secret</translate>
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:0.0007in solid #000000;padding:0.0382in;"| <translate>
Classified, Secret</translate>

|-
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| TS1, TS2, TS3
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| <translate>
Top Secret</translate>
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:0.0007in solid #000000;padding:0.0382in;"| <translate>
Classified, Secret, Top Secret</translate>

|}

<translate>
In this case, all Users are in exactly one group, but some groups have access to more than one Access Level of items. In other words, we have a one-to-one relationship between Users and groups, but a one-to-many relationship between Groups and Access Levels.</translate>

<translate>
===Team Security Example=== 
</translate>

<translate>
Another possible use case is a set of non-hierarchical teams. Let's say we have three teams, T1, T2, and T3. Some Users are only on one team, but others might be on two or more teams. In this case, we could set up our Access Levels and Groups by team. Documents for each team have the access level for that team, and the Group for the team has only the one access level. When a User is on more than one team, they get added to the group for each team, as follows:</translate>

{| style="border-spacing:0;"
| style="border-top:0.0007in solid #000000;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| <translate>
User</translate>
| style="border-top:0.0007in solid #000000;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| <translate>
Description</translate>
| style="border-top:0.0007in solid #000000;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| <translate>
Group</translate>
| style="border:0.0007in solid #000000;padding:0.0382in;"| <translate>
Access Levels</translate>

|-
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| U1
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| <translate>
Team 1 member</translate>
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| T1
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:0.0007in solid #000000;padding:0.0382in;"| T1

|-
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| U2
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| <translate>
Team 2 member</translate>
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| T2
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:0.0007in solid #000000;padding:0.0382in;"| T2

|-
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| U3
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| <translate>
Team 3 member</translate>
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| T3
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:0.0007in solid #000000;padding:0.0382in;"| T3

|-
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| U1-2
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| <translate>
Member of teams 1 and 2</translate>
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| T1, T2
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:0.0007in solid #000000;padding:0.0382in;"| T1, T2

|-
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| U1-3
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| <translate>
Member of teams 1 and 3</translate>
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| T1, T3
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:0.0007in solid #000000;padding:0.0382in;"| T1, T3

|-
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| U1-2-3
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| <translate>
Member of teams 1,2, and 3</translate>
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| T1,T2, T3
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:0.0007in solid #000000;padding:0.0382in;"| T1, T2, T3

|}

<translate>
===Hybrid Example=== 
</translate>

<translate>
In a real-world situation, you might have a combination of these two arrangements. Say for example we have Managers and Staff. Staff can only see Staff documents and Managers can see Manager and Staff documents. Both types of Users can be assigned to teams as well, in which case they can see all of the documents for that team. In addition, say that Managers can access some, but not all, team documents. Staff can only access team documents if they are members of that team.</translate>

<translate>
In this example, we could set up the following Access Levels:</translate>

{| style="border-spacing:0;"
| style="border-top:0.0007in solid #000000;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| <translate>
Access Level</translate>
| style="border-top:0.0007in solid #000000;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| <translate>
Description</translate>
| style="border:0.0007in solid #000000;padding:0.0382in;"| <translate>
Groups</translate>

|-
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| <translate>
Manager</translate>
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| <translate>
Non-team manager documents</translate>
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:0.0007in solid #000000;padding:0.0382in;"| <translate>
Manager</translate>

|-
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| <translate>
Staff</translate>
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| <translate>
Non-team staff documents</translate>
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:0.0007in solid #000000;padding:0.0382in;"| <translate>
Manager, Staff</translate>

|-
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| <translate>
Team1</translate>
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| <translate>
Sensitive Team1 documents (no access outside team)</translate>
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:0.0007in solid #000000;padding:0.0382in;"| <translate>
Team1</translate>

|-
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| <translate>
Team1-Manager</translate>
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| <translate>
Team1 documents that can be accessed by all managers</translate>
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:0.0007in solid #000000;padding:0.0382in;"| <translate>
Team1, Manager</translate>

|-
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| <translate>
Team2</translate>
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| <translate>
Sensitive Team2 documents (no access outside team)</translate>
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:0.0007in solid #000000;padding:0.0382in;"| <translate>
Team2</translate>

|-
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| <translate>
Team2-Manager</translate>
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| <translate>
Team2 documents that can be accessed by all managers</translate>
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:0.0007in solid #000000;padding:0.0382in;"| <translate>
Team2, Manager</translate>

|}

<translate>
Then, Users could be assigned to groups as follows:</translate>

{| style="border-spacing:0;"
| style="border-top:0.0007in solid #000000;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| <translate>
User Type</translate>
| style="border:0.0007in solid #000000;padding:0.0382in;"| <translate>
Group</translate>

|-
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| <translate>
Manager on no teams</translate>
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:0.0007in solid #000000;padding:0.0382in;"| <translate>
Manager</translate>

|-
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| Staff on no teams
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:0.0007in solid #000000;padding:0.0382in;"| Staff

|-
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| <translate>
Manager on team 1</translate>
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:0.0007in solid #000000;padding:0.0382in;"| <translate>
Manager, Team1</translate>

|-
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| <translate>
Staff on team 1</translate>
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:0.0007in solid #000000;padding:0.0382in;"| <translate>
Staff, Team1</translate>

|-
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| <translate>
Manager on teams 1 and 2</translate>
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:0.0007in solid #000000;padding:0.0382in;"| <translate>
Manager, Team1, Team2</translate>

|-
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:none;padding:0.0382in;"| <translate>
Staff on teams 1 and 2</translate>
| style="border-top:none;border-bottom:0.0007in solid #000000;border-left:0.0007in solid #000000;border-right:0.0007in solid #000000;padding:0.0382in;"| <translate>
Staff, Team1, Team2</translate>
|}

<noinclude>
<translate>

[[Category:Joomla! 1.6]]
[[Category:Joomla! 2.5]]
[[Category:Joomla! 3.x]]
[[Category:Tutorials]]
[[Category:Access Control]]
[[Category:Access Management]]
</translate>
</noinclude>

Git for Coders

2023-07-10T15:01:05Z

Cmb: Several markup changes. URL changes. Capitalization and spelling corrections.

=Overview=
This article shows you how to use Git and GitHub to code and submit changes to the Joomla CMS. If you are not familiar with Git, you may wish to read the tutorial [[Git_for_Testers_and_Trackers | Git for Testers and Trackers]] first.

''IMPORTANT NOTE: Git is a very powerful system and there is usually more than one way to accomplish the same thing in Git. This tutorial does not try to cover all of the different ways you could do these tasks. Instead, it covers one (hopefully simple) way to do it. As you become more familiar with Git, you may find other ways that work better for you.''

The first step is to set up the remote and local Git repositories. You do this once. Once it is set up, the normal workflow is:
# Update your local and remote repositories with changes others have committed to the main Joomla CMS repository.
# Create a branch for each issue or feature you are working on and commit your changes to the branch in your local repository.
# Update your remote repository on GitHub with your branches.
# Create a pull request from your GitHub branch. Alternatively, you can create a patch or diff file from your local branch and post that to the tracker.
# Update the Joomla Issue tracker or Joomla Feature tracker so that others can test your code.

Each of these steps is explained below. Note that you can use Git from the command line, from an IDE such as Eclipse (with the eGit plugin), or from a stand-alone tool, such as TortoiseGit. Here we will use the command line and, where applicable, show the equivalent command in Eclipse eGit.

NOTE: If you want to propose a simple code change, you can do it directly from GitHub.com, without setting up anything on your local PC. See [[Using_the_Github_UI_to_Make_Pull_Requests|Using the GitHub UI to Make Pull Requests]].

=Setup=
== GitHub Work Flow for Joomla! ==

[[File:Github work flow joomla.png]]

== Create Your Forked Repository on GitHub==
GitHub allows you to create your own copy of any public repository, including the Joomla CMS. This is your personal copy of the repository and is called a "fork". To create a fork of the Joomla CMS:
# If you haven't already, register on GitHub.com and log in.
# Navigate to [https://github.com/joomla/joomla-cms https://github.com/joomla/joomla-cms]
# Click on the Fork button in the upper right part of the screen.

Note that you can only create one fork of any given repository. However, as we will see, you can create as many branches (versions) of your repository as you like.

== Clone Your GitHub Repository To Your PC ==
At this point, you have your own repository on GitHub.com. Now you need to create a local repository that is a copy (called a "clone") of the GitHub repository. To do this:
===CLI (command line) Commands===
# Change directory to the directory where you want the Joomla files to be stored (for example, <code>C:\xampp\htdocs\joomla\my-project</code> or <code>/opt/lampp/htdocs/joomla/my-project</code>).
# Enter the command: <code>git clone <nowiki>https://github.com/<your GitHub user name>/joomla-cms.git</nowiki> .</code> For example, if your GitHub user name is "joomla-coder", the command would be: <code>git clone <nowiki>https://github.com/joomla-coder/joomla-cms.git</nowiki> .</code>

You can get the URL for the command above from your repository at GitHub.com as shown below. [[File:git-coders-tutorial-20121009-03.png|frame|none]]

Note that the "." dot just tells Git to put the new repository in the current directory. The system will work for a few minutes while it downloads all of the files. When it is finished, you will have a complete set of Joomla files under version control in the current directory.

=== Eclipse Commands ===
# If you like, you can get the URL from GitHub as shown below. [[File:git-coders-tutorial-20121009-03.png|frame|none]] You will use this later on.
# In Eclipse, open the Git Repositories view and click the button called "Clone a Git Repository and add the clone to this view" as shown below. [[File:git-coders-tutorial-20121009-01.png|frame|none]]
# The window below will show. [[File:git-coders-tutorial-20121009-02.png|frame|none]] Select URI and click Next.
# The window below will show. [[File:git-coders-tutorial-20121009-04.png|frame|none]] Enter the GitHub URL for your repository (from step (1) above). Enter your GitHub user name and password and check the box called "Store in Secure Store".
# Click Next and the window below will show. [[File:git-coders-tutorial-20121009-05.png|frame|none]]
# Click Next to select all branches. The window below will show. [[File:git-coders-tutorial-20121009-06.png|frame|none]]
# In Directory, enter the folder where you want the Joomla files to be copied. Keep the default values for Initial branch ("master") and Remote name ("origin") as shown.
# Click Finish. The system will work for a few minutes. When it finishes you will have a clone of the remote repository.

== Create an Upstream Remote==
Now we have our local repository. This has a remote called "origin" that points to our personal fork of Joomla on GitHub.

In a project like Joomla, many users are submitting bug fixes and features. These changes are committed to the main Joomla CMS repository frequently. It is up to each coder to keep their personal repositories up to date with these changes. Fortunately, as we will see, this is easy to do.

The last step in the setup is to create a second remote called "upstream" that points to the main Joomla CMS repository. We will use this remote to pull changes that others make to the main Joomla repository so we can keep our personal repositories up to date.

===CLI Command ===
To create a remote called "upstream" that points to the main CMS repository, enter this command:

<code>git remote add upstream <nowiki>https://github.com/joomla/joomla-cms.git</nowiki></code>

Note, if you get a error like "fatal: Not a git repository (or any of the parent directories): .git", then make sure you've changed directory to the new repository that's been created within the current directory (so one level lower).

===Eclipse Command===
''Unknown at this time.''

At this point, you have your personal remote repository (created by "forking" the Joomla CMS project) and your personal local repository (created with CLI or Eclipse). Now you are ready to code patches and features.

=Normal Workflow=
Now that we have done our one-time setup, we are ready to start our normal workflow. This is outlined below.

== Create a New Feature or Bug Fix Change==
Let's say you are ready to start working on a new bug fix or a new feature. Here are the steps you would normally follow.
# Update your master branches. Update the master branch of your local and GitHub repositories with the latest CMS changes.
# Create a branch for writing the new code
# In the new branch, code the changes and commit them. Depending on the length of time, you can make multiple commits to the branch.
# When you are ready to propose your code for testing (or when you want others to be able to see it), push the branch to your GitHub repository.
# When you are ready to submit the code, either:
## Create a pull request on GitHub, or
## Create a patch or diff file and post to the Joomlacode tracker.

Each of these steps is explained in more detail below.

=== Update Your Master Branches ===
You need to keep your repositories up to date with changes made by others in the main CMS repository. It's easy to do, and here are the steps. These are done more easily with the CLI than with Eclipse.

IMPORTANT NOTE: Make sure you never commit your own code changes to the master branch. If you do, you won't be able to keep it synchronized with the master branch on the main CMS repository.

====CLI Commands====
* Make sure you are in your master branch of your local repository (<code>git checkout master</code>). If you aren't sure, you can use the command <code>git status</code> to see what branch you are on.
* Enter the command: <code>git pull upstream master</code>. You should get a message showing the changes, similar to this:
$ git pull upstream master
From <nowiki>https://github.com/joomla/joomla-cms</nowiki>
* branch master -> FETCH_HEAD
Updating 76feee8..294c62c
Fast-forward
installation/CHANGELOG | 3 +++
installation/language/fr-FR/fr-FR.ini | 2 +-
2 files changed, 4 insertions(+), 1 deletion(-)
Mark@MARK2009 /c/xampp/htdocs/joomla-coder/joomla-cms (master)
:If your local repository was already up to date, you will get a message like this:
$ git pull upstream master
From <nowiki>https://github.com/joomla/joomla-cms</nowiki>
* branch master -> FETCH_HEAD
Already up-to-date.

* At this point, your local master branch is up to date with the main CMS repository. Now you need to update the master branch of your GitHub repository. Enter the command: <code>git push origin master</code>. You should see a message like this:
$ git push origin master
To <nowiki>https://github.com/joomla-coder/joomla-cms.git</nowiki>
76feee8..294c62c master -> master

NOTE: If you haven't stored your user name and password, you will be prompted for them after you enter the push command. See below for how to store your credentials so you don't have to type them each time.

At this point, your master branches on your local and GitHub repositories are up to date with the main CMS repository. Now, when you create a new branch, it will start at this point and be based on the latest code.

===Create a Branch for the Code===
In Git, the best practice is to use a branch for each bug fix or feature. (In fact, experienced Git users will often create more than one branch for an individual project, perhaps trying different approaches to the problem.) It is super easy to create, delete, and even combine branches. Use a naming convention that allows you to keep track. For example, you could incorporate the tracker issue number into the branch name (for example, "php-notice-12345").

When you create a new branch, it starts from the branch you are currently on. For this reason, you will normally want to make sure you are in your master branch when creating a new one.

====CLI Commands====
<code>git branch xxx</code> where "xxx" is the new branch name. Note: If you already have a branch you are working on, use the command: <code>git checkout xxx</code>.

====Eclipse Commands====
#Left-click on the PHP project and select Team→Switch To→New Branch as shown below. [[File:Git-coders-tutorial-20121009-07.png|frame|none]]. The screen below will show. [[File:Git-coders-tutorial-20121009-08.png|frame|none]]
#Fill in the name of the new branch and click finish.

===Code and Commit to the Branch===
Finally, we are to the fun part! Here we are actually coding and testing our feature or bug fix. The normal workflow is as follows:
# Do some coding.
# Commit your work to your branch.
# Repeat until you are done.

Here are the commands to commit your work to your branch. Make sure you are in the right branch before committing! (Use <code>git status</code> to check.)

====CLI Commands====
* To commit all of the changes since the last commit: <code>git commit -m "My commit message" -a</code>
* To undo any file changes since the last commit: <code>git reset --hard</code>
* To remove any added files and folder since the last commit: <code>git clean -d -f</code>
* To change the last commit: <code>git commit --amend</code>

====Eclipse Commands====
* To commit all changes, right-click on project, select Team→Commit to show this window. [[File:Git-coders-tutorial-20121009-09.png|frame|none]]
* To undo any file changes since the last commit, select Team→Reset and check the Hard Reset Type as shown below. [[File:Git-coders-tutorial-20121009-10.png|frame|none]]
* To change the last commit, select Team→Commit and check the Amend Previous Commit button (as shown in the Commit Changes screenshot above).

===Push Branch to GitHub===
In the previous workflow, we created the branch and committed changes to our local repository. If we want others to be able to see the branch or to create a pull request, we need to push the branch to our personal repository on GitHub.

====CLI Command====
To push a branch to your personal GitHub repository: <code>git push origin xxx</code> (where "xxx" is the name of your branch).

===Submit Pull Request or Patch File===
There are two ways you can submit a proposed code change to the Joomla CMS project. One is to submit a pull request via GitHub, the other is to create a patch or diff file. In general, pull requests are preferred for very large changes, whereas both work fine for smaller changes.

====Create a Pull Request====
# Navigate to your personal GitHub repository.
# Select the branch that has the changes for the pull request as shown below. [[File:Git-coders-tutorial-20121009-11.png|frame|none]]
# Click the Pull Request button on the top of the screen. The screen will show as below. [[File:Git-coders-tutorial-20121009-12.png|frame|none]]
# The left side shows the base repository and base branch. This will normally be the master branch of the "joomla/joomla-cms" repository. The right side shows the head repository and branch. This will normally be your repository and the branch that has the desired code changes. If you like you can change the commit message and enter in a comment describing this pull request.
# You can review the pull request using the tabs across the top. Clicking the Commits tab shows the commit history for the branch, as shown below.[[File:Git-coders-tutorial-20121009-13.png|frame|none]]
# Clicking the Files Changed tab shows all of the changes made in this branch, as shown here. [[File:Git-coders-tutorial-20121009-14.png|frame|none]]
# When you are ready to submit the pull request, click the Send Pull Request button at the bottom right of the screen. GitHub will process the request and then display it as shown below. [[File:Git-coders-tutorial-20121009-15.png|frame|none]]
# At this point, you should update the Joomlacode tracker. For example, if this code is a fix for a Confirmed issue, you should change the issue status to Pending and add a comment with a link to the pull request (for example, <nowiki>https://github.com/joomla/joomla-cms/pull/494</nowiki>). Also, make sure there are good test instructions so people can test the proposed code.

====Create a Patch File====
It is not necessary to create a pull request to submit code changes to Joomla. Another alternative is to create a patch file. This can be done on your local system from the command line as follows:
# In your local system, change to the desired branch.
# Enter the command: <code>git diff master > my-new-patch.patch</code>
This will create a patch file in that same folder. (Note that you may want to have Git automatically ignore all patch files. See the section called Git Tips below.) Upload that file to the Joomlacode tracker and add a comment and change the issue status as needed.
To include changes to binary files in the diff add the <code>--binary</code> option to the command line as follows:
# Enter the command: <code>git diff --binary master > my-new-patch.patch</code>

Note that this method does not require you to push your local branches to GitHub.

== Keep Your Repositories Up to Date==
As discussed earlier, the main CMS repository on GitHub is being changed frequently. It is possible that one or more of these changes could conflict with (or otherwise affect) our work. For this reason, it is very important that we keep our repositories up to date. Otherwise, our patch files and pull requests may not work. As discussed earlier, the way we will do this is by keeping our master branch synchronized with the main CMS repository and then using that to update our working branches.

In this tutorial we are using the git merge command. The merge command merges the changes from a different branch into the current branch. Here we use the merge to merge changes from the master branch into our working branch. For example, say we created a branch (my-branch) on day 1. On day 2, someone does 5 commits to the master branch in the main CMS repository. Now, on day 3 we want to update our branch to be current with these 5 commits. The merge command tries to do this automatically. It looks to see what was changed in the master branch since our last merge and applies those same changes to our current branch ("my-branch"). This will work automatically unless we have made changes that conflict with changes made in the same files in the main repository. In that case, we need to resolve these conflicts before we can finish updating our branch.

To update a working branch with changes to the main CMS repository, follow these steps.
# Update your local master branch.
#* Make sure you are on the master branch in your local repository: <code>git checkout master</code>
#* Pull changes from the main CMS repository: <code>git pull upstream master</code>
#* Push those changes to your Github repository: <code>git push origin master</code>
# Now your local master branch is up to date. Next, change to your working branch: <code>git checkout my-branch</code>
# Make sure your remote repository "my-branch" is up to date with your local repository. Use the command: <code>git push origin my-branch</code>. If the remote repository was already up to date, no harm is done. You will just get a message saying it was already up to date.
# Finally, merge the new changes to the master branch with your working branch. The command is as follows: <code>git merge master</code>
# The system will work for a short time and then indicate whether or not the merge was successful. If you don't have any changes that conflict with changes from the main CMS repository, the merge will be successful. If one or more of your changes conflicts with the changes that were made in the main repository, any affected files will be flagged as being in conflict. See the Fixing Conflicts section below for more information about this.

You can also use Eclipse for the merge by changing to the working branch and selecting Team→Merge→. This will show the following screen. [[File:Git-coders-tutorial-20121027-01.png|frame|none]] Select Local->master as shown above and click Merge.

== Fixing Conflicts ==
A conflict occurs during a merge (or rebase) if the same file has been changed in the local branch and in the master branch in a way that conflicts. If this happens, the file is flagged as being in conflict and the merge process is suspended. To complete the process, you need to:
# Manually edit each of the flagged. You will see the changes from your branch and the changes from the main repository highlighted in the file. You need to figure out what should be in the file.
# Once you have edited each flagged file, enter the command <code>git add xxx</code> where "xxx" is the name of the flagged file.

Let's look at a simple example. Here we have added a line of code to a file in our branch and someone has added a different line to the same file in the master branch. When we do the merge command, we get the following message.

$ git merge master
Removing administrator/templates/hathor/html/mod_submenu/default.php
Auto-merging administrator/components/com_admin/script.php
CONFLICT (content): Merge conflict in administrator/components/com_admin/script
php
Automatic merge failed; fix conflicts and then commit the result.

So this tells us we have a conflict in the file <code>administrator/components/com_admin/script.php</code>. If we look at this file in our text editor, we see the following: [[File:Git-coders-tutorial-20121009-17.png|frame|none]] The line under "<<<<<<< HEAD" is from the master branch of the main repository. The line after the "=======" is from our working branch.

At this point, we need to correct the file and remove the "marker" lines. Then we do the command <code>git add administrator/components/com_admin/script.php</code> to tell Git that the conflict is resolved.

Finally, we do the command

<code>git commit -a</code>

to finish the merge. This commits all of the changes that were applied automatically by the merge as well as the changes we have done manually in fixing the conflicts.

If we want to abandon the merge instead of fixing the conflicts, we can use the following commands to reset our branch back to its state before the merge:

<code>git reset --hard</code>

<code>git clean -f -d</code>

===Using Eclipse For Conflicts===
Eclipse is very handy for resolving commits. When you do the command Team→Merge and there is a conflict, you get the following window. [[File:Git-coders-tutorial-20121027-02.png|frame|none]] You will also see a red square annotation in the PHP Explorer window next to each file with a conflict.

To see all of the files in conflict you can use the Merge Tool. Right click on the PHP project and select {{rarr|Team,Merge Tool}}. You will see the following option. [[File:Git-coders-tutorial-20121009-20.png|frame|none]]

This gives you the option of having Git put in the changes from both sources in the file or letting you compare the changes side by side. If you select Use HEAD version you get a file compare similar to the following. [[File:Git-coders-tutorial-20121009-21.png|frame|none]]

The left shows the change from the master branch, and the right shows the change from your working branch. At this point, you can either edit the file in the left side (for example, by pulling in the change from the right side) or you can just manually edit the file in conflict.

Once the file has been fixed, select the file (either by right-clicking in the PHP Explorer view or in the editor) and select {{rarr|Team,Add}} to Index as shown below. [[File:Git-coders-tutorial-20121009-22.png|frame|none]]When you do this, the red square annotation will disappear.

Once all the conflicts are resolved, you can finish the merge by right-clicking on the project and selecting {{rarr|Team,Commit}}. The normal commit screen will show as follows. [[File:Git-coders-tutorial-20121027-03.png|frame|none]] Notice that the files that were in conflict are automatically added to the commit message. Edit the commit message as desired and click the Commit button. At this point, the merge is complete.

== Saving Your User Name and Password ==
When you push changes to GitHub, it must authenticate you based on your GitHub user name and password. Normally, the system will simply prompt you for your user name and password each time you do a push.

There are a number of ways you can save your credentials so you don't have to enter them each time. One very simple method is to use the git "store" feature.

''IMPORTANT NOTE: This feature stores your password in plain text on your local computer. If this is not acceptable, do not use this method.''

If it is OK to store your credentials on your PC, at the command line enter the command: <code>git config --global credential.helper store</code> This tells Git to store your credentials in a file called .git-credentials in your home folder ("for example, C:\users\user-name").

The next time you do a push and enter your credentials, they will be stored in that file. After that, you will not need to enter them. Git will use them automatically.

If you want to change your password, simple delete the file and then change your password on GitHub. The next time you enter your credentials, the new password will be saved.

== Git Tips ==

=== Ignoring Files ===
Sometimes you don't want to track all the files in a folder, specially some system files that the operating system generates. One way to have Git ignore files is to use the ''.gitignore'' file.

If you create a file in your repository named ''.gitignore'', Git uses it to determine which files and directories to ignore, before you make a commit.

A ''.gitignore'' file should be committed into your repository, in order to share the ignore rules with any other users that clone the repository.

Read more about ''.gitignore'' at:
* https://git-scm.com/docs/gitignore
* https://docs.github.com/en/get-started/getting-started-with-git/ignoring-files

Here is an example of a file.

# OSX
.DS_Store
._*
.Spotlight-V100
.Trashes

# Windows
Thumbs.db
Desktop.ini

# PHPStorm
.idea/

# Sublime Text
*.sublime*
sftp-config.json

# Eclipse
.buildpath
.project
.settings

# Netbeans (custom)
.netbeans/*
/nbproject/*

# Temp files
*.tmp
*.bak
*.swp
*~.nib
*~

# Phing build script
build.properties

# Packages #
*.zip
*.tar.*

# Composer
composer.lock
/vendor

# Test related files
/tests/system/servers/configdef.php
/tests/system/webdriver/tests/logs/
/tests/acceptance.suite.yml
codecept.phar

# Never ignore
!.gitignore
!index.html
!index.php

As you can see from the example, we can exclude specific folders and file names.

Once you have this file created, Git will ignore any of these files.

[[Category:Bug Squad]]
[[Category:Development]]
[[Category:GitHub]]

Testing Joomla! patches QuickReferenceGuide

2023-07-10T14:40:38Z

Cmb: Corrected a URL. Other markup changes.

<noinclude><languages /></noinclude>

<translate>

The [[S:MyLanguage/Testing Joomla! patches|Testing Joomla! patches]] page describes the patch testing procedure. This document is a Quick Reference Guide with all necessary steps.
</translate>

<translate>
=== Joomla Issue Tracker === 
* https://issues.joomla.org/
* Login with Github account -> no account? https://github.com/
* Status: {{rarr|New,Confirmed,Pending,Ready to Commit (RTC),Closed}}
** '''New''' - Just reported
** '''Confirmed''' - Someone reproduced and confirmed error
** '''Pending''' - Patch available (“PR” - pull request); needs two successful tests
** '''Ready To Commit''' - To be added to Joomla source code
** Needs Review - Need experienced developer to review the issue
** Information Required - Need more info from the person who reported the issue
</translate>

<translate>
===Testing Bugs, Reports, Patches=== 
* Have working local web server environment (XAMPP, MAMP ect)
* Get Joomla “staging” from: https://github.com/joomla/joomla-cms
** Download, unzip to folder
** or: git clone https://github.com/joomla/joomla-cms.git
* Install Joomla at local web server
** Install with: Test English (GB) sample data
** Do '''not remove''' /installation/ folder!
* Joomla Patch Tester Component
** Download from: https://github.com/joomla-extensions/patchtester/releases
** Installation via Extensions > Install
** Add your own Github account details under Options (Username + Password)
* Testing found issues
** Find issue in Joomla Issue Tracker (useful filters: status, category, tests, easy)
** Reproduce bug (can't reproduce bug? → report)
** Install Patch in Joomla Patch Tester Component. patch: [#ID of patch – Some descriptive title for problem/patch]
** Test if bug is solved & report findings (use @test for successful test)
** Remove Patch (“revert patch”)
</translate>

<translate>
===Report Bug=== 
* Search in Issue Tracker if issue has been reported already
* Create new item [New Item]
** Title: use descriptive title!
** Description:
*** Steps to reproduce the issue
*** Expected result & actual result
*** System information (as much as possible). e.g. your PHP information, browser + version
*** Additional comments
** Priority: default: Medium
** Build: 3.4.x-dev (at this moment)
** Categories: select the most appropriate categories
</translate>

<translate>
===Create Patch=== 
Patch = text file that describes changes in source code.
</translate>

<translate>

Methods:
* Use IDE (like Netbeans, PHPStorm)
** Improve Joomla code in editor & create ''.diff'' patch
* Use Github: https://github.com/joomla/joomla-cms
** Navigate to page with code
** Click “pencil” icon: “Clicking this button will fork this project so you can edit the file”
** Add improvements:
*** Make changes in code under “Edit file”
*** Add Commit Summary under Propose file change (50 characters or less)
*** Use optional extended description (in case 50 characters was not enough)
** Save & choose Pull Request
* Use Command line “git” (for experienced users)
</translate>

<translate>
===More information=== 
* Component Patchtester: [[S:MyLanguage/Component Patchtester for Testers|Component Patchtester for Testers]]
* Testing Joomla! patches: [[S:MyLanguage/Testing Joomla! patches|Testing Joomla! patches]]
* Testing Checklist: [[S:MyLanguage/Testing Checklists|Testing Checklists]]
* Filing bugs and issues: [[S:MyLanguage/Filing bugs and issues|Filing bugs and issues]]
* Bug Squad: [[S:MyLanguage/Bug Squad|Bug Squad]]
* Bug Tracking Process: [[S:MyLanguage/Bug Tracking Process|Bug Tracking Process]]
</translate>

<noinclude>
[[Category:Bug Tracker{{#translation:}}]]
[[Category:Bug Squad{{#translation:}}]]
[[Category:Tutorials{{#translation:}}]]
</noinclude>

How to use JDate

2023-07-09T20:08:02Z

Cmb: Replaced deprecated 'source' tags with 'syntaxhighlight' tags. Other markup changes.

<noinclude><languages /></noinclude>

<translate>
== Introduction == 
Joomla's Date class is a helper class, extended from PHP's DateTime class, which allows developers to handle date formatting more efficiently. The class allows developers to format dates for readable strings, MySQL interaction, UNIX timestamp calculation, and also provides helper methods for working in different time zones.
</translate>

<translate>

===Regarding the ''JDate'' Class Name===
This page has been updated to utilise namespaced class names. ''JDate'', ''JApplication'' and other similarly-named classes you will see throughout the Joomla documentation are actually class aliases, maintained for legacy reasons. It is recommended to use namespaced access to Joomla classes, which will improve your development experience by providing better code hints and checks in your editor, leading to fewer errors.


You can view the full list of aliased classes [https://github.com/joomla/joomla-cms/blob/3.10-dev/libraries/classmap.php in this file inside the Joomla code base].
</translate>

<translate>
== Creating a Date Instance == 
All of the date helper methods require an instance of the Date class. To begin, you must create one. A Date object may be created in two ways. One is the typical native method of simply creating a new instance:
</translate>

<syntaxhighlight lang="php">
use Joomla\CMS\Date\Date;

$date = new Date(); // Creates a new Date object equal to the current time.
</syntaxhighlight>

<translate>

You may also create an instance using the static method defined in Date:
</translate>

<syntaxhighlight lang="php">
use Joomla\CMS\Date\Date;

$date = Date::getInstance(); // Alias of 'new Date();'
</syntaxhighlight>

<translate>

There is no difference between these methods, as Date::getInstance simply creates a new instance of Date exactly like the first method shown.


Alternatively, you may also retrieve the current date (as a Date object) from the Application object, by using:
</translate>
<syntaxhighlight lang="php">
use Joomla\CMS\Factory;

$date = Factory::getDate();
</syntaxhighlight>

<translate>
== Arguments == 


The Date constructor (and ''getInstance'' static method) accepts two optional parameters: A date string to format and a timezone. Not passing a date string will create a Date object with the current date and time, while not passing a timezone will allow the Date object to use the default timezone set.
</translate>

<translate>

The first argument, if used, should be a string that can be parsed using PHP's native DateTime constructor. For example:
</translate>
<syntaxhighlight lang="php">
use Joomla\CMS\Date\Date;

$currentTime = new Date('now'); // Current date and time
$tomorrowTime = new Date('now +1 day'); // Current date and time, + 1 day.
$plus1MonthTime = new Date('now +1 month'); // Current date and time, + 1 month.
$plus1YearTime = new Date('now +1 year'); // Current date and time, + 1 year.
$plus1YearAnd1MonthTime = new Date('now +1 year +1 month'); // Current date and time, + 1 year and 1 month.
$plusTimeToTime = new Date('now +1 hour +30 minutes +3 seconds'); // Current date and time, + 1 hour, 30 minutes and 3 seconds
$plusTimeToTime = new Date('now -1 hour +30 minutes +3 seconds'); // Current date and time, + 1 hour, 30 minutes and 3 seconds
$combinedTimeToTime = new Date('now -1 hour -30 minutes 23 seconds'); // Current date and time, - 1 hour, +30 minutes and +23 seconds

$date = new Date('2012-12-1 15:20:00'); // 3:20 PM, December 1st, 2012
</syntaxhighlight>

<translate>

A Unix timestamp (in seconds) can also be passed as the first argument, in which case it will be internally uplifted into a date. If a timezone has been specified as the second argument to the constructor, it will be converted to that timezone.
</translate>

<translate>
== Outputting Dates == 


One note of caution when outputting Date objects in a user context: do not simply print them to the screen. The Date object's toString() method simply calls its parent's format() method, without consideration for time zones or localized date formatting. This will not result in a good user experience, and will lead to inconsistencies between the formatting in your extension, and elsewhere in Joomla. Instead, you should always output Dates using the methods shown below.</translate>

<translate>
=== Common Date Formats === 


A number of date formats are predefined in Joomla as part of the base language packs. This is beneficial because it means date formats can be easily internationalised. A sample of the available format strings is below, from the en-GB language pack. It is highly recommended to utilise these formatting strings when outputting dates, so that your dates will be automatically re-formatted according to a user's locale. They can be retrieved in the same way as any language string. (See below for examples.)
</translate>

<syntaxhighlight lang="ini">
DATE_FORMAT_LC="l, d F Y"
DATE_FORMAT_LC1="l, d F Y"
DATE_FORMAT_LC2="l, d F Y H:i"
DATE_FORMAT_LC3="d F Y"
DATE_FORMAT_LC4="Y-m-d"
DATE_FORMAT_LC5="Y-m-d H:i"
DATE_FORMAT_LC6="Y-m-d H:i:s"
DATE_FORMAT_JS1="y-m-d"
DATE_FORMAT_CALENDAR_DATE="%Y-%m-%d"
DATE_FORMAT_CALENDAR_DATETIME="%Y-%m-%d %H:%M:%S"
DATE_FORMAT_FILTER_DATE="Y-m-d"
DATE_FORMAT_FILTER_DATETIME="Y-m-d H:i:s"
</syntaxhighlight>

<translate>
=== The HtmlHelper Method (Recommended) === 


As with many common output items, the HtmlHelper class is here to... help! HtmlHelper's date() method will take any date-time string that the Date constructor would accept, along with a formatting string, and output the date appropriate for the current user's timezone settings. As such, this is the recommended method for outputting dates for the user.
</translate>

<syntaxhighlight lang="php">
use Joomla\CMS\HTML\HTMLHelper;
use Joomla\CMS\Language\Text;

$myDateString = '2012-12-1 15:20:00';
echo HtmlHelper::date($myDateString, Text::_('DATE_FORMAT_FILTER_DATETIME'));
</syntaxhighlight>

<translate>
=== The Date Object's format() Method === 


Another option is to format the Date manually. If this method is used, you will have to also manually retrieve and set the user's timezone. This method is more useful for formatting dates outside of the user interface, such as in system logs or API calls.
</translate>

<syntaxhighlight lang="php">
use Joomla\CMS\Language\Text;
use Joomla\CMS\Date\Date;
use Joomla\CMS\Factory;

$myDateString = '2012-12-1 15:20:00';
$timezone = Factory::getUser()->getTimezone();

$date = new Date($myDateString);
$date->setTimezone($timezone);
echo $date->format(Text::_('DATE_FORMAT_FILTER_DATETIME'));
</syntaxhighlight>

<translate>
== Other Useful Code Examples == 
</translate>

<translate>
=== Quickly Outputting the Current Time === 
</translate>

<translate>

There are two easy ways of doing this.
# The HtmlHelper's date() method, if no date value is provided, will default to the current time.
# Factory::getDate() gets the current date as a Date object, which we can then format.
</translate>

<syntaxhighlight lang="php">
use Joomla\CMS\Factory;
use Joomla\CMS\HTML\HTMLHelper;
use Joomla\CMS\Language\Text;

// These two are functionally equivalent
echo HtmlHelper::date('now', Text::_('DATE_FORMAT_FILTER_DATETIME'));

$timezone = Factory::getUser()->getTimezone();
echo Factory::getDate()->setTimezone($timezone)->format(Text::_('DATE_FORMAT_FILTER_DATETIME'));
</syntaxhighlight>

<translate>
=== Adding and Subtracting from Dates === 


Because the Joomla Date object extends the PHP DateTime object, it provides methods for adding and subtracting from dates. The easiest of these methods to use is the modify() method, which accepts any relative modification string that the PHP [https://www.php.net/manual/en/function.strtotime.php strtotime()] method would accept. For example:
</translate>

<syntaxhighlight lang="php">
use Joomla\CMS\Date\Date;

$date = new Date('2012-12-1 15:20:00');
$date->modify('+1 year');
echo $date->toSQL(); // 2013-12-01 15:20:00
</syntaxhighlight>

<translate>

There are also separate add() and sub() methods, for adding or subtracting time from a date object respectively. These accept PHP-standard [https://www.php.net/manual/en/class.dateinterval.php DateInterval] objects:
</translate>

<syntaxhighlight lang="php">
use Joomla\CMS\Date\Date;

$interval = new \DateInterval('P1Y1D'); // Interval represents 1 year and 1 day

$date1 = new Date('2012-12-1 15:20:00');
$date1->add($interval);
echo $date1->toSQL(); // 2013-12-02 15:20:00

$date2 = new Date('2012-12-1 15:20:00');
$date2->sub($interval);
echo $date2->toSQL(); // 2011-11-30 15:20:00
</syntaxhighlight>

<translate>
=== Outputting Dates in ISO 8601 Format === 
</translate>

<syntaxhighlight lang="php">
$date = new Date('2012-12-1 15:20:00');
$date->toISO8601(); // 20121201T152000Z
</syntaxhighlight>

<translate>
=== Outputting Dates in RFC 822 Format === 
</translate>

<syntaxhighlight lang="php">
$date = new Date('2012-12-1 15:20:00');
$date->toRFC822(); // Sat, 01 Dec 2012 15:20:00 +0000
</syntaxhighlight>

<translate>
=== Outputting Dates in SQL Date-Time Format === 
</translate>

<syntaxhighlight lang="php">
$date = new Date('20121201T152000Z');
$date->toSQL(); // 2012-12-01 15:20:00
</syntaxhighlight>

<translate>
=== Outputting Dates as Unix Timestamps === 


A Unix timestamp is expressed as the number of seconds that have passed since the Unix Epoch (the first second of Jan 1st 1970).
</translate>

<syntaxhighlight lang="php">
$date = new Date('20121201T152000Z');
$date->toUnix(); // 1354375200
</syntaxhighlight>

<translate>

[[Category:Development]]
</translate>

Chunk:Configuring Eclipse IDE for PHP development - Configuration

2023-07-05T22:31:14Z

Cmb: /* Installing More Extensions */ Corrected list markup.

== Configuration ==

=== Installing More Extensions ===

For your Eclipse IDE you will need to install more extensions for PHP development and other tools to help you in your project development journey. Follow these steps and instructions:

* In Eclipse, go to: ''Toolbar → Help → install new software''.
* You are now on the ''Install'' window. Click the drop-down list ''Work with'' and set it to ''--All Available Sites--''.
* In the list, expand the nodes and find the following packages to install:
** Go to ''Web, XML, and Java EE Development'' and select
*** PHP Development Tools (PDT) SDK Feature
*** JavaScript Development Tools
*** Eclipse Web Developer Tools
** Go to ''General Purpose Tools'' and select
*** Remote System Explorer End-User Runtime

* Press ''Next →'' and follow the installation wizard. Restart Eclipse when prompted.
* In Eclipse, go to: ''Toolbar → Help → Install new software''.
* Press the ''Add'' button and add this new repository, name it ''xtext plugin''.

https://download.eclipse.org/modeling/tmf/xtext/updates/composite/releases/

* Press the ''Add'' button and add this new repository. Name it ''LESS plugin''.

http://www.normalesup.org/~simonet/soft/ow/update/

* Press ''OK'' and wait until Eclipse fetches all the new elements.
* In the selection box next to the ''Add'' button, select the ''LESS plugin...'' repository.
* On the list below find the ''LESS'' option and check it.

* Press ''Next →'' and follow the installation wizard. Restart Eclipse when prompted.

Those are all the extensions to install for now. They should be enough to do local and remote PHP development. Nonetheless you can experiment and try all the extensions you want.

=== Configuring the Perspectives and Views ===

In this case we need to configure Eclipse for PHP development. Add the following perspectives:

* In the Toolbar, go to: ''Window → Perspective → Open Perspective → Other → Debug''
* In the Toolbar, go to: ''Window → Perspective → Open Perspective → Other → PHP''
* Switch to the ''PHP perspective''.
* In the Toolbar, go to: ''Window → Show View → Other → Remote Systems''
* Drag the view from the tab and drop it next to the ''PHP Explorer'' view.

Now you can explore local and remote PHP projects. The configuration of these tools are explained in [[Setting_up_your_workstation_for_PHP_development | this]] series of articles.

=== Configuring the editors ===

These are some of the configuration you can do to your editors to improve the user experience:

==== Display Whitespace ====

Some people like to see the whitespace represented in the editor. To do so:

* In the Toolbar, go to: ''Window → Preferences → General → Editors → Text Editors''
* Check the ''Show whitespace characters'' box.
* Select the ''Apply and Close'' button.

==== Colors ====

To highlight some the parts of the code with stronger colors, follow these steps:

* In the Toolbar, go to: ''Window → Preferences → General → Editors → Text editors → Annotations''
** On the list find ''JavaScript Occurrences'' and set the color value to ''#FFFF5A''.
** On the list find ''Matching Tags'' and set the color value to ''#FFFF5A''.
** On the list find ''PHP elements 'read' occurrences'' and set the color value to ''#FFFF5A''.

* In the Toolbar, go to: ''Window → Preferences → General → Editors → Structured Text Editor''
** Find the list ''Appearance color options''.
** On the list find ''Matching brackets highlight'' and set the color value to ''#0000FF''.

* In the Toolbar, go to: ''Window → Preferences → JavaScript → Editor''
** Find the list ''Appearance color option''.
** On the list find ''Matching brackets highlight'' and set the color value to ''#0000FF''.

* In the Toolbar, go to: ''Window → Preferences → JavaScript → Editor → Syntax Coloring''
** Find the list ''Element''.
** On the list find ''JavaScript → Functions''. Enable the option and set the color value to "#1E90FF''.
** On the list find ''JavaScript → Function declarations'' Enable the option and set the color value to ''#1E90FF''.
** On the list find ''JavaScript → Local variable declaration''. Enable the option and set the color value to ''#A52A2A''.
** On the list find ''JavaScript → Local variable references''. Enable the option and set the color value to ''#A52A2A''.
** On the list find ''JavaScript → Parameter variables''. Enable the option and set the color value to ''#A52A2A''.

* In the Toolbar, go to: ''Window → Preferences → PHP → Editor → Syntax Coloring''
** Find the list ''Syntax Element''.
** On the list find ''Classes'' and set the color value to ''#1E90FF''.
** On the list find ''Functions'' and set the color value to ''#1E90FF''.
** On the list find ''Methods'' and set the color value to ''#1E90FF''.
** On the list find ''Variable'' and set the color value to ''#A52A2A''.

==== Spell Checking ====

If you want Eclipse to check the grammar of your text, enable this option.

* In the Toolbar, go to: ''Window → Preferences → General → Editors → Text Editors → Spelling''
** Find and enable ''Enable spell checking''.

==== Code Folding ====

Code folding is a nice feature of some editors. It allow you to fold the code in certain data structures such as functions, classes, conditionals and iterators. We are going to fold all except PHP classes to be able to check and study PHP files quickly.

* In the Toolbar, go to: ''Window → Preferences → General → Editors → Structured Text Editors''
** Select the ''Appearance'' tab.
** Find and enable ''Enable folding''.

* In the Toolbar, go to: ''Window → Preferences → JavaScript → Editor → Folding''
** Find and enable ''Enable folding''.
** Find and enable ''Comments''.
** Find and enable ''Header Comments''.
** Find and enable ''Members''.

* In the Toolbar, go to: ''Window → Preferences → PHP → Editor → Code Folding''
** Find and enable ''Enable folding''.
** Find and enable ''Functions''.
** Find and enable ''PHPDoc''.
** Find and enable ''Header PHPDoc''.

==== Code Cleaning ====

Eclipse provides some nice utilities to automatically remove empty lines, delete unnecessary trailing spaces, format the code and more. To activate these features:

* In the Toolbar, go to: ''Window → Preferences → PHP → Editor → Save Actions''
** Find and enable ''Remove trailing whitespace'' and also select ''All lines''.

* In the Toolbar, go to: ''Window → Preferences → JavaScript → Editor → Save Actions''
** Find and enable ''Perform the selected actions on save''.
** Find and enable ''Additional actions''.
** Press the ''Configure...'' button.
** Select the tab ''Code Organizing''.
** Find and enable ''Remove trailing whitespace''.
** Find and select ''All lines''.
** Press ''OK'' to continue.

* When you are done, press ''Apply and Close'' to save and close the Preferences window.

Configuring Eclipse IDE for PHP development/Linux

2023-07-05T22:26:05Z

Cmb: Some markup changes.

{{RightTOC}}

These instructions should work fine on any Debian-based distribution such as Debian, Ubuntu, Linux Mint, Xubuntu and Kubuntu.

== Installation ==
There are several ways to download and install the Eclipse IDE to your Linux box. You can do it automatically from the comfort of your software center or using the Linux terminal with few commands or manually downloading and installing the Eclipse IDE from the Eclipse project website or other alternative download sites.

=== Method 1: From a Linux Repository ===
'''NOTE''' This method is recommended because you will automate the installation process and get automatic security patches and bug fix updates when the software is installed from the repositories.

==== Option 1: Terminal ====
*Open your terminal and type
''sudo apt-get install eclipse''
*Wait for the installation process to finish.
*If everything went fine, the Eclipse IDE will be available in the software menu.

==== Option 2: Software Center ====
*Open the software center that comes with your distribution.
*Type in the search box ''Eclipse IDE''.
*Select ''Eclipse IDE'' in the search result list.
*Click on the ''install'' button.
*Wait for the installation process to finish.
*If everything went fine, the Eclipse IDE will be available in the software menu.

=== Method 2: From a Downloaded Copy ===
'''NOTE''' For manual download and installation, you must have Java runtime previously installed or Eclipse IDE will not run.

To install Java runtime on your Linux box, open a terminal and type following command and wait until the installation finishes:

''sudo apt-get install sun-java6''

You can also install Java from your software center. Just type ''openjdk java 6'' and install the package.

To get a copy of Eclipse IDE, follow these steps:

*Go to: [https://www.eclipse.org/downloads/ Eclipse download page].
*Download ''Eclipse Classic'' 32 or 64 bits according to your current OS version.
*Unpack the downloaded file to any location that you want. For example: the Downloads folder or the Desktop folder.
*Open the Eclipse folder an find an executable file called ''eclipse''.
*Do a right click on the file then: ''properties → permissions'' and check ''Allow executing file as a program''.
*To execute the Eclipse IDE, you can do a double click on the executable file or run it from terminal. For example:
<syntaxhighlight>
cd ~/Downloads/eclipse/
eclipse
</syntaxhighlight>

'''NOTE''' At the [https://www.eclipse.org/downloads/ Eclipse download page] you can see many versions of Eclipse IDE. All of them are basically the same Eclipse with several extensions pre-installed to do specific tasks. By default, Eclipse IDE comes with all the tools needed to develop Java projects but you can install more extensions to develop in other languages. Go to [https://www.eclipse.org/downloads/packages/compare Compare Eclipse Packages] to see a complete list of all the extensions included on each Eclipse Package build. You can try one of these pre-build packages specifically created for PHP development. Some of them are official releases from the Eclipse Website and others are independent projects.

*[https://www.eclipse.org/pdt/#download Eclipse PDT (PHP Development Tools)]
*[http://www.easyeclipse.org/site/distributions/php.html EasyEclipse for PHP]
*[http://www.phpeclipse.com/ PhpEclipse]

{{chunk:Configuring Eclipse IDE for PHP development - Understanding the interface}}

== Understanding the Folder Structure ==
When you execute Eclipse for the first time, it will ask you to create a ''workspace''. The workspace is a folder where Eclipse IDE will store two things: all your custom configurations and all or some of your projects.

All your projects will be separated into folders inside the workspace folder like this:
<syntaxhighlight>
/home/youruser/workspace/project-a
/home/youruser/workspace/project-b
/home/youruser/workspace/joomla_component
/home/youruser/workspace/joomla-test-site
</syntaxhighlight>

You can have more than one workspace. Each of them will contain its own custom configurations and will not affect the information of other workspaces. For example, you can have a workspace located at ''/home/youruser/java-workspace/'' dedicated to contain Java projects and a separate workspace such as ''/home/youruser/php-workspace/'' dedicated to PHP development.

As you can see, your workspace folder could be in any valid folder location. For the purposes of PHP development and our convenience, we can set our workspace folder to the same location where our Web server stores its Web files. For example, ''/home/youruser/lamp/public_html/''. This way the Eclipse IDE and our Web server will use the same location for our Web files.

Is important to note that you have the additional option to place your project files outside the workspace locations if you wish. This way Eclipse gives you an additional flexibility in certain cases. For example, let's say we have a workspace located at ''/home/youruser/workspace/'' which contains several random projects, but our server stores its files in a different location at ''/home/youruser/lamp/public_html/''. Of course we want to put our PHP project there so we can edit the files and serve the pages at the same time. Simply create a folder like this: ''/home/youruser/lamp/public_html/my-joomla-project''. Then create a new PHP project and manually specify the path of your new project.

What is the difference of projects that are inside and outside the workspace folder? The only noticeable difference is at the moment of creating new projects, When you create a project inside the workspace, Eclipse IDE will automatically create a folder for that project with the same name as the project itself. On the other hand, if the project is outside the workspace location, you can set a random name for the project and then you have to set the path of the project manually regardless of the destination folder name.

A final note about the behavior of creating new project is that the Eclipse IDE will not let you link an external project that is actually inside your current workspace location. Also you can manually create any folder inside your Eclipse IDE workspace location but that does not mean Eclipse will recognize such folders as a project at all. When you create the new project from the Eclipse IDE that shares the name of an existing folder that already exists in your workspace, Eclipse will automatically link all its contents to your new project.

When you create a new workspace, Eclipse will automatically create a hidden folder called ''.metadata''. It will contain all your custom global configurations about the editors, perspectives and views. This configuration will be inherited by any new project by default. If you wish, you can override part of the global configuration with custom configurations values specific for each project.

When you create a new project, Eclipse will create these hidden files and folders inside your new project folder:
<syntaxhighlight>
.project
.buildpath
.settings
</syntaxhighlight>
These files and folders contain information about your custom project configurations and building information that will let Eclipse show tree views of dependencies and classes among many other things.

{{Chunk:Configuring Eclipse IDE for PHP development - Configuration}}

[[Category:Development]]

== Fine Tuning ==
=== Increase RAM Usage ===
By default, Eclipse gets some configuration information to limit the amount of RAM. This configuration works fine for most users but if you have 2 gigabytes or more of RAM, consider setting this value to improve Eclipse performance.

First locate the ''eclipse.ini'' file that contains some Eclipse configurations.

*If you downloaded Eclipse IDE manually from Internet, the ''eclipse.ini'' file is just inside the unpacked folder.
*If you installed Eclipse via terminal or software center, the location of the file is ''/etc/eclipse.ini''.
*In some Linux versions, the file can be found at ''/usr/share/eclipse/eclipse.ini''.

'''NOTE''' If you found a config file at ''/etc/eclipse.ini'', don't edit the file at ''/usr/share/eclipse/eclipse.ini''.

This is the content of the original ''eclipse.ini'' file:

<syntaxhighlight>
-startup
plugins/org.eclipse.equinox.launcher_1.2.0.dist.jar
--launcher.library
plugins/org.eclipse.equinox.launcher.gtk.linux.x86_64_1.1.100.dist
-showsplash
org.eclipse.platform
--launcher.XXMaxPermSize
256m
--launcher.defaultAction
openFile
-vmargs
-Xms40m
-Xmx384m
-Dorg.eclipse.equinox.p2.reconciler.dropins.directory=/usr/share/eclipse/dropins
</syntaxhighlight>

To see the full reference about these parameters, visit [https://help.eclipse.org/oxygen/index.jsp?topic=%2Forg.eclipse.platform.doc.isv%2Freference%2Fmisc%2Fruntime-options.html].

Change the following values to increase the amount of RAM used by Eclipse.

<syntaxhighlight>
-startup
plugins/org.eclipse.equinox.launcher_1.2.0.dist.jar
--launcher.library
plugins/org.eclipse.equinox.launcher.gtk.linux.x86_64_1.1.100.dist
-showsplash
org.eclipse.platform
--launcher.XXMaxPermSize
512m
--launcher.defaultAction
openFile
-vmargs
-Xms512m
-Xmx512m
-Dorg.eclipse.equinox.p2.reconciler.dropins.directory=/usr/share/eclipse/dropins
</syntaxhighlight>

If you have a lot of RAM you can try these other configurations.

<syntaxhighlight>
-startup
plugins/org.eclipse.equinox.launcher_1.2.0.dist.jar
--launcher.library
plugins/org.eclipse.equinox.launcher.gtk.linux.x86_64_1.1.100.dist
-showsplash
org.eclipse.platform
--launcher.XXMaxPermSize
1024m
--launcher.defaultAction
openFile
-vmargs
-Xms1024m
-Xmx1024m
-Dorg.eclipse.equinox.p2.reconciler.dropins.directory=/usr/share/eclipse/dropins
</syntaxhighlight>

[[Category:Development]]
[[Category:IDE (Integrated development environment)]]

Joomla CodeSniffer

2023-07-05T20:57:40Z

Cmb: Removed dead URLs to screenshots.

<noinclude><languages /></noinclude>

<translate>
== A Nose For Joomla == 
</translate>
<translate> This is a custom coding standard for the PHP CodeSniffer that attempts to codify and enforce the Joomla coding standards. This article covers how to set the automatic code style checker. It consists of three steps:</translate>
<translate>
# Install PHP CodeSniffer (phpcs).
# Clone the Joomla Code Style (for use with for phpcs).
# Configure your IDE to work with PHP CodeSniffer and Joomla Code Style.</translate>

[[File:CodeSnifferInAction.jpg|center|thumb|300px|PHP Code Sniffer in action]]

<translate>
==Why?== 
</translate>
<translate> *Coherent and consistent coding practice makes the files look more professional. Conflicting styles in the same project (or worse, the same file) not only look sloppy, they encourage further sloppiness.</translate>
<translate> *When all code complies with the same standard, bad code is easier for everyone to spot.</translate>
<translate> *It makes it easier for someone new to a particular file in the project to find and fix errors or extend functionality.</translate>
<translate> *If there is no consistent standard maintained, sometimes developers will reformat the code to suit themselves. This causes a wide range of changes in the code repository. If there is a later problem, a significant change could be lost in the chaff produced by a diff.</translate>

<translate>
==Installation of PHP Code Sniffer (phpcs)== 
</translate>
<translate>
===Composer=== 
</translate>
<translate> PHP Code Sniffer is available via Composer. It can be installed system-wide with the following command:</translate><br />
''composer global require --dev squizlabs/php_codesniffer "~3.5"''
<translate>

On '''Linux''' PHP Code Sniffer (phpcs) will be installed under your user folder:</translate>
* <translate> Symbolic Link:</translate> ''~/.composer/vendor/bin/phpcs''
* <translate> The file:</translate> ''~/.composer/vendor/squizlabs/php_codesniffer/scripts/phpcs''
<translate> To create that symbolic link, use on the command line: </translate>
''$ sudo ln -s ~/.config/composer/vendor/squizlabs/php_codesniffer/scripts /usr/bin/phpcs''

<translate> or (for example OpenSuse)</translate>
* <translate> Symbolic Link:</translate> ''~/.config/composer/vendor/bin/phpcs''
* <translate> The file:</translate> ''~/.config/composer/vendor/squizlabs/php_codesniffer/scripts/phpcs''

<translate> On '''Windows''' PHP Code Sniffer (phpcs) will be installed under your user folder:</translate>
* <translate> Symbolic Link:</translate> ''c:\Users\Username\AppData\Roaming\Composer\vendor\bin\phpcs''
* <translate> The file:</translate> ''c:\Users\Username\AppData\Roaming\Composer\vendor\squizlabs\php_codesniffer\scripts\phpcs''

<translate>
=== Add composer bin directory to your $PATH === 
</translate>
<translate>

In order to execute PHP Code sniffer from anywhere on Linux or Mac command line you have to add ''.composer/vendor/bin'' to your $PATH variable.</translate>
<translate>

To do this persistent edit your shells start file, like your .profile or .bash_profile file depending which shell you are using (echo $SHELL shows you which one you are using).</translate>

<translate> Add the following line to the file:</translate>
''export PATH=$PATH:~/.composer/vendor/bin''

<translate> Alternatively you can also create a symbolic link in the bin folder:</translate>
''ln -s ~/.composer/vendor/bin/phpcs /usr/local/bin/phpcs''

<translate>
==Install Joomla Coding Standards== 
</translate>
<translate> In order to have PHP Code Sniffer (phpcs) sniffing your Joomla projects for the right code style, you have to install the Joomla Coding Standards.</translate>

<translate> Using composer we can execute:</translate>
''composer global require --dev joomla/coding-standards "~3.0@alpha"''

<translate> Notice that it says ''@alpha'', that is because the coding standard is still in alpha state and we need to allow the installation of alpha status code. If we do not include the @alpha the coding standards will not install and throw this error.</translate>

<pre>
Your requirements could not be resolved to an installable set of packages.

Problem 1
- The requested package joomla/coding-standards ~3.0 is satisfiable by joomla/coding-standards[3.0.0-alpha, 3.0.0-alpha2, 3.x-dev] but these conflict with your requirements or minimum-stability.
</pre>

<translate> Once the installation is done the coding standard will be installed in the global composer folder. The location of this folder depends on your operating system. Some popular locations are:</translate>

'''Mac / Linux'''

''~/.composer/vendor/joomla/coding-standards/''
and
''~/.config/composer/vendor/joomla/coding-standards/''

'''Windows'''

''c:\Users\Username\AppData\Roaming\Composer\vendor\joomla\coding-standards\''

<translate> This is using Composer on Windows.</translate>

<translate> If you can't find it in any of the above folders, note that the folder you are looking for ends with ''\joomla\coding-standards\''.</translate>
<translate>

Finally we need to tell Code Sniffer that the Joomla coding standards exist.</translate>

<translate>
'''Install Joomla Coding Standards'''
# Check if certain paths are already set by running ''phpcs --config-show''
# You can get an answer that looks like this: ''installed_paths: /path/to/installation''
# In step 2, if you see the '''installed_paths''' you need to copy that
# Set the Joomla Coding Standards path in phpcs by executing ''phpcs --config-set installed_paths /Users/user/.composer/vendor/joomla/coding-standards''. If you copied any paths in step 2, include them here as well by separating them with a comma. The command looks like ''phpcs --config-set installed_paths [/to/path1],[/to/path2],[/Users/user/.composer/vendor/joomla/coding-standards]''
# Verify the path is set correctly by running ''phpcs --config-show''
# Verify that phpcs can see the Joomla codestyle by running ''phpcs -i''
# The output should look like this: ''The installed coding standards are MySource, PEAR, PHPCS, PSR1, PSR2, Squiz, Zend and Joomla''</translate>
<translate>

== Usage == 
</translate>
<translate> You invoke the custom standard by</translate>
''phpcs --standard=Joomla file/to/sniff''

<translate> To test a platform file using the provided platform coding standards, use</translate>
''phpcs --standard=build/phpcs/Joomla path/to/file/or/folder''

<translate> Further documentation on the use of phpcs can be found at the [https://pear.php.net/package/PHP_CodeSniffer/docs pear.php.net website].</translate>

<translate>
==IDE Integration== 
</translate>
<translate> Everybody loves the console. It is, with no doubt, the most effective way to do whatever you need to do. Sometimes even Linux gurus need a little bit of comfort.</translate>

<translate> Fortunately there is a plug-in available for PhpStorm, Eclipse and Netbeans that integrates the CodeSniffer into your favourite IDE, so any coding standard violations are shown like "normal" errors.</translate>

<translate>
=== PhpStorm === 
</translate>
<translate> Code Sniffer is supported out of the box in PhpStorm. Go to Settings and under {{rarr|Editor,Inspections}} you will see the list of sniffers you have installed.</translate>
<translate>
==== Set Path to Code Sniffer ==== 
</translate>
<translate>
# Open Settings (CTRL-ALT-S / CMD-,)
# Go to Languages & Frameworks
# Click on PHP
# Click on Quality Tools
# Click on PHP cs fixer dropdown arrow
# The configuration is set to Local by default
# Click on the 3 dots behind it to open the configuration screen
# The first option is the PHP Code Sniffer (phpcs) path
# Click on the 3 dots behind the path to select the location of the phpcs file. See above on where phpcs may be installed on your site
# Click on Validate to make sure the path is correct and phpcs is working
# Click OK</translate>

<translate>
===== Activating the Joomla Code Style ===== 
</translate>
<translate>
# Open Settings (CTRL-ALT-S / CMD-,)
# Go to Editor
# Click on Inspections
# In the list, go to PHP
# Click on PHP Code Sniffer Validation
# Click on the check box behind it to activate it
# Click the Reload button (2 arrows) to force a reload of rules from disk
# Joomla should now be available in the list. See following image:{{-}}[[File:PhpStorm8CodeSniffer.png|PHPStorm CodeSniffer|500px]]
# Click OK</translate>

<translate>
==== PHP PSR-0, PSR-1 and PSR-2 ==== 
</translate>
* https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md
* https://github.com/pmjones/fig-standards/blob/psr-1-style-guide/proposed/PSR-1-basic.md
* https://github.com/pmjones/fig-standards/blob/psr-1-style-guide/proposed/PSR-2-advanced.md

<translate>
===== Using PHP PSR-1 and PSR-2 Sniff ===== 
</translate>
<translate> A CodeSniffer sniff to check against the PSR-x Coding Standard can be used as well. In that case you can select a different standard than Joomla.</translate>
<translate>
===== Using Joomla Code style ===== 
</translate>
<translate> It's nice to be able to check that the standards are respected. It's even nicer if PhpStorm helps you format properly too as you are coding.</translate>
<translate>
To use the Joomla code style in PhpStorm
# Open Settings (CTRL-ALT-S / CMD-,)
# Go to Editor
# Click on Code Style
# Select Joomla from the Scheme select box</translate>

<translate>
==== PhpStorm / Alternative Method ==== 
</translate>
<translate> '''NOTE''': This method is '''outdated''', but it might be useful if you are looking for a different integration. It also demonstrates the use of external tools in PhpStorm - so it ''shouldn't be deleted''.</translate>

<translate> The Code Sniffer can also be integrated easily as an external tool. PhpStorm will display the output in the console, including click-able links containing line and column numbers to the files that contain errors.</translate>

<translate>
* Click on "Settings" and search for "External tools"
* Click "Add..."
* Choose a "Name", "Group" and "Description".
* Click "Output Filters"
** Click "Add...", Choose a name and enter under "Regular expression to match output" the value: ''$FILE_PATH$:$LINE$:$COLUMN$''
* "Program": Search for the phpcs executable on your system. You have to set the path to the ''phpcs.bat'' from the installed PHP_CodeSniffer PEAR package
** For Unix based systems, the path is something like /usr/bin/phpcs
** In XAMPP (windows), you can find the file in the PHP root folder (e.g. C:\xampp\php\phpcs.bat)
* "Parameters":
** ''--standard=<path/to/joomla-platform>/build/phpcs/Joomla'' The path to the Joomla! coding standards.
** ''--report=emacs'' The will generate a simple list containing links to the error files
** Optionally you may want to specify ''-p'' for "progress" or ''-n'' for "errors only".
** The last parameter has to be ''$FilePath$'' specifying the file or folder you want to sniff.</translate>

<translate> A typical "Parameters" line on a Linux system might look like this:</translate>

''-np --standard=/home/elkuku/libs/joomla/build/phpcs/Joomla --report=emacs $FilePath$''

<translate> You may now right click any file or folder and choose the sniffer from the context menu or add a new tool bar button with a nice Joomla! logo</translate> [[File:icon-16-joomla.png]].

<translate>
=== Netbeans === 
</translate>
<translate> Netbeans has the sniffer functionality integrated into the core system.</translate>

<translate>
# Start your Netbeans IDE
# Open {{rarr|Tools,Options,PHP,Code Analysis,Code Sniffer}}
# You have to set the path to ''phpcs.bat'' from the installed PHP_CodeSniffer PEAR package
#* For Unix based systems the path is something like /usr/bin/phpcs
#* In XAMPP (windows) you can find the file in the PHP root folder (e.g. C:\xampp\php\phpcs.bat)
# As "Default Standard," choose "Joomla" to use the Joomla! standard
# Now you can click ''OK'' to start sniffing
# Open from the top menu {{rarr|Source,Inspect}}
# Enjoy</translate>

<translate>
=== Eclipse === 
</translate>
[[Image:eclipse_pti.png|left|thumb|200px|1) Eclipse PTI]]
{{-}}
<translate>
Installation is a breeze and follows the usual pattern:
# {{rarr|Help,Install New Software}}
# ''Work with:'' Fill in one of the update site URLs found here: http://www.phpsrc.org/eclipse/pti/
# Select the desired tools
# Restart Eclipse.</translate>

[[Image:eclipse_pti_settings.png|right|thumb|150px|2) <translate> Eclipse PTI settings</translate>]]
<translate> You are now able to sniff for code violations against common standards like PEAR or Zend etc.</translate>

<translate> To sniff against your own standards, specify their location and activate them:</translate>
<translate>
# {{rarr|Window,Preferences}}
# {{rarr|PHP Tools,PHP CodeSniffer}}</translate>

<translate> Happy sniffing.</translate>

<translate>
=== Geany === 
</translate>
<translate>
* Open a PHP file. (Otherwise the build menu is not accessible.)
* On the top menu, select Build->Set Build Commands.
* Select the second field and name it as you wish. Enter this code in the Command: ''phpcs --standard=Joomla "%f" | sed -e 's/^/%f |/' | egrep 'WARNING|ERROR'''
* Enter this code in the Error Regular Expression field: ''(.+) [|]\s+([0-9]+)''
* Select ''OK''.
* If the Message Window is not open, display it by selecting it in the top ''View'' menu.
* When viewing any PHP file, press F9 to see the errors found.</translate>

<translate>
=== Atom === 
</translate>
<translate>

* Install phpcs and the Joomla standards as described above.
* In {{rarr|Atom,Preferences,Install}} install ''linter-phpcs'' and all its requirements.
* In {{rarr|Atom,Preferences,Packages,linter-phpcs,Settings}} adjust
** '''Executable Path''' to the path of your phpcs
** '''Code Standard Or Config File''': Joomla
** '''Tab Width''': 4
</translate>

<translate>
=== References === 
</translate>
* [https://github.com/joomla/coding-standards Joomla! Coding Standards]
* [https://www.phpsrc.org/ PTI - PHP tools integration for Eclipse]
* [https://sourceforge.net/projects/phpmdnb/ Netbeans plugin]
* https://hakre.wordpress.com/2010/03/06/php-code-sniffer-eclipse-and-wordpress/ - <translate> Excellent article. Just change ''Wordpress'' for ''Joomla'' ;)</translate>

<noinclude>
[[Category:Development{{#translation:}}]]
[[Category:Bug Squad{{#translation:}}]]
[[Category:IDE (Integrated development environment){{#translation:}}]]
</noinclude>

Joomla CodeSniffer

2023-07-05T16:54:43Z

Cmb: Corrected a URL. Other markup changes.

<noinclude><languages /></noinclude>

<translate>
== A Nose For Joomla == 
</translate>
<translate> This is a custom coding standard for the PHP CodeSniffer that attempts to codify and enforce the Joomla coding standards. This article covers how to set the automatic code style checker. It consists of three steps:</translate>
<translate>
# Install PHP CodeSniffer (phpcs).
# Clone the Joomla Code Style (for use with for phpcs).
# Configure your IDE to work with PHP CodeSniffer and Joomla Code Style.</translate>

[[File:CodeSnifferInAction.jpg|center|thumb|300px|PHP Code Sniffer in action]]

<translate>
==Why?== 
</translate>
<translate> *Coherent and consistent coding practice makes the files look more professional. Conflicting styles in the same project (or worse, the same file) not only look sloppy, they encourage further sloppiness.</translate>
<translate> *When all code complies with the same standard, bad code is easier for everyone to spot.</translate>
<translate> *It makes it easier for someone new to a particular file in the project to find and fix errors or extend functionality.</translate>
<translate> *If there is no consistent standard maintained, sometimes developers will reformat the code to suit themselves. This causes a wide range of changes in the code repository. If there is a later problem, a significant change could be lost in the chaff produced by a diff.</translate>

<translate>
==Installation of PHP Code Sniffer (phpcs)== 
</translate>
<translate>
===Composer=== 
</translate>
<translate> PHP Code Sniffer is available via Composer. It can be installed system-wide with the following command:</translate><br />
''composer global require --dev squizlabs/php_codesniffer "~3.5"''
<translate>

On '''Linux''' PHP Code Sniffer (phpcs) will be installed under your user folder:</translate>
* <translate> Symbolic Link:</translate> ''~/.composer/vendor/bin/phpcs''
* <translate> The file:</translate> ''~/.composer/vendor/squizlabs/php_codesniffer/scripts/phpcs''
<translate> To create that symbolic link, use on the command line: </translate>
''$ sudo ln -s ~/.config/composer/vendor/squizlabs/php_codesniffer/scripts /usr/bin/phpcs''

<translate> or (for example OpenSuse)</translate>
* <translate> Symbolic Link:</translate> ''~/.config/composer/vendor/bin/phpcs''
* <translate> The file:</translate> ''~/.config/composer/vendor/squizlabs/php_codesniffer/scripts/phpcs''

<translate> On '''Windows''' PHP Code Sniffer (phpcs) will be installed under your user folder:</translate>
* <translate> Symbolic Link:</translate> ''c:\Users\Username\AppData\Roaming\Composer\vendor\bin\phpcs''
* <translate> The file:</translate> ''c:\Users\Username\AppData\Roaming\Composer\vendor\squizlabs\php_codesniffer\scripts\phpcs''

<translate>
=== Add composer bin directory to your $PATH === 
</translate>
<translate>

In order to execute PHP Code sniffer from anywhere on Linux or Mac command line you have to add ''.composer/vendor/bin'' to your $PATH variable.</translate>
<translate>

To do this persistent edit your shells start file, like your .profile or .bash_profile file depending which shell you are using (echo $SHELL shows you which one you are using).</translate>

<translate> Add the following line to the file:</translate>
''export PATH=$PATH:~/.composer/vendor/bin''

<translate> Alternatively you can also create a symbolic link in the bin folder:</translate>
''ln -s ~/.composer/vendor/bin/phpcs /usr/local/bin/phpcs''

<translate>
==Install Joomla Coding Standards== 
</translate>
<translate> In order to have PHP Code Sniffer (phpcs) sniffing your Joomla projects for the right code style, you have to install the Joomla Coding Standards.</translate>

<translate> Using composer we can execute:</translate>
''composer global require --dev joomla/coding-standards "~3.0@alpha"''

<translate> Notice that it says ''@alpha'', that is because the coding standard is still in alpha state and we need to allow the installation of alpha status code. If we do not include the @alpha the coding standards will not install and throw this error.</translate>

<pre>
Your requirements could not be resolved to an installable set of packages.

Problem 1
- The requested package joomla/coding-standards ~3.0 is satisfiable by joomla/coding-standards[3.0.0-alpha, 3.0.0-alpha2, 3.x-dev] but these conflict with your requirements or minimum-stability.
</pre>

<translate> Once the installation is done the coding standard will be installed in the global composer folder. The location of this folder depends on your operating system. Some popular locations are:</translate>

'''Mac / Linux'''

''~/.composer/vendor/joomla/coding-standards/''
and
''~/.config/composer/vendor/joomla/coding-standards/''

'''Windows'''

''c:\Users\Username\AppData\Roaming\Composer\vendor\joomla\coding-standards\''

<translate> This is using Composer on Windows.</translate>

<translate> If you can't find it in any of the above folders, note that the folder you are looking for ends with ''\joomla\coding-standards\''.</translate>
<translate>

Finally we need to tell Code Sniffer that the Joomla coding standards exist.</translate>

<translate>
'''Install Joomla Coding Standards'''
# Check if certain paths are already set by running ''phpcs --config-show''
# You can get an answer that looks like this: ''installed_paths: /path/to/installation''
# In step 2, if you see the '''installed_paths''' you need to copy that
# Set the Joomla Coding Standards path in phpcs by executing ''phpcs --config-set installed_paths /Users/user/.composer/vendor/joomla/coding-standards''. If you copied any paths in step 2, include them here as well by separating them with a comma. The command looks like ''phpcs --config-set installed_paths [/to/path1],[/to/path2],[/Users/user/.composer/vendor/joomla/coding-standards]''
# Verify the path is set correctly by running ''phpcs --config-show''
# Verify that phpcs can see the Joomla codestyle by running ''phpcs -i''
# The output should look like this: ''The installed coding standards are MySource, PEAR, PHPCS, PSR1, PSR2, Squiz, Zend and Joomla''</translate>
<translate>

== Usage == 
</translate>
<translate> You invoke the custom standard by</translate>
''phpcs --standard=Joomla file/to/sniff''

<translate> To test a platform file using the provided platform coding standards, use</translate>
''phpcs --standard=build/phpcs/Joomla path/to/file/or/folder''

<translate> Further documentation on the use of phpcs can be found at the [https://pear.php.net/package/PHP_CodeSniffer/docs pear.php.net website].</translate>

<translate>
==IDE Integration== 
</translate>
<translate> Everybody loves the console. It is, with no doubt, the most effective way to do whatever you need to do. Sometimes even Linux gurus need a little bit of comfort.</translate>

<translate> Fortunately there is a plug-in available for PhpStorm, Eclipse and Netbeans that integrates the CodeSniffer into your favourite IDE, so any coding standard violations are shown like "normal" errors.</translate>

<translate>
=== PhpStorm === 
</translate>
<translate> Code Sniffer is supported out of the box in PhpStorm. Go to Settings and under {{rarr|Editor,Inspections}} you will see the list of sniffers you have installed.</translate>
<translate>
==== Set Path to Code Sniffer ==== 
</translate>
<translate>
# Open Settings (CTRL-ALT-S / CMD-,)
# Go to Languages & Frameworks
# Click on PHP
# Click on Quality Tools
# Click on PHP cs fixer dropdown arrow
# The configuration is set to Local by default
# Click on the 3 dots behind it to open the configuration screen
# The first option is the PHP Code Sniffer (phpcs) path
# Click on the 3 dots behind the path to select the location of the phpcs file. See above on where phpcs may be installed on your site
# Click on Validate to make sure the path is correct and phpcs is working
# Click OK</translate>

<translate>
===== Activating the Joomla Code Style ===== 
</translate>
<translate>
# Open Settings (CTRL-ALT-S / CMD-,)
# Go to Editor
# Click on Inspections
# In the list, go to PHP
# Click on PHP Code Sniffer Validation
# Click on the check box behind it to activate it
# Click the Reload button (2 arrows) to force a reload of rules from disk
# Joomla should now be available in the list. See following image:{{-}}[[File:PhpStorm8CodeSniffer.png|PHPStorm CodeSniffer|500px]]
# Click OK</translate>

<translate>
==== PHP PSR-0, PSR-1 and PSR-2 ==== 
</translate>
* https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md
* https://github.com/pmjones/fig-standards/blob/psr-1-style-guide/proposed/PSR-1-basic.md
* https://github.com/pmjones/fig-standards/blob/psr-1-style-guide/proposed/PSR-2-advanced.md

<translate>
===== Using PHP PSR-1 and PSR-2 Sniff ===== 
</translate>
<translate> A CodeSniffer sniff to check against the PSR-x Coding Standard can be used as well. In that case you can select a different standard than Joomla.</translate>
<translate>
===== Using Joomla Code style ===== 
</translate>
<translate> It's nice to be able to check that the standards are respected. It's even nicer if PhpStorm helps you format properly too as you are coding.</translate>
<translate>
To use the Joomla code style in PhpStorm
# Open Settings (CTRL-ALT-S / CMD-,)
# Go to Editor
# Click on Code Style
# Select Joomla from the Scheme select box</translate>

<translate>
==== PhpStorm / Alternative Method ==== 
</translate>
<translate> '''NOTE''': This method is '''outdated''', but it might be useful if you are looking for a different integration. It also demonstrates the use of external tools in PhpStorm - so it ''shouldn't be deleted''.</translate>

<translate> The Code Sniffer can also be integrated easily as an external tool. PhpStorm will display the output in the console, including click-able links containing line and column numbers to the files that contain errors.</translate>

<translate>
* Click on "Settings" and search for "External tools"
* Click "Add..."
* Choose a "Name", "Group" and "Description".
* Click "Output Filters"
** Click "Add...", Choose a name and enter under "Regular expression to match output" the value: ''$FILE_PATH$:$LINE$:$COLUMN$''
* "Program": Search for the phpcs executable on your system. You have to set the path to the ''phpcs.bat'' from the installed PHP_CodeSniffer PEAR package
** For Unix based systems, the path is something like /usr/bin/phpcs
** In XAMPP (windows), you can find the file in the PHP root folder (e.g. C:\xampp\php\phpcs.bat)
* "Parameters":
** ''--standard=<path/to/joomla-platform>/build/phpcs/Joomla'' The path to the Joomla! coding standards.
** ''--report=emacs'' The will generate a simple list containing links to the error files
** Optionally you may want to specify ''-p'' for "progress" or ''-n'' for "errors only".
** The last parameter has to be ''$FilePath$'' specifying the file or folder you want to sniff.</translate>

<translate> A typical "Parameters" line on a Linux system might look like this:</translate>

''-np --standard=/home/elkuku/libs/joomla/build/phpcs/Joomla --report=emacs $FilePath$''

<translate> You may now right click any file or folder and choose the sniffer from the context menu or add a new tool bar button with a nice Joomla! logo</translate> [[File:icon-16-joomla.png]].

<translate>
=== Netbeans === 
</translate>
<translate> Netbeans has the sniffer functionality integrated into the core system.</translate>

<translate>
# Start your Netbeans IDE
# Open {{rarr|Tools,Options,PHP,Code Analysis,Code Sniffer}}
# You have to set the path to ''phpcs.bat'' from the installed PHP_CodeSniffer PEAR package
#* For Unix based systems the path is something like /usr/bin/phpcs
#* In XAMPP (windows) you can find the file in the PHP root folder (e.g. C:\xampp\php\phpcs.bat)
# As "Default Standard," choose "Joomla" to use the Joomla! standard
# Now you can click ''OK'' to start sniffing
# Open from the top menu {{rarr|Source,Inspect}}
# Enjoy</translate>

<translate>
=== Eclipse === 
</translate>
[[Image:eclipse_pti.png|left|thumb|200px|1) Eclipse PTI]]
{{-}}
<translate>
Installation is a breeze and follows the usual pattern:
# {{rarr|Help,Install New Software}}
# ''Work with:'' Fill in one of the update site URLs found here: http://www.phpsrc.org/eclipse/pti/
# Select the desired tools
# Restart Eclipse.</translate>

[[Image:eclipse_pti_settings.png|right|thumb|150px|2) <translate> Eclipse PTI settings</translate>]]
<translate> You are now able to sniff for code violations against common standards like PEAR or Zend etc.</translate>

<translate> To sniff against your own standards, specify their location and activate them (see screen shot 2)</translate>
<translate>
# {{rarr|Window,Preferences}}
# {{rarr|PHP Tools,PHP CodeSniffer}}</translate>

<translate> Happy sniffing.</translate>

<translate>
=== Geany === 
</translate>
<translate>
* Open a PHP file. (Otherwise the build menu is not accessible.) See this [http://static.xscreenshot.com/2016/07/13/08/screen_6bc0692cf995702a1e379b39643d0c2d Screenshot]
* On the top menu, select Build->Set Build Commands.
* Select the second field and name it as you wish. Enter this code in the Command: ''phpcs --standard=Joomla "%f" | sed -e 's/^/%f |/' | egrep 'WARNING|ERROR'''
* Enter this code in the Error Regular Expression field: ''(.+) [|]\s+([0-9]+)'' See this [http://view.xscreenshot.com/ef00820cf7c017ce659c8e9f0b02d3ae Screenshot]
* Select OK.
* If the Message Window is not open, display it by selecting it in the top View menu.
* When viewing any PHP file, press F9 to see the errors found. [http://view.xscreenshot.com/8704b9fd1bda3f841364a0ffa28a54ae Screenshot]</translate>

<translate>
=== Atom === 
</translate>
<translate>

* Install phpcs and the Joomla standards as described above.
* In {{rarr|Atom,Preferences,Install}} install ''linter-phpcs'' and all its requirements.
* In {{rarr|Atom,Preferences,Packages,linter-phpcs,Settings}} adjust
** '''Executable Path''' to the path of your phpcs
** '''Code Standard Or Config File''': Joomla
** '''Tab Width''': 4
</translate>

<translate>
=== References === 
</translate>
* [https://github.com/joomla/coding-standards Joomla! Coding Standards]
* [https://www.phpsrc.org/ PTI - PHP tools integration for Eclipse]
* [https://sourceforge.net/projects/phpmdnb/ Netbeans plugin]
* https://hakre.wordpress.com/2010/03/06/php-code-sniffer-eclipse-and-wordpress/ - <translate> Excellent article. Just change ''Wordpress'' for ''Joomla'' ;)</translate>

<noinclude>
[[Category:Development{{#translation:}}]]
[[Category:Bug Squad{{#translation:}}]]
[[Category:IDE (Integrated development environment){{#translation:}}]]
</noinclude>

Joomla CodeSniffer

2023-07-05T01:02:02Z

Cmb: Corrected some URLs. Other markup changes.

<noinclude><languages /></noinclude>

<translate>
== A Nose For Joomla == 
</translate>
<translate> This is a custom coding standard for the PHP CodeSniffer that attempts to codify and enforce the Joomla coding standards. This article covers how to set the automatic code style checker. It consists of three steps:</translate>
<translate>
# Install PHP CodeSniffer (phpcs).
# Clone the Joomla Code Style (for use with for phpcs).
# Configure your IDE to work with PHP CodeSniffer and Joomla Code Style.</translate>

[[File:CodeSnifferInAction.jpg|center|thumb|300px|PHP Code Sniffer in action]]

<translate>
==Why?== 
</translate>
<translate> *Coherent and consistent coding practice makes the files look more professional. Conflicting styles in the same project (or worse, the same file) not only look sloppy, they encourage further sloppiness.</translate>
<translate> *When all code complies with the same standard, bad code is easier for everyone to spot.</translate>
<translate> *It makes it easier for someone new to a particular file in the project to find and fix errors or extend functionality.</translate>
<translate> *If there is no consistent standard maintained, sometimes developers will reformat the code to suit themselves. This causes a wide range of changes in the code repository. If there is a later problem, a significant change could be lost in the chaff produced by a diff.</translate>

<translate>
==Installation of PHP Code Sniffer (phpcs)== 
</translate>
<translate>
===Composer=== 
</translate>
<translate> PHP Code Sniffer is available via Composer. It can be installed system-wide with the following command:</translate><br />
''composer global require --dev squizlabs/php_codesniffer "~3.5"''
<translate>

On '''Linux''' PHP Code Sniffer (phpcs) will be installed under your user folder:</translate>
* <translate> Symbolic Link:</translate> ''~/.composer/vendor/bin/phpcs''
* <translate> The file:</translate> ''~/.composer/vendor/squizlabs/php_codesniffer/scripts/phpcs''
<translate> To create that symbolic link, use on the command line: </translate>
''$ sudo ln -s ~/.config/composer/vendor/squizlabs/php_codesniffer/scripts /usr/bin/phpcs''

<translate> or (for example OpenSuse)</translate>
* <translate> Symbolic Link:</translate> ''~/.config/composer/vendor/bin/phpcs''
* <translate> The file:</translate> ''~/.config/composer/vendor/squizlabs/php_codesniffer/scripts/phpcs''

<translate> On '''Windows''' PHP Code Sniffer (phpcs) will be installed under your user folder:</translate>
* <translate> Symbolic Link:</translate> ''c:\Users\Username\AppData\Roaming\Composer\vendor\bin\phpcs''
* <translate> The file:</translate> ''c:\Users\Username\AppData\Roaming\Composer\vendor\squizlabs\php_codesniffer\scripts\phpcs''

<translate>
=== Add composer bin directory to your $PATH === 
</translate>
<translate>

In order to execute PHP Code sniffer from anywhere on Linux or Mac command line you have to add ''.composer/vendor/bin'' to your $PATH variable.</translate>
<translate>

To do this persistent edit your shells start file, like your .profile or .bash_profile file depending which shell you are using (echo $SHELL shows you which one you are using).</translate>

<translate> Add the following line to the file:</translate>
''export PATH=$PATH:~/.composer/vendor/bin''

<translate> Alternatively you can also create a symbolic link in the bin folder:</translate>
''ln -s ~/.composer/vendor/bin/phpcs /usr/local/bin/phpcs''

<translate>
==Install Joomla Coding Standards== 
</translate>
<translate> In order to have PHP Code Sniffer (phpcs) sniffing your Joomla projects for the right code style, you have to install the Joomla Coding Standards.</translate>

<translate> Using composer we can execute:</translate>
''composer global require --dev joomla/coding-standards "~3.0@alpha"''

<translate> Notice that it says ''@alpha'', that is because the coding standard is still in alpha state and we need to allow the installation of alpha status code. If we do not include the @alpha the coding standards will not install and throw this error.</translate>

<pre>
Your requirements could not be resolved to an installable set of packages.

Problem 1
- The requested package joomla/coding-standards ~3.0 is satisfiable by joomla/coding-standards[3.0.0-alpha, 3.0.0-alpha2, 3.x-dev] but these conflict with your requirements or minimum-stability.
</pre>

<translate> Once the installation is done the coding standard will be installed in the global composer folder. The location of this folder depends on your operating system. Some popular locations are:</translate>

'''Mac / Linux'''
~/.composer/vendor/joomla/coding-standards/

~/.config/composer/vendor/joomla/coding-standards/
'''Windows'''
c:\Users\Username\AppData\Roaming\Composer\vendor\joomla\coding-standards\
<translate> This is using Composer on Windows.</translate>

<translate> If you can't find it in any of the above folders, note that the folder you are looking for ends with '''\joomla\coding-standards\'''</translate>
<translate>

Finally we need to tell Code Sniffer that the Joomla coding standards exist.</translate>

<translate>
'''Install Joomla Coding Standards'''
# Check if certain paths are already set by running ''phpcs --config-show''
# You can get an answer that looks like this: ''installed_paths: /path/to/installation''
# In step 2, if you see the '''installed_paths''' you need to copy that
# Set the Joomla Coding Standards path in phpcs by executing ''phpcs --config-set installed_paths /Users/user/.composer/vendor/joomla/coding-standards''. If you copied any paths in step 2, include them here as well by separating them with a comma. The command looks like ''phpcs --config-set installed_paths [/to/path1],[/to/path2],[/Users/user/.composer/vendor/joomla/coding-standards]''
# Verify the path is set correctly by running ''phpcs --config-show''
# Verify that phpcs can see the Joomla codestyle by running ''phpcs -i''
# The output should look like this: ''The installed coding standards are MySource, PEAR, PHPCS, PSR1, PSR2, Squiz, Zend and Joomla''</translate>
<translate>

== Usage == 
</translate>
<translate> You invoke the custom standard by</translate>
''phpcs --standard=Joomla file/to/sniff''

<translate> To test a platform file using the provided platform coding standards, use</translate>
''phpcs --standard=build/phpcs/Joomla path/to/file/or/folder''

<translate> Further documentation on the use of phpcs can be found at: [http://pear.php.net/package/PHP_CodeSniffer/docs]</translate>

<translate>
==IDE Integration== 
</translate>
<translate> Everybody loves the console. It is, with no doubt, the most effective way to do whatever you need to do. Sometimes even Linux gurus need a little bit of comfort.</translate>

<translate> Fortunately there is a plug-in available for PhpStorm, Eclipse and Netbeans that integrates the CodeSniffer into your favourite IDE, so any coding standard violations are shown like "normal" errors.</translate>

<translate>
=== PhpStorm === 
</translate>
<translate> Code Sniffer is supported out of the box in PhpStorm. Go to Settings and under {{rarr|Editor,Inspections}} you will see the list of sniffers you have installed.</translate>
<translate>
==== Set Path to Code Sniffer ==== 
</translate>
<translate>
# Open Settings (CTRL-ALT-S / CMD-,)
# Go to Languages & Frameworks
# Click on PHP
# Click on Quality Tools
# Click on PHP cs fixer dropdown arrow
# The configuration is set to Local by default
# Click on the 3 dots behind it to open the configuration screen
# The first option is the PHP Code Sniffer (phpcs) path
# Click on the 3 dots behind the path to select the location of the phpcs file. See above on where phpcs may be installed on your site
# Click on Validate to make sure the path is correct and phpcs is working
# Click OK</translate>

<translate>
===== Activating the Joomla Code Style ===== 
</translate>
<translate>
# Open Settings (CTRL-ALT-S / CMD-,)
# Go to Editor
# Click on Inspections
# In the list, go to PHP
# Click on PHP Code Sniffer Validation
# Click on the check box behind it to activate it
# Click the Reload button (2 arrows) to force a reload of rules from disk
# Joomla should now be available in the list. See following image:{{-}}[[File:PhpStorm8CodeSniffer.png|PHPStorm CodeSniffer|500px]]
# Click OK</translate>

<translate>
==== PHP PSR-0, PSR-1 and PSR-2 ==== 
</translate>
* https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md
* https://github.com/pmjones/fig-standards/blob/psr-1-style-guide/proposed/PSR-1-basic.md
* https://github.com/pmjones/fig-standards/blob/psr-1-style-guide/proposed/PSR-2-advanced.md

<translate>
===== Using PHP PSR-1 and PSR-2 Sniff ===== 
</translate>
<translate> A CodeSniffer sniff to check against the PSR-x Coding Standard can be used as well. In that case you can select a different standard than Joomla.</translate>
<translate>
===== Using Joomla Code style ===== 
</translate>
<translate> It's nice to be able to check that the standards are respected. It's even nicer if PhpStorm helps you format properly too as you are coding.</translate>
<translate>
To use the Joomla code style in PhpStorm
# Open Settings (CTRL-ALT-S / CMD-,)
# Go to Editor
# Click on Code Style
# Select Joomla from the Scheme select box</translate>

<translate>
==== PhpStorm / Alternative Method ==== 
</translate>
<translate> '''NOTE''': This method is '''outdated''', but it might be useful if you are looking for a different integration. It also demonstrates the use of external tools in PhpStorm - so it ''shouldn't be deleted''.</translate>

<translate> The Code Sniffer can also be integrated easily as an external tool. PhpStorm will display the output in the console, including click-able links containing line and column numbers to the files that contain errors.</translate>

<translate>
* Click on "Settings" and search for "External tools"
* Click "Add..."
* Choose a "Name", "Group" and "Description".
* Click "Output Filters"
** Click "Add...", Choose a name and enter under "Regular expression to match output" the value: ''$FILE_PATH$:$LINE$:$COLUMN$''
* "Program": Search for the phpcs executable on your system. You have to set the path to the ''phpcs.bat'' from the installed PHP_CodeSniffer PEAR package
** For Unix based systems, the path is something like /usr/bin/phpcs
** In XAMPP (windows), you can find the file in the PHP root folder (e.g. C:\xampp\php\phpcs.bat)
* "Parameters":
** ''--standard=<path/to/joomla-platform>/build/phpcs/Joomla'' The path to the Joomla! coding standards.
** ''--report=emacs'' The will generate a simple list containing links to the error files
** Optionally you may want to specify ''-p'' for "progress" or ''-n'' for "errors only".
** The last parameter has to be ''$FilePath$'' specifying the file or folder you want to sniff.</translate>

<translate> A typical "Parameters" line on a Linux system might look like this:</translate>
<pre>-np --standard=/home/elkuku/libs/joomla/build/phpcs/Joomla --report=emacs $FilePath$</pre>

<translate> You may now right click any file or folder and choose the sniffer from the context menu or add a new tool bar button with a nice Joomla! logo</translate> [[File:icon-16-joomla.png]].

<translate>
=== Netbeans === 
</translate>
<translate> Netbeans has the sniffer functionality integrated into the core system.</translate>

<translate>
# Start your Netbeans IDE
# Open {{rarr|Tools,Options,PHP,Code Analysis,Code Sniffer}}
# You have to set the path to ''phpcs.bat'' from the installed PHP_CodeSniffer PEAR package
#* For Unix based systems the path is something like /usr/bin/phpcs
#* In XAMPP (windows) you can find the file in the PHP root folder (e.g. C:\xampp\php\phpcs.bat)
# As "Default Standard," choose "Joomla" to use the Joomla! standard
# Now you can click ''OK'' to start sniffing
# Open from the top menu Source => Inspect...
# Enjoy</translate>

<translate>
=== Eclipse === 
</translate>
[[Image:eclipse_pti.png|left|thumb|200px|1) Eclipse PTI]]
{{-}}
<translate>
Installation is a breeze and follows the usual pattern:
# ''Help => Install New Software...''
# ''Work with:'' Fill in one of the update site URLs found here: http://www.phpsrc.org/eclipse/pti/
# Select the desired tools
# Restart Eclipse.</translate>

[[Image:eclipse_pti_settings.png|right|thumb|150px|2) <translate> Eclipse PTI settings</translate>]]
<translate> You are now able to sniff for code violations against common standards like PEAR or Zend etc.</translate>

<translate> To sniff against your own standards, specify their location and activate them (see screen shot 2)</translate>
<translate>
# ''Window => Preferences''
# ''PHP Tools => PHP CodeSniffer''</translate>

<translate> Happy sniffing.</translate>

<translate>
=== Geany === 
</translate>
<translate>
* Open a PHP file. (Otherwise the build menu is not accessible.) See this [http://static.xscreenshot.com/2016/07/13/08/screen_6bc0692cf995702a1e379b39643d0c2d Screenshot]
* On the top menu, select Build->Set Build Commands.
* Select the second field and name it as you wish. Enter this code in the Command: <code>phpcs --standard=Joomla "%f" | sed -e 's/^/%f |/' | egrep 'WARNING|ERROR'</code>
* Enter this code in the Error Regular Expression field: <code>(.+) [|]\s+([0-9]+)</code> See this [http://view.xscreenshot.com/ef00820cf7c017ce659c8e9f0b02d3ae Screenshot]
* Select OK.
* If the Message Window is not open, display it by selecting it in the top View menu.
* When viewing any PHP file, press F9 to see the errors found. [http://view.xscreenshot.com/8704b9fd1bda3f841364a0ffa28a54ae Screenshot]</translate>

<translate>
=== Atom === 
</translate>
<translate>

* Install phpcs and the Joomla standards as described above.
* In {{rarr|Atom,Preferences,Install}} install ''linter-phpcs'' and all its requirements.
* In {{rarr|Atom,Preferences,Packages,linter-phpcs,Settings|| adjust
** '''Executable Path''' to the path of your phpcs
** '''Code Standard Or Config File''': Joomla
** '''Tab Width''': 4
</translate>

<translate>
=== References === 
</translate>
* https://github.com/joomla/coding-standards - <translate> Joomla! Coding Standards</translate>
* https://www.phpsrc.org/ <translate> PTI - PHP tools integration for Eclipse</translate>
* https://sourceforge.net/projects/phpmdnb/ <translate> Netbeans plugin</translate>
* https://hakre.wordpress.com/2010/03/06/php-code-sniffer-eclipse-and-wordpress/ - <translate> Excellent article. Just change "Wordpress" for "Joomla!" ;)</translate>

<noinclude>
[[Category:Development{{#translation:}}]]
[[Category:Bug Squad{{#translation:}}]]
[[Category:IDE (Integrated development environment){{#translation:}}]]
</noinclude>

Visual Studio Code

2023-07-01T21:37:35Z

Cmb: Xdebug 2 is no longer supported.

<noinclude><languages /></noinclude>
<translate>

[https://code.visualstudio.com/ Visual Studio Code (VSCode)] is a source code editor developed by Microsoft for Windows, Linux and MacOS (including M1 Macs). It includes support for debugging, embedded Git control and GitHub, syntax highlighting, intelligent code completion, snippets, and code refactoring.


The main characteristic of the editor is that it is extensible and it has a huge collection of extensions maintained by users and by Microsoft itself. See details at the [https://marketplace.visualstudio.com/ VSCode Extensions for Visual Studio Code] website.


As a general introduction, this is a presentation about the topic [https://www.renekreijveld.nl/slides/juglondon/vscode.pdf Joomla Development with Visual Studio Code], by René Kreijveld, Joomla developer Destiny B.V. Joomla User Group London, 16th march 2021.


On this page, we detail a list of recommended extensions to configure VSCode to support PHP and Joomla.


This is a list of extensions to support PHP on VSCode:


* '''PHP Debug''' [https://marketplace.visualstudio.com/items?itemName=felixfbecker.php-debug felixfbecker.php-debug]. Debug support for PHP with Xdebug.
* '''phpcs''' [https://marketplace.visualstudio.com/items?itemName=ikappas.phpcs ikappas.phpcs]. PHP CodeSniffer for Visual Studio Code.
* '''PHP Intelephense''' [https://marketplace.visualstudio.com/items?itemName=bmewburn.vscode-intelephense-client bmewburn.vscode-intelephense-client]. PHP code intelligence for Visual Studio Code. Alternative: ''PHP IntelliSense'' [https://marketplace.visualstudio.com/items?itemName=felixfbecker.php-intellisense felixfbecker.php-intellisense]
* '''PHPUnit''' [https://marketplace.visualstudio.com/items?itemName=emallin.phpunit emallin.phpunit]. Run PHPUnit tests from VSCode.
* '''phpfmt''' [https://marketplace.visualstudio.com/items?itemName=kokororin.vscode-phpfmt kokororin.vscode-phpfmt]. The missing phpfmt extension for Visual Studio Code. The phpfmt formatter can parse and format even a PHP file version 4 if needed.
* '''php cs fixer''' [https://marketplace.visualstudio.com/items?itemName=junstyle.php-cs-fixer junstyle.php-cs-fixer]: In case of opting for the [https://www.php-fig.org/psr/psr-2/ PSR-2: Coding Style Guide]). PHP CS Fixer extension for VS Code, PHP formatter, PHP code beautify tool, format HTML.
* '''PHP Namespace Resolver''' [https://marketplace.visualstudio.com/items?itemName=MehediDracula.php-namespace-resolver MehediDracula.php-namespace-resolver]: PHP Namespace Resolver can import and expand your class. You can also sort your imported classes by line length or in alphabetical order.
* '''PHP Phan (Analyzer)''' [https://marketplace.visualstudio.com/items?itemName=TysonAndre.php-phan tysonandre.php-phan]. Phan - static analyzer for PHP, minimizing false positives.
* '''phpmd''' [https://marketplace.visualstudio.com/items?itemName=linyang95.phpmd linyang95.phpmd]. VS Code extension for PHP, using PHPMD.


The Git protocol is natively supported on VSCode. However, there are extensions to improve code and repository management. This is a list of featured extensions for this task:


* '''Git History''' [https://marketplace.visualstudio.com/items?itemName=donjayamanne.githistory donjayamanne.githistory]: Git History, Search and More (including git log).
* '''GitHub''' [https://marketplace.visualstudio.com/items?itemName=KnisterPeter.vscode-github KnisterPeter.vscode-github]: This VSCode extension integrates with GitHubExtensions for Visual Studio Code
* '''GitHub Pull Requests and Issues''' [https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-github GitHub.vscode-pull-request-github]: Review and manage your GitHub pull requests and issues directly in VS Code
* '''gitignore''' [https://marketplace.visualstudio.com/items?itemName=codezombiech.gitignore codezombiech.gitignore]: A extension for Visual Studio Code that assists you in working with ''.gitignore'' files.
* '''Visual Studio Code Commitizen Support''' [https://marketplace.visualstudio.com/items?itemName=KnisterPeter.vscode-commitizen KnisterPeter.vscode-commitizen]: This VSCode extension adds ''commitizen'' support.


This is a list of extensions to support Joomla on VSCode:


* '''Joomla Snippets''' [https://marketplace.visualstudio.com/items?itemName=AnibalSanchez.vs-code-joomla-snippets anibalsanchez.vs-code-joomla-snippets]. Snippets for Joomla including Joomla 3.x and Joomla 4 Snippets.
* '''PHP Getters & Setters''' [https://marketplace.visualstudio.com/items?itemName=phproberto.vscode-php-getters-setters phproberto.vscode-php-getters-setters]. Create PHP getters and setters from class properties.


This is a list of extensions to support remote SSH development:


* '''Remote - SSH''' [https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh ms-vscode-remote.remote-ssh]: The Remote - SSH extension lets you use any remote machine with an SSH server as your development environment. This can greatly simplify development and troubleshooting in a wide variety of situations. For more information: [https://code.visualstudio.com/docs/remote/ssh-tutorial Remote development over SSH]
* '''Live Share''' [https://marketplace.visualstudio.com/items?itemName=MS-vsliveshare.vsliveshare MS-vsliveshare.vsliveshare]: Visual Studio Live Share enables you to collaboratively edit and debug with others in real-time, regardless of what programming languages you're using or app types you're building. It allows you to instantly (and securely) share your current project, and then as needed, share debugging sessions, terminal instances, localhost web apps, voice calls, and more!


This is a list of handy extensions highly recommended to ease the development:


* '''EditorConfig for VS Code''' [https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig editorconfig.editorconfig] EditorConfig Support for Visual Studio Code.
* '''change-case''' [https://marketplace.visualstudio.com/items?itemName=wmaurer.change-case wmaurer.change-case]: Quickly change the case (camelCase, CONSTANT_CASE, snake_case, etc) of the current selection or current word.
* '''Project Manager''' [https://marketplace.visualstudio.com/items?itemName=alefragnani.project-manager alefragnani.project-manager]: It helps you to easily access your projects, no matter where they are located. Don't miss those important projects anymore.

== PHP Debug Configuration == 


The extension supports the most common configurations of PHP [https://xdebug.org/ Xdebug]. It fully integrates all VSCode features to debug PHP scripts.


To configure the extension, visit the [https://github.com/xdebug/vscode-php-debug#installation official documentation].


As a sample configuration for VSCode debugging, this is a common ''launch.json'':


<syntaxhighlight lang="javascript">
{
// Use IntelliSense to learn about possible attributes.
// Hover to view descriptions of existing attributes.
// For more information, visit: https://code.visualstudio.com/docs/editor/debugging#_launch-configurations
"version": "0.2.0",
"configurations": [


{
"name": "Listen for Xdebug",
"type": "php",
"request": "launch",


// Server Remote Xdebug Port - 9003 is the default Xdebug port
"port": 9003,


// Server Remote Path -> Local Project Path
"pathMappings": {
"/app/www": "${workspaceRoot}/www"
}
},
{
"name": "Launch currently open script",
"type": "php",
"request": "launch",
"program": "${file}",
"cwd": "${fileDirname}",


// Local Xdebug Port - 9003 is the default Xdebug port
"port": 9003
}
]
}
</syntaxhighlight>


Related to the ''launch.json'' configuration that ''felixfbecker/vscode-php-debug'' requires, it is the configuration of PHP Xdebug itself.


Your development environment should have Xdebug 3. (Xdebug 2 is no longer supported.) To configure PHP Xdebug, these are the most common settings for ''php.ini'':

=== Xdebug 3 Configuration === 


<syntaxhighlight>
[Xdebug]
;;;;;;;;;;;;;;;;;;;
; xdebug-3.0.0
; https://xdebug.org/docs/upgrade_guide
;;;;;;;;;;;;;;;;;;;
xdebug.mode = debug
xdebug.start_with_request = yes
xdebug.discover_client_host = true
; xdebug.client_port = 9003
</syntaxhighlight>


To know more about how Xdebug works internally to connect to the Editor, check the [https://xdebug.org/docs/ Xdebug 3 — Documentation].

== ''phpcs'' Configuration == 


To configure the extension, visit the [https://marketplace.visualstudio.com/items?itemName=ikappas.phpcs official documentation].


The extension supports the most common configurations of [https://pear.php.net/package/PHP_CodeSniffer/ PHP_CodeSniffer].


By default, PHP_CodeSniffer comes with several coding standards. Once the extension is installed, it works with ''PSR2''.


<syntaxhighlight lang="javascript">
"phpcs.standard": "PSR2",
</syntaxhighlight>


To configure the extension to apply the '''Joomla! Coding Standards''', install the rules following the [https://developer.joomla.org/coding-standards/html.html official guide].


Once '''Joomla! Coding Standards''' is installed, configure the User Settings following this sample configuration:


<syntaxhighlight lang="javascript">
"phpcs.standard": "/home/YOUR-USER/.../Joomla",
</syntaxhighlight>

== Configuration of PHP Intelephense == 


To configure the extension, visit the [https://github.com/bmewburn/vscode-intelephense#quick-start official documentation].


The extension does not require additional configuration.


VSCode comes with basic support of the PHP language. It is a good idea to disable the default support to avoid conflicts:


<syntaxhighlight lang="javascript">
// Disable basic suggestions
"php.suggest.basic": false,


// To activate code suggestions in comments
"editor.quickSuggestions": { "comments": true },
</syntaxhighlight>


As an alternative, it is also a popular extension: '''PHP IntelliSense''' [https://marketplace.visualstudio.com/items?itemName=felixfbecker.php-intellisense felixfbecker.php-intellisense] Advanced Autocompletion and Refactoring support for PHP.

== PHPUnit Configuration == 


To configure the extension, visit the [https://github.com/elonmallin/vscode-phpunit#setup official documentation].


The extension integrates [https://phpunit.de/ PHP Unit] with VSCode, so all features of PHP Unit are integrated with VSCode and can also be parameterized for further integration with the user interface.


This is a sample configuration of the extension:


<syntaxhighlight lang="javascript">
"phpunit.preferRunClassTestOverQuickPickWindow": true,
"phpunit.driverPriority": [
"Path",
"Command",
"Composer",
"Phar",
"Ssh",
"GlobalPhpUnit"
],
</syntaxhighlight>

== PHP CS Fixer Configuration (Only for PSR2) == 


To configure the extension, visit the [https://github.com/junstyle/vscode-php-cs-fixer#installation official documentation].


The extension integrates [https://github.com/PHP-CS-Fixer/PHP-CS-Fixer PHP CS Fixer] with VSCode, so all features of PHP CS Fixer are integrated with VSCode and can also be parameterized for further integration with the user interface.


To automatically apply PHP CS Fixer to PHP files, configure the user settings in this way:


<syntaxhighlight lang="javascript">
"[php]": {
"editor.defaultFormatter": "junstyle.php-cs-fixer",
},
"php-cs-fixer.onsave": true,
</syntaxhighlight>

== PHP Phan (Analyzer) Configuration == 


To configure the extension, visit the [https://marketplace.visualstudio.com/items?itemName=TysonAndre.php-phan official documentation].


This is a sample configuration of the extension:


<syntaxhighlight lang="javascript">
"phan.phpExecutablePath": "/usr/bin/php",
"phan.analyzedFileExtensions": [
"php"
],
</syntaxhighlight>

== ''phpmd'' Configuration == 


To configure the extension, visit the [https://github.com/xdebug/vscode-php-debug#installation official documentation].


The extension does not require additional configuration.


This is a sample configuration of the extension:


<syntaxhighlight lang="javascript">
"phpmd.command": "php /home/YOUR-USER/.../phpmd/phpmd.phar",
"phpmd.rules": "/home/YOUR-USER/.../phpmd-rulesets/phpmd_config.xml",
</syntaxhighlight>

== Configure EditorConfig for VS Code == 


EditorConfig is a file format and collection of text editor plugins for maintaining consistent coding styles between different editors and IDEs.


To configure the editor according to your preferences, create a file ''.editorconfig'':


<syntaxhighlight lang="javascript">
; EditorConfig helps developers define and maintain consistent
; coding styles between different editors and IDEs.


; For more visit https://editorconfig.org/
root = true


; Choose between lf or rf on "end_of_line" property
[*]
charset = utf-8
end_of_line = lf
indent_size = 2
indent_style = space
insert_final_newline = true
trim_trailing_whitespace = true


# editorconfig-tools is unable to ignore longs strings or URLs
max_line_length = null


[*.html]
indent_style = tab


# PSR-2
# [*.php]
# indent_size = 4
# indent_style = space


# Joomla! Coding Standards
[*.php]
indent_size = 4
indent_style = tab


[*.md]
trim_trailing_whitespace = false


[*.yml]
indent_style = space
indent_size = 2
</syntaxhighlight>
</translate>

<noinclude>
<translate>

[[Category:Development{{#translation:}}]]
[[Category:Beginner_Development{{#translation:}}]]
[[Category:Server configurations{{#translation:}}]]
[[Category:Server setup local{{#translation:}}]]
[[Category:Server configurations{{#translation:}}]]
[[Category:Bug Squad{{#translation:}}]]
[[Category:IDE (Integrated development environment){{#translation:}}]]
</translate>
</noinclude>

Setting up your workstation for Joomla development

2023-06-29T21:16:24Z

Cmb: URL correction. Other text editing.

<noinclude><languages /></noinclude>
<translate> This page is centered around developing on and with Joomla. If you find yourself stuck following any of these tutorials, please visit [[jforum:810|our Installation forums]] for more information.</translate>

<translate>== Installing a Web Server == </translate>
<translate> Installing a typical web server environment is easy with [[wikipedia:List_of_AMP_packages|AMP packages]] (Apache, MySQL, PHP).</translate>
* <translate> [https://www.apachefriends.org/ XAMPP] at Apache Friends (Multiple operating systems)</translate>
** <translate> [[XAMPP]] (for Joomla 1.5 and 2.5 please view [[J2.5:XAMPP|XAMPP for Joomla 2.5]])</translate>
* <translate> [[wikipedia:LAMP (software bundle)|LAMP]] (Linux)</translate>
**<translate> [[Configuring a LAMPP server for PHP development]]</translate>
* <translate> [[wikipedia:WAMP|WAMP]] (Windows) A good choice for a local server environment for Windows is [https://www.wampserver.com/en/ WampServer].</translate>
* <translate> [[wikipedia: MAMP|MAMP]] (Macintosh / OS X) [https://www.mamp.info/en/windows/ MAMP] may be a good choice.</translate>
* <translate> [https://bitnami.com/stack/joomla Bitnami] also offers a Joomla stack that you can install locally or on a remote server.</translate>
<translate> If you want use XDebug for debugging, you'll need to tune the PHP settings</translate>
* <translate> [[Edit PHP.INI File for XDebug]]</translate>

<translate>== Installing an IDE/Editor (and Debugging)== </translate>
* <translate> [[wikipedia:Visual_Studio_Code|Visual Studio Code]]</translate>
** <translate>  [[Visual_Studio_Code|Configuring Visual Studio Code for Joomla development]]</translate>
*<translate> PhpStorm IDE</translate>
**<translate> [https://www.jetbrains.com/help/phpstorm/joomla-specific-coding-assistance.html Joomla! Development with PhpStorm] </translate>
* <translate> [[wikipedia:Eclipse (software)|Eclipse IDE]]</translate>
** <translate> [[Configuring Eclipse for joomla development]]</translate>
** <translate> [[How to configure Eclipse IDE for PHP development]]</translate>
** <translate> [[Configuring Eclipse IDE for PHP development]]</translate>
** <translate> [https://community.joomla.org/blogs/community/webinar-using-eclipse-for-joomla-development.html Using Eclipse for Joomla! Development] Video webinar demonstrating overview of Eclipse features for Joomla! development</translate>
* <translate> [[wikipedia:ActiveState_Komodo|Komodo Edit]]</translate>
** <translate> [[Configuring Komodo Edit for Joomla Code Completion]]</translate>
* <translate> [[wikipedia:NetBeans|NetBeans]]</translate>
* <translate> UltraEdit, Notepad++...</translate>
*<translate> Sublime Text 2 Editor</translate>
**<translate> [https://code.tutsplus.com/courses/perfect-workflow-in-sublime-text-2 Perfect Workflow in Sublime Text 2 tutorial]</translate>

<translate>=== Debugging Specifics === </translate>
* <translate> [[Running Automated Tests for the Joomla CMS]]</translate>
* <translate> [[How to debug your code]]</translate>

<translate>== Using Git == </translate>
<translate> The CMS project uses the Git version control system and the CMS repository is stored on [https://github.com/joomla/joomla-cms GitHub]. Bugs are fixed in the master branch of this repository, and normally there are bug fixes and changes in the master branch that are more recent than the latest released Joomla version. For this reason, when we test and code bug fixes, we normally use the latest code from the master branch on GitHub, not the latest released version. Therefore, Bug Squad testers and coders need to understand how to use Git and the GitHub repository.</translate>

* <translate> For testing and tracking changes, please refer to [[Git for Testers and Trackers]].</translate>
* <translate> For creating your first code change (called a Pull Request), see [[Working with git and github/My first pull request]]</translate>
* <translate> For working with Git, please see [[Git for Coders]].</translate>

<translate>== Related == </translate>
* <translate> [[Setting up your workstation for PHP development]]</translate>
* <translate> [[Joomla Issue shortcut]]</translate>
* <translate> [[Browser Shortcut Issue Tracker]]</translate>
* [[J4.x:Setting_Up_Your_Local_Environment|<translate> Setting up your local environment for Joomla 4]]</translate>
<translate> Help is appreciated finding related pages and making these pages less redundant.</translate>

<noinclude>
<translate>

[[Category:Development{{#translation:}}]]
[[Category:Tutorials{{#translation:}}]]
[[Category:Beginner_Development{{#translation:}}]]
[[Category:Server configurations{{#translation:}}]]
[[Category:Server setup local{{#translation:}}]]
[[Category:Server configurations{{#translation:}}]]
[[Category:Bug Squad{{#translation:}}]]
[[Category:IDE (Integrated development environment){{#translation:}}]]
</translate>
</noinclude>

Edit PHP.INI File for XDebug

2023-06-29T20:57:05Z

Cmb: URL corrections. Other text editing.

==For Windows==
Starting with version 1.7, XAMPP includes the XDebug PHP debugger, but it needs to be configured for use. To do that, we will edit the ''php.ini'' file to configure XDebug. The ''Loaded Configuration File'' tells you which ''php.ini'' file is being used. For Windows, this is normally ''c:\xampp\apache\bin\php.ini''.

<blockquote>Important note for Windows 7 & Vista users: As of August 2013 (XAMPP version 1.8.2), the file ''php_xdebug.dll'' that is included with XAMPP now works with Windows 7 & Vista. In some earlier versions of XAMPP, the distributed version of XDebug did not work correctly. The symptom of this earlier problem was that the Apache server would stop if this version of XDebug is loaded. To check that you are running the correct version of XDebug on your system, [https://xdebug.org/wizard follow these instructions] on the XDebug site.
</blockquote>

We need to edit this file to configure XDebug as follows:
# Find the line ''implicit_flush'' and set it as follows: <syntaxhighlight lang="ini">implicit_flush = On</syntaxhighlight>
# Find the section called ''[Zend]'' and comment out all of the lines by putting a semicolon (;) at the start of each line.
# Find the line: ''zend_extension = "c:\xampp\php\ext\php_xdebug.dll"'' and uncomment it.
# Find the ''[XDebug]'' section and uncomment all of the lines (except for the first comment line). For Windows, it should look like the example below:
<syntaxhighlight lang="ini">
[XDebug]
; Only Zend OR (!) XDebug
zend_extension_ts="C:\xampp\php\ext\php_xdebug.dll"
xdebug.remote_enable=true
xdebug.remote_host=localhost
xdebug.remote_port=10000
xdebug.remote_handler=dbgp
</syntaxhighlight>

You do not need to enable XDebug profiling to use XDebug to debug Joomla code. Profiling allows you to find performance bottlenecks in your PHP code. However, enabling profiling with XDebug can slow down your system substantially, so it is not recommended unless you need it. To enable XDebug profiling, add these entries to your ''php.ini'' file.
<syntaxhighlight lang="ini">
xdebug.profiler_enable=1
xdebug.profiler_output_dir="C:\xampp\tmp"
</syntaxhighlight>

For Windows 7 & Vista, you will use the file downloaded from the XDebug site. So the first line will be
<syntaxhighlight lang="ini">
zend_extension_ts="C:\xampp\php\ext\php_xdebug-2.0.0-5.2.2.dll"
</syntaxhighlight>

For PHP version 5.3 and later, the ''_ts'' has been dropped, so the first line will read:
<syntaxhighlight lang="ini">
zend_extension="C:\xampp\php\ext\php_xdebug.dll"
</syntaxhighlight>

In XAMPP 1.7.3 on Windows 7, XDebug may not work correctly if the path to the DLL file is in quotes. In this case, the line should be
<syntaxhighlight lang="ini">
zend_extension = C:\xampp\php\ext\php_xdebug-2.1.0-5.3-vc6.dll
</syntaxhighlight>

==For Linux==
We will edit the ''php.ini'' file to configure XDebug. The ''Loaded Configuration File'' in your ''phpinfo'' display tells you what ''php.ini'' file is being used. For Linux, it will be something like ''/etc/php/7.2/apache2/php.ini''. (The PHP configuration is available in the Administrator of your website: {{rarr|Administrator,System,System Information,PHP Information}} tab''.)

Edit this file to configure XDebug as follows:
# Find the line ''implicit_flush'' and set it as follows: <syntaxhighlight lang="ini">implicit_flush = On</syntaxhighlight>
# Add the following lines at the end: <syntaxhighlight lang="ini">
;xDebug Configuration starts

zend_extension = /opt/lampp/lib/php/extensions/no-debug-non-zts-20090626/xdebug.so

xdebug.profiler_output_dir = "/tmp/xdebug/"
xdebug.profiler_enable = On
xdebug.remote_enable=On
xdebug.remote_host="localhost"
xdebug.remote_port=10000
xdebug.remote_handler="dbgp"

;xDebug Configuration ends </syntaxhighlight>

===If Using ''php5-xdebug'' on Ubuntu===
The xDebug Configuration detailed above can be appended to:
<syntaxhighlight lang="ini">/etc/php5/apache2/conf.d/xdebug.ini </syntaxhighlight>
It should already contain the ''zend_extension'' variable and only needs the following variables added:
<syntaxhighlight lang="ini">
xdebug.profiler_enable = On
xdebug.remote_enable=On
xdebug.remote_host="localhost"
xdebug.remote_port=10000
xdebug.remote_handler="dbgp"</syntaxhighlight>

===Tip for Users with LAN or Remote Servers===
<syntaxhighlight lang="ini">xdebug.remote_host="localhost"</syntaxhighlight>
Should be set to the IP address of your Eclipse workstation [LAN users] or your public IP. For example:
<syntaxhighlight lang="ini">xdebug.remote_host=192.168.0.199</syntaxhighlight>

==For Mac OS X==
XAMPP for Mac OS X includes the XDebug PHP debugger, but it needs to be added to the ''php.ini'' file so that XDebug runs when Apache is started. To do this, open up the ''php.ini'' file, located at ''/Applications/XAMPP/xamppfiles/etc/php.ini''.

Edit this file to configure XDebug:
# Find the line ''implicit_flush'' and set it as follows: <syntaxhighlight lang="ini">implicit_flush = On</syntaxhighlight>
# Add the following lines at the end:
<syntaxhighlight lang="ini">
;xDebug Configuration starts

zend_extension="/Applications/XAMPP/xamppfiles/lib/php/php-5.3.1/extensions/no-debug-non-zts-20090626/xdebug.so"

xdebug.profiler_output_dir = "/tmp/xdebug/"
xdebug.profiler_enable = On
xdebug.remote_enable=On
xdebug.remote_host="localhost"
xdebug.remote_port=10000
xdebug.remote_handler="dbgp"

;xDebug Configuration ends
</syntaxhighlight>

Be sure to navigate to the directory where you targeted the extension and verify that the file path is correct. The folders in your XAMPP installation may be named differently.

The current (as of Sept 2010) version of the XAMPP binary for OS X contains the 2.0.4 version of XDebug which will not let you see the variable data from included files when running XDebug. You can download a newer version from the [https://code.activestate.com/komodo/remotedebugging/ ActiveState website]. Unzip and copy one of the ''xdebug.so'' files to ''/Applications/XAMPP/xamppfiles/lib/php/php-5.3.1/extensions/no-debug-non-zts-20090626''.

==Test the XDebug Installation==
Now we need to verify that XDebug is installed correctly. Restart XAMPP. In Windows, we can just browse to the ''c:\xampp'' folder in Windows Explorer and double-click the program ''xampp-control.exe'' to open the application shown below.

[[Image:Xampp-control.png]]

Press the ''Stop'' button for ''Apache''. The button with then read ''Start''. Press ''Start'' for Apache and wait a few seconds and the green ''Running'' message will again display. Then press ''Exit'' to close the application.

In Windows, if you get ''ERROR: MySQL service not started [-1]'', you may be able to correct this by going to ''c:\xampp\mysql'' and running ''mysql_uninstallservice.bat'' followed by ''mysql_installservice.bat''.

In Linux, to restart LAMPP execute the command:
<syntaxhighlight lang="shell">
sudo /opt/lampp/lampp restart
</syntaxhighlight>

In Mac, open the ''XAMPP Control'' application, stop, and then start the Apache service.

Once XAMPP has been restarted, open a browser and navigate to http://localhost to display the XAMPP welcome message. (If you set XAMPP to listen to another port, you must append the port to the URL. For example: http://localhost:8080/). Press the ''phpinfo()'' link again to display the PHP information screen. Scroll down to the lower part of the screen. You should see a section for ''XDebug'' as shown below.

[[Image:Phpinfo_xdebug.png]]

Look at the settings you entered in the ''php.ini'' file above. You should see these same settings in the XDebug display, as shown below.

[[Image:Xdebug settings.png]]

At this point, XDebug is set up correctly.

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

How to debug your code

2023-06-29T20:04:08Z

Cmb: Corrected some URLs.

<noinclude><languages /></noinclude>
<translate>
==The Easy Way 1 (''echo'')== 
</translate>
<translate> The simplest way to see what is going on inside your code is to temporarily add ''echo'' statements for variables to show their values on the screen. For example, say you want to know what the value of some variables are when $i is "5". You could use code like this:</translate>

<syntaxhighlight lang="PHP">for ( $i = 0; $i < 10; $i++ ) {
if ( $i == 5 ) {
echo '$i=' . $i;
// other echo statements
}
}</syntaxhighlight>

<translate> This works for simple situations. However, if you are planning on doing a lot of Joomla! development, it is worth the effort to install and learn an integrated development environment (IDE) that includes a real PHP debugger.</translate>

<translate>
==The Easy Way 2 (Joomla ''message'')== 
</translate>
<translate> Your code won't always display simple echo statements. In that case you can try this alternative, still an easy way:</translate>
<syntaxhighlight lang="PHP">JFactory::getApplication()->enqueueMessage('Some debug string(s)');</syntaxhighlight>
<translate> You can choose different [[Display_error_messages_and_notices|message types]] which correspond to grouping with different styles (colors mainly).</translate>

<translate>
==Joomla Logging== 
</translate>
<translate> Joomla allows you to log messages to a log file, and optionally also display these on the web page (in the same way as ''enqueueMessage'' above) and on the Joomla Debug Console (described below).</translate>

<translate> To log a message in the log file:</translate>
<syntaxhighlight lang="PHP">
JLog::add('my error message', JLog::ERROR);
</syntaxhighlight>
<translate> To log a message and also display it on the screen:</translate>
<syntaxhighlight lang="PHP">
JLog::add('my error message', JLog::ERROR, 'jerror');
</syntaxhighlight>
<translate> Logging to the log file and to the Debug Console is controlled via the settings of the System – Debug plugin. To understand how this works, and the relevant settings of the System-Debug plugin, read the Joomla documentation page on [[S:MyLanguage/Using JLog|Using JLog]].</translate>

<translate>
==Using an IDE== 
</translate>
<translate> Check this </translate>[https://www.youtube.com/watch?v=sP4dHAuq2kc 3 minute video]
<translate> that shows how you can debug your code with a browser and an IDE</translate>.

{{#ev:youtube|sP4dHAuq2kc}}

<translate> Many Joomla! developers use the Eclipse IDE. This is free and includes a debugger. Instructions for installing it are available at [[S:Mylanguage/Setting up your workstation for Joomla development|Setting up your workstation for Joomla development]], or you can watch this video on setting up Eclipse and Xdebug.</translate>

{{#widget:YouTube|id=MiIEF8-XAkc}}
<translate>
==Using the PHP Expert Editor== 
</translate>
<translate> Another option is the PHP Expert editor with an installed extension for debugging. Add the following lines to the ''php.ini'' file:</translate>

extension=php_dbg.dll
[Debugger]
debugger.enabled=on
debugger.profiler_enabled=off

<translate> It is best to set ''profiler_enable'' to ''off''. Then you need to set options in the Run/Options menu to use HTTP-server and the directory in which your script is located.</translate>
<translate>

If all options are correct, you may run your script in debug mode by clicking on the Debug button (F8).</translate>

<translate>
==J!Dump== 
</translate>
<translate> An often handy extension that can be found in the JED is the J!Dump extension that will allow you to dump variable, stack traces, and system information into a popup window at run time. This extension works like the PHP command ''var_dump'' but formats the output in a more readable fashion.</translate>

<translate>
==Joomla Debug Console== 
</translate>
<translate> The Debug Console can be enabled from the Joomla! Global Configuration, System tab, by setting the Debug System option to Yes. Once enabled, the output of the debug plugin will be displayed at the bottom of each page.</translate>
[[File:Jdebug-module-<translate> en</translate>.jpg|<translate> The JDebug Plugin output</translate>]]

<translate> Setting this Debug System option also sets the global variable ''JDEBUG'' to true, so that you can control whether to log messages by testing this variable:</translate>
<syntaxhighlight lang="PHP">
if(JDEBUG)
{
// whatever debugging code you want to run, e.g.
JLog::add('my debug message', JLog::DEBUG, 'my-debug-category');
}
</syntaxhighlight>

<translate>

This plugin provides information that can assist in debugging and improving the performance of your component.</translate>

<translate>
===Session Information=== 
</translate>

<translate> This section displays state variables which are stored in the Session data to enable them to be 'remembered' across HTTP requests. Examples include variables defining the current search filters the user has defined, the pagination point in a list of records, etc.</translate>

[[File:session-<translate> en</translate>.jpg]]

<translate>
===Profile Information=== 
</translate>

<translate> The Profile Information tab from the debug plugin provides information about the time and memory taken to render the page based on each of the application events. This can help to identify areas outside of network speed that are contributing to long page load times and high server memory usage.</translate>

[[File:Jdebug-profile-<translate> en</translate>.jpg|<translate> JDEBUG Profile</translate>]]

<translate>
===Database Queries=== 
</translate>

<translate> One of the most useful tabs is the Database Queries tab. This will provide a log of all queries that have been executed while loading the page and identify both the time taken to execute the query and whether duplicate queries have occurred. This is particularly useful when debugging performance problems on larger components as duplicate queries are often a contributing factor.</translate>

[[File:Jdebug-query-<translate> en</translate>.jpg]]

<translate>
==Komodo IDE== 
</translate>

[[S:MyLanguage/Debugging Joomla with Komodo IDE|Debugging Joomla with Komodo IDE]]

<noinclude>
[[Category:Development{{#translation:}}]]
[[Category:Video{{#translation:}}]]
</noinclude>

Configuring Xdebug for PHP development/Mac

2023-06-29T17:36:55Z

Cmb: Some markup and phrasing changes.

== Configuring XDebug with MAMP ==

=== Prerequisites ===
These instructions are for Mac OS X (actually tested on version 10.9.2 Mavericks) with installed MAMP Application (actually tested on MAMP version 3.0.4).

=== Configuration Instructions ===
*Open finder and navigate to
<syntaxhighlight lang="text"> /Applications/MAMP/conf/<selected php version>/ </syntaxhighlight>
(NOTE: <selected php version> is the PHP version that you have selected in the MAMP configuration)
*Open the file ''php.ini'' with a text editor such as TextWrangler
*Find the section [xdebug]
*Uncomment the line
<syntaxhighlight lang="text">
[xdebug]
;zend_extension="/Applications/MAMP/bin/php/<selected php version>/lib/php/extensions/no-debug-non-zts-20121212/xdebug.so"
</syntaxhighlight>
by removing the semicolon character at the beginning of the line.
*Add after the line the following text, if not already existing
<syntaxhighlight lang="text">
xdebug.remote_enable=on
xdebug.remote_handler=dbgp
xdebug.remote_host=localhost
xdebug.remote_port=9000
</syntaxhighlight>
*Save changes and close the editor
*Restart your MAMP Server
Note: You can set a different port number if you need.

Configuring Xdebug for PHP development

2023-06-29T17:28:03Z

Cmb: Some capitalization and phrasing changes.

XDebug is an extension that provides debugging and profiling capabilities. It runs in the server side and sends the debugging information to any client capable of receiving and reading it. For this article we will install XDebug in our local server and use Eclipse IDE as the client which will receive and interpret the debugging information. With XDebug you will be able to study the behavior of your code step by step and also inspect the value of the any variable at every execution step.
=Linux OS=
{{:Configuring Xdebug for PHP development/Linux}}
=Windows OS=
{{:Configuring Xdebug for PHP development/Windows}}
=Mac OS=
{{:Configuring Xdebug for PHP development/Mac}}
[[Category:Development]]

Configuring Xdebug for PHP development/Linux

2023-06-29T17:23:29Z

Cmb: URL corrections. Other text editing.

Theses instructions should work fine on any Debian based distribution such as Debian, Ubuntu, Linux Mint, Xubuntu, Kubuntu and others.

== Installation ==
There are several ways to download and install XDebug to your Linux box, you can do it from your software center, terminal or manual download.

=== Method 1: From a Linux Repository ===
{{tip|This is the recommended method because you will get updates and security patches automatically.}}

==== Option 1: Terminal ====
*Open your terminal and type
<tt> sudo apt-get install php5-xdebug </tt>
*Wait until the installation process finishes

==== Option 2: Software Center ====
*Open the software center that comes with your distribution
*Type in the search box "Eclipse IDE"
*Select "Eclipse IDE" in the search result list
*Click on the "install" button
*Wait until installation processes finishes

=== Method 2: From a Downloaded Copy ===
* Visit this page [https://packages.debian.org/bookworm/php-xdebug here] and download the most recent version available
* Do a double click on the downloaded file, your package manager should do the rest of the work automatically

== Configuring XDebug ==
Open your terminal and type:

<tt>sudo gedit /etc/php5/mods-available/xdebug.ini</tt>

If the file is empty try this location:

<tt>sudo gedit /etc/php5/conf.d/xdebug.ini</tt>

That command should open the text editor with the XDebug configuration file.

At the end of the file content append the following text:

<tt>xdebug.remote_enable=on</tt>

<tt>xdebug.remote_handler=dbgp</tt>

<tt>xdebug.remote_host=localhost</tt>

<tt>xdebug.remote_port=9000</tt>

Save changes and close the editor.

In your terminal, type:

<tt>sudo service apache2 restart</tt>

Note: You can set a different port number if you need to.

== Configuring Eclipse IDE ==
*Open Eclipse IDE.
*On Eclipse go to: {{rarr|Toolbar,Window,Preferences,PHP,Debug}}
*Find the option: "PHP Debugger" and set it to "Xdebug"
*On Eclipse go to: {{rarr|Toolbar,Window,Preferences,PHP,Debug,Installed Debugger}}
*In the list make sure the port the "Xdebug" option is set to the value "9000"
*Save changes.
Note: You can set a different port number if necessary.

When you debug a PHP project, Xdebug stops the code execution of the current page and Eclipse IDE by default pops out a perspective with 2 views containing the internal Eclipse IDE web browser and a view with the current HTML output. If you don't like the internal web browser, you can use any other external web browser installed in your computer, such as Google Chrome, Chromium, Firefox and so on.

To set up a different web browser, follow these steps. If you are okay with the Eclipse internal browser, skip this part.

*On Eclipse, go to: {{rarr|Toolbar,Window,Preferences,General,Web Browser}}
*Make sure the option "Use external browser" is selected.
*If your preferred browser is on the list, select it and save changes. Skip the rest of this part.
*If your preferred browser is not on the list, press the button "New"
*Set a name for your new browser, that is "chrome".
*Set the location of your new browser, that is "/usr/bin/google-chrome"
*If you don't know the location of the browser, open a terminal and use the command "whereis browsername" to display the browser location. Note: Replace browsername with the name of your preferred browser, that is "whereis google-chrome". Copy one of the locations if there is more than one.
*Save all changes.

== Testing XDebug and Eclipse IDE ==
To test our new debugging tool, we need to create an Eclipse PHP project, set the debug configuration for our project and write a few lines of PHP code. This example assumes 3 things:
# You understand the Eclipse IDE concepts of "workspace" and "projects". If not, please read this article: [[Configuring Eclipse IDE for PHP development/Linux#Understanding the folder structure]]
# You already have a working web server. If not, please read this article: [[Configuring a LAMPP server for PHP development/Linux desktop]]
# Your Eclipse workspace is located at the server's web root folder.
=== Configuring the Workspace ===
*If your current workspace is located at your server's web root, skip this part.
*Open Eclipse IDE.
*On Eclipse, go to: {{rarr|Toolbar,File,Switch,Workspace,Other}}
*Press the button "browse" and browse to the location of your server's web root folder. For example, "/home/youruser/lamp/public_html/"
*Press "OK" and wait until Eclipse IDE restarts and load the new workspace.
=== Configuring the Test Project ===
*On Eclipse go to: {{rarr|Toolbar,File,New,Other,PHP,PHP Project}}
*Set the project name to "xdebug-test" or anything you like.
*Press "Ok" to continue.
*After this Eclipse IDE will automatically create a project folder like this "/home/youruser/lamp/public_html/xdebug-test/". Also you should be able to visualize the new project at the Eclipse IDE Project Explorer view or Navigation view.
*On Eclipse go to: {{rarr|Toolbar,File,New,Other,PHP,PHP File}}
*Set the file name to "index.php".
*Press "Ok" to continue.
*After this Eclipse IDE will automatically create a PHP file like this "/home/youruser/lamp/public_html/xdebug-test/index.php". Also you should be able to visualize the new file at the Eclipse IDE Project Explorer view or Navigation view.
*Find the new "index.php" file at the Eclipse IDE project explorer and open it by double clicking on it.
*Place the following content to that file:
<syntaxhighlight lang="php">
<?php
$X = 5;
$X = 8;
$Y = 2;
$Z = $X + $Y;
$Z = $Z + 1;
echo "Z value is: " . $Z;
?>
</syntaxhighlight>
*Save the changes.
*Open your web browser and navigate to "http://localhost/xdebug-test/index.php"
*It should display a web page and output like this:
<tt>Z value is: 11</tt>
=== Configuring the Test Project Debug Information ===
*On Eclipse, go to: {{rarr|Toolbar,Run,Debug configuration...}}
*On the left list, find ''PHP Web Application'' and do a double click on it to create a new configuration element.
*Select the new configuration element to display its contents.
*Set the name to ''xdebug-test'' or anything you like.
*Make sure the option "Server debugger" is set to "XDebug".
*Make sure the option "Break at first Line" is not checked.
*In the option "File" press the button "Browse". Find your project "xdebug-test" and expand its contents. Then find and select the file "index.php".
*Make sure that option URL looks something like this "http://localhost/xdebug-test/index.php"
*Press "Apply" and "Close" to save changes and continue.
=== Debugging the Test Project ===
As you can see, our "index.php" file has several lines of code. With the debugger, we can study how those lines of code are executed one by one. To stop the execution, we need to set something called "Breakpoint". A Breakpoint is a "mark" in our lines of code that indicate to the debugger to stop the execution and poll the var values. To set a Breakpoint on our code and test the debugger, follow these simple steps.

*Open the "index.php" of our test project.
*Locate the line of code "$X = 8;" and do a click on it to place the blinking cursor there.
*On Eclipse go to: {{rarr|Toolbar,Run,Toggle Breakpoint}}. You can also used the hotkey "shift+ctrl+B" or simply do a double click on the line number of the line of code at the left side of your editor to toggle a Breakpoint.
*When a Breakpoint is set, you should see it represented as a little circle next to the line number at the left side of your editor.

Now is the time to execute our project to see how the debugger helps us.

*On Eclipse, go to: {{rarr|Toolbar,Run,Debug}}. You can also used the hotkey "F11" or simply do a click in the "little bug icon" located at the second toolbar from the top.
*Eclipse will open the configured web browser and change to the "Debug perspective". The debug perspective contains a set of pre-configured views useful to do debugging tasks. Among them we have:
**Debug view: It displays buttons to control the current running debug session. This view contains the current [[wikipedia:Call_stack | call stack]].
**Breakpoint view: display all your set breakpoints on any project file.
**Variables view: It's basically a "var dump" of all the PHP variables of your actual session. This view lets you easily navigate through any variable and child members of those variables.
**Expressions view: here you can set custom expressions, for instance, "$X+$Y+$Z" and see the outcome of each expression without changing the code.
**Internal browser view and output view: optional if you not configured an external browser, Eclipse IDE will display this view with the current page and the current page HTML output.
*At this point our web page should look stopped and most likely the browser will show a blank page "waiting" to load the rest of it.
*Note that the current breakpoint has a "little arrow" over the circle and the line of code is highlighted. This indicates the next line of code to be executed, also know as the "current step".
*If you take a look at the "variables view", the current value of "$X" should be "5".
*Go to the "Debug view" and press the button "step over" or use the hotkey "F6" to go one [http://www.youtube.com/watch?v=LAUcTGeqvOw step forward] in the code execution.
*Take another look at the "variables view". The current value of "$X" should be now "8".
*This way you can neatly study how your code and values changes step by step. You can also hover your mouse pointer over the variables names in the editor. Eclipse will pop up the current values.
*Keep going forward until the end of the lines of code. At that point the web browser should display the final web page output.

[[Category:Development]]

Configuring Xdebug for PHP development/Windows

2023-06-29T17:13:08Z

Cmb: URL corrections. Other text editing.

{{incomplete}}
Configuring XDebug is split into two parts: Server-side and Client-side.

== Server-side (Extension in PHP) ==

=== Installation ===
First check if this extension is already installed. Create a new file with the content ''<?php phpinfo(); ?>'', save it in your web folder (e.g. ''C:\xampp\htdocs\phpinfo.php'') and call it using your browser (https://localhost/phpinfo.php). The command ''phpinfo'' will show you the information about installed plugins and their configuration. If you see a headline called XDebug, it is already downloaded and enabled.

To get the extension for a Windows system, you have to download the DLL file from https://xdebug.org/download that fits your PHP version, move it into the ''ext'' folder of your PHP installation. If the file ''php_xdebug.dll'' exists, leave it there. It's most likely the right version, just that it's not enabled.

=== Enable XDebug ===
On Windows systems you most likely just have one ''php.ini'' file for all configuration whereas on several Linux distributions you have a directory called ''conf.d'' in addition. If you have installed XDebug on a Linux-based system, you'll probably find a file ''xdebug.ini''. Use this file instead if you have it.

Enable the plugin by adding (or uncommenting) the following line in your config file:
<syntaxhighlight lang="ini">
; Example for XAMPP
zend_extension = "\xampp\php\ext\php_xdebug.dll"

; Example on Mac OS X for XAMPP
zend_extension="/Applications/XAMPP/xamppfiles/lib/php/php-5.3.1/extensions/no-debug-non-zts-20090626/xdebug.so"
</syntaxhighlight>

Make sure you use ''zend_extension'' instead of ''extension'' which requires the full path to the extension-file.

=== Configuration ===
Also read this introduction for configuration details: https://xdebug.org/docs/step_debug

Here is an example configuration:
<syntaxhighlight lang="ini">
; location of my configuration-file
zend_extension=/usr/lib/php5/20090626/xdebug.so

; Enables colors if you use XDebug on the console
xdebug.cli_color=1

; Enable profiler by a trigger (f.e. cookie or GET-param)
xdebug.profiler_enable_trigger=1
xdebug.profiler_output_dir=/var/www/log/

; Debugger will try to connect back to the machine sending the HTTP-Request
xdebug.remote_connect_back=1

; Enables the debugger
xdebug.remote_enable=1
</syntaxhighlight>

== Client-side (Configure Your IDE) ==
If your IDE is not listed on https://xdebug.org/docs/step_debug#clients, you'll probably find a tutorial in the manual of your IDE.
Feel free to add helpful tutorials here.

Testing Checklists

2023-06-28T20:05:50Z

Cmb: Corrected a parentheses mismatch.

<noinclude><languages /></noinclude>

<translate>

This article is designed to help Joomla! Bug Squad members as they test New issues and Pending issues.
</translate>

<translate>
=== Testing New Issues === 
The ''New'' status indicates that no member of the Joomla! Bug Squad has evaluated this issue. The goal is to learn enough about the issue to be able to change the status to one of the following: ''Unconfirmed Report'', ''Known Issue'', ''Duplicate Report'', ''Confirmed'' or ''Information Required''. See [[S:MyLanguage/Bug Tracking Process#Resolving Issues | Bug Tracking Process]] for details about these status codes.
</translate>

<translate>

Here is a checklist for testing ''New'' issues:
</translate>
<translate>
* Did you carefully read the entire description and any other comments?
* Is there enough information provided? If not, add a comment and change to ''Information Required''.
* Did you search the tracker to see if this issue has already been reported? If so, add a comment and change to ''Duplicate Report''.</translate>
<translate>
* Is the issue a known issue or limitation? If so, add a comment and change to ''Known Issue''.
* Is the issue an enhancement request? If so, change status to ''Discussion''.</translate>
<translate>
* Before testing, did you update your local GIT repository to get the latest GIT Joomla! version? (See [[S:MyLanguage/Git for Testers and Trackers|Git for Testers and Trackers]])
* If you couldn't duplicate the problem with the latest GIT version, did you test using the latest production version?
* If the issue is still unconfirmed, try to to reproduce the issue with different cache settings.</translate>
<translate>
* Try to localize the problem by changing your cache settings.
* If you changed the issue to ''Confirmed'', did you make sure there is a detailed test plan in the comments to allow someone who is not familiar with the issue to understand and test the issue?</translate>

<translate>
=== Testing Pending Issues === 
</translate>
<translate>

A ''Pending'' issue is one that (a) has been confirmed, (b) has a detailed test plan, and (c) has a proposed patch to be tested. ([[S:MyLanguage/My_first_pull_request_to_Joomla!_on_Github|Learn more about creating your first pull request]]). Here is a checklist for testing ''Pending'' issues:
</translate>
<translate>
* Is there a test plan for the issue shown in the ''Test Instructions'' field? If not, post a comment and change status to ''Information Required''.
* Before testing, did you update your local GIT repository to get the latest GIT Joomla! version?
* Did you test the issue '''before''' applying the patch to make sure you can confirm the problem?</translate>
<translate>
* Did you test the issue after applying the patch to make sure the problem is fixed?
* Are there any other test cases that should be considered? Examples might include:</translate>
<translate>
** template override files (especially Beez template)
** testing with SEF or ''mod_rewrite'' enabled and disabled
** language file issues (Test with Debug Language set to Yes.)
** PHP warnings (Test with ''Error Reporting'' set to ''Maximum'').</translate>
<translate>
* If your test is successful and you are the first tester, indicate in your comment that a second test is needed. If you are the second tester, change the status to ''Ready to Commit''.
* Remember to revert the changes made by the patch after you are done testing.</translate>

<translate>=== Testing Code Snippets === 
Sometimes to test a patch you will need to test PHP code snippets. One simple way to do this is:</translate>
<translate>
# Create a new folder called ''com_test'' under the components folder.
# Create a new file called ''test.php'' under this folder.
# Put your PHP code snippet in this file.
# To run the file, just enter the URL ''<your domain>/index.php?option=com_test''. For example, ''<nowiki>http://localhost/joomla_development/index.php?option=com_test</nowiki>''.</translate>

<translate>
This will run the code snippet inside the Joomla! framework. This way, when you are done, you can just remove the ''com_test'' folder and no other files have been changed. (Sam, thanks for this tip!)</translate>
<translate>

=== General Tips & Tricks === 
* If you have the cache enabled ({{rarr|Global Configuration,System,Cache Settings}}), you will need to clean the cache each time you make a change to the code or parameters. Otherwise, you might be seeing the older cached version of the page. Unless you are specifically testing the cache feature, test with the Cache set to ''No''.
</translate>

<translate>

* Set Error Reporting to ''Maximum'' and enable all debugging options in Global Configuration.
</translate>

<translate>

[[Category:Bug Squad]]
[[Category:Testing]]
</translate>

Visual Studio Code

2023-06-28T17:30:55Z

Cmb: Corrected some URLs.

<noinclude><languages /></noinclude>
<translate>

[https://code.visualstudio.com/ Visual Studio Code (VSCode)] is a source code editor developed by Microsoft for Windows, Linux and MacOS (including M1 Macs). It includes support for debugging, embedded Git control and GitHub, syntax highlighting, intelligent code completion, snippets, and code refactoring.


The main characteristic of the editor is that it is extensible and it has a huge collection of extensions maintained by users and by Microsoft itself. See details at the [https://marketplace.visualstudio.com/ VSCode Extensions for Visual Studio Code] website.


As a general introduction, this is a presentation about the topic [https://www.renekreijveld.nl/slides/juglondon/vscode.pdf Joomla Development with Visual Studio Code], by René Kreijveld, Joomla developer Destiny B.V. Joomla User Group London, 16th march 2021.


On this page, we detail a list of recommended extensions to configure VSCode to support PHP and Joomla.


This is a list of extensions to support PHP on VSCode:


* '''PHP Debug''' [https://marketplace.visualstudio.com/items?itemName=felixfbecker.php-debug felixfbecker.php-debug]. Debug support for PHP with XDebug.
* '''phpcs''' [https://marketplace.visualstudio.com/items?itemName=ikappas.phpcs ikappas.phpcs]. PHP CodeSniffer for Visual Studio Code.
* '''PHP Intelephense''' [https://marketplace.visualstudio.com/items?itemName=bmewburn.vscode-intelephense-client bmewburn.vscode-intelephense-client]. PHP code intelligence for Visual Studio Code. Alternative: ''PHP IntelliSense'' [https://marketplace.visualstudio.com/items?itemName=felixfbecker.php-intellisense felixfbecker.php-intellisense]
* '''PHPUnit''' [https://marketplace.visualstudio.com/items?itemName=emallin.phpunit emallin.phpunit]. Run PHPUnit tests from VSCode.
* '''phpfmt''' [https://marketplace.visualstudio.com/items?itemName=kokororin.vscode-phpfmt kokororin.vscode-phpfmt]. The missing phpfmt extension for Visual Studio Code. The phpfmt formatter can parse and format even a PHP file version 4 if needed.
* '''php cs fixer''' [https://marketplace.visualstudio.com/items?itemName=junstyle.php-cs-fixer junstyle.php-cs-fixer]: In case of opting for the [https://www.php-fig.org/psr/psr-2/ PSR-2: Coding Style Guide]). PHP CS Fixer extension for VS Code, PHP formatter, PHP code beautify tool, format HTML.
* '''PHP Namespace Resolver''' [https://marketplace.visualstudio.com/items?itemName=MehediDracula.php-namespace-resolver MehediDracula.php-namespace-resolver]: PHP Namespace Resolver can import and expand your class. You can also sort your imported classes by line length or in alphabetical order.
* '''PHP Phan (Analyzer)''' [https://marketplace.visualstudio.com/items?itemName=TysonAndre.php-phan tysonandre.php-phan]. Phan - static analyzer for PHP, minimizing false positives.
* '''phpmd''' [https://marketplace.visualstudio.com/items?itemName=linyang95.phpmd linyang95.phpmd]. VS Code extension for PHP, using PHPMD.


The Git protocol is natively supported on VSCode. However, there are extensions to improve code and repository management. This is a list of featured extensions for this task:


* '''Git History''' [https://marketplace.visualstudio.com/items?itemName=donjayamanne.githistory donjayamanne.githistory]: Git History, Search and More (including git log).
* '''GitHub''' [https://marketplace.visualstudio.com/items?itemName=KnisterPeter.vscode-github KnisterPeter.vscode-github]: This VSCode extension integrates with GitHubExtensions for Visual Studio Code
* '''GitHub Pull Requests and Issues''' [https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-github GitHub.vscode-pull-request-github]: Review and manage your GitHub pull requests and issues directly in VS Code
* '''gitignore''' [https://marketplace.visualstudio.com/items?itemName=codezombiech.gitignore codezombiech.gitignore]: A extension for Visual Studio Code that assists you in working with ''.gitignore'' files.
* '''Visual Studio Code Commitizen Support''' [https://marketplace.visualstudio.com/items?itemName=KnisterPeter.vscode-commitizen KnisterPeter.vscode-commitizen]: This VSCode extension adds ''commitizen'' support.


This is a list of extensions to support Joomla on VSCode:


* '''Joomla Snippets''' [https://marketplace.visualstudio.com/items?itemName=AnibalSanchez.vs-code-joomla-snippets anibalsanchez.vs-code-joomla-snippets]. Snippets for Joomla including Joomla 3.x and Joomla 4 Snippets.
* '''PHP Getters & Setters''' [https://marketplace.visualstudio.com/items?itemName=phproberto.vscode-php-getters-setters phproberto.vscode-php-getters-setters]. Create PHP getters and setters from class properties.


This is a list of extensions to support remote SSH development:


* '''Remote - SSH''' [https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh ms-vscode-remote.remote-ssh]: The Remote - SSH extension lets you use any remote machine with an SSH server as your development environment. This can greatly simplify development and troubleshooting in a wide variety of situations. For more information: [https://code.visualstudio.com/docs/remote/ssh-tutorial Remote development over SSH]
* '''Live Share''' [https://marketplace.visualstudio.com/items?itemName=MS-vsliveshare.vsliveshare MS-vsliveshare.vsliveshare]: Visual Studio Live Share enables you to collaboratively edit and debug with others in real-time, regardless of what programming languages you're using or app types you're building. It allows you to instantly (and securely) share your current project, and then as needed, share debugging sessions, terminal instances, localhost web apps, voice calls, and more!


This is a list of handy extensions highly recommended to ease the development:


* '''EditorConfig for VS Code''' [https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig editorconfig.editorconfig] EditorConfig Support for Visual Studio Code.
* '''change-case''' [https://marketplace.visualstudio.com/items?itemName=wmaurer.change-case wmaurer.change-case]: Quickly change the case (camelCase, CONSTANT_CASE, snake_case, etc) of the current selection or current word.
* '''Project Manager''' [https://marketplace.visualstudio.com/items?itemName=alefragnani.project-manager alefragnani.project-manager]: It helps you to easily access your projects, no matter where they are located. Don't miss those important projects anymore.

== PHP Debug Configuration == 


The extension supports the most common configurations of PHP [https://xdebug.org/ XDebug]. It fully integrates all VSCode features to debug PHP scripts.


To configure the extension, visit the [https://github.com/xdebug/vscode-php-debug#installation official documentation].


As a sample configuration for VSCode debugging, this is a common ''launch.json'':


<syntaxhighlight lang="javascript">
{
// Use IntelliSense to learn about possible attributes.
// Hover to view descriptions of existing attributes.
// For more information, visit: https://code.visualstudio.com/docs/editor/debugging#_launch-configurations
"version": "0.2.0",
"configurations": [


{
"name": "Listen for XDebug",
"type": "php",
"request": "launch",


// Server Remote XDebug Port - 9000 is the default XDebug port
"port": 9000,


// Server Remote Path -> Local Project Path
"pathMappings": {
"/app/www": "${workspaceRoot}/www"
}
},
{
"name": "Launch currently open script",
"type": "php",
"request": "launch",
"program": "${file}",
"cwd": "${fileDirname}",


// Local XDebug Port - 9000 is the default XDebug port
"port": 9000
}
]
}
</syntaxhighlight>


Related to the ''launch.json'' configuration that ''felixfbecker/vscode-php-debug'' requires, it is the configuration of PHP XDebug itself.


At this time, your development environment could have ''xdebug-2'' or ''xdebug-3''. They differ in the required parameters. To configure PHP XDebug, these are the most common settings for ''php.ini'':

=== XDebug 2 Configuration === 


<syntaxhighlight>
[XDebug]
;;;;;;;;;;;;;;;;;;;
; xdebug-2.9.8
;;;;;;;;;;;;;;;;;;;
xdebug.remote_enable = 1
xdebug.remote_autostart = 1
; xdebug.remote_port = 9000
</syntaxhighlight>

=== XDebug 3 Configuration === 


<syntaxhighlight>
[XDebug]
;;;;;;;;;;;;;;;;;;;
; xdebug-3.0.0
; https://xdebug.org/docs/upgrade_guide
;;;;;;;;;;;;;;;;;;;
xdebug.mode = debug
xdebug.start_with_request = yes
xdebug.discover_client_host = true
; xdebug.client_port = 9000
</syntaxhighlight>


To know more about how XDebug works internally to connect to the Editor, check the [https://xdebug.org/docs/ Xdebug 3 — Documentation].

== ''phpcs'' Configuration == 


To configure the extension, visit the [https://marketplace.visualstudio.com/items?itemName=ikappas.phpcs official documentation].


The extension supports the most common configurations of [https://pear.php.net/package/PHP_CodeSniffer/ PHP_CodeSniffer].


By default, PHP_CodeSniffer comes with several coding standards. Once the extension is installed, it works with ''PSR2''.


<syntaxhighlight lang="javascript">
"phpcs.standard": "PSR2",
</syntaxhighlight>


To configure the extension to apply the '''Joomla! Coding Standards''', install the rules following the [https://developer.joomla.org/coding-standards/html.html official guide].


Once '''Joomla! Coding Standards''' is installed, configure the User Settings following this sample configuration:


<syntaxhighlight lang="javascript">
"phpcs.standard": "/home/YOUR-USER/.../Joomla",
</syntaxhighlight>

== Configuration of PHP Intelephense == 


To configure the extension, visit the [https://github.com/bmewburn/vscode-intelephense#quick-start official documentation].


The extension does not require additional configuration.


VSCode comes with basic support of the PHP language. It is a good idea to disable the default support to avoid conflicts:


<syntaxhighlight lang="javascript">
// Disable basic suggestions
"php.suggest.basic": false,


// To activate code suggestions in comments
"editor.quickSuggestions": { "comments": true },
</syntaxhighlight>


As an alternative, it is also a popular extension: '''PHP IntelliSense''' [https://marketplace.visualstudio.com/items?itemName=felixfbecker.php-intellisense felixfbecker.php-intellisense] Advanced Autocompletion and Refactoring support for PHP.

== PHPUnit Configuration == 


To configure the extension, visit the [https://github.com/elonmallin/vscode-phpunit#setup official documentation].


The extension integrates [https://phpunit.de/ PHP Unit] with VSCode, so all features of PHP Unit are integrated with VSCode and can also be parameterized for further integration with the user interface.


This is a sample configuration of the extension:


<syntaxhighlight lang="javascript">
"phpunit.preferRunClassTestOverQuickPickWindow": true,
"phpunit.driverPriority": [
"Path",
"Command",
"Composer",
"Phar",
"Ssh",
"GlobalPhpUnit"
],
</syntaxhighlight>

== PHP CS Fixer Configuration (Only for PSR2) == 


To configure the extension, visit the [https://github.com/junstyle/vscode-php-cs-fixer#installation official documentation].


The extension integrates [https://github.com/PHP-CS-Fixer/PHP-CS-Fixer PHP CS Fixer] with VSCode, so all features of PHP CS Fixer are integrated with VSCode and can also be parameterized for further integration with the user interface.


To automatically apply PHP CS Fixer to PHP files, configure the user settings in this way:


<syntaxhighlight lang="javascript">
"[php]": {
"editor.defaultFormatter": "junstyle.php-cs-fixer",
},
"php-cs-fixer.onsave": true,
</syntaxhighlight>

== PHP Phan (Analyzer) Configuration == 


To configure the extension, visit the [https://marketplace.visualstudio.com/items?itemName=TysonAndre.php-phan official documentation].


This is a sample configuration of the extension:


<syntaxhighlight lang="javascript">
"phan.phpExecutablePath": "/usr/bin/php",
"phan.analyzedFileExtensions": [
"php"
],
</syntaxhighlight>

== ''phpmd'' Configuration == 


To configure the extension, visit the [https://github.com/xdebug/vscode-php-debug#installation official documentation].


The extension does not require additional configuration.


This is a sample configuration of the extension:


<syntaxhighlight lang="javascript">
"phpmd.command": "php /home/YOUR-USER/.../phpmd/phpmd.phar",
"phpmd.rules": "/home/YOUR-USER/.../phpmd-rulesets/phpmd_config.xml",
</syntaxhighlight>

== Configure EditorConfig for VS Code == 


EditorConfig is a file format and collection of text editor plugins for maintaining consistent coding styles between different editors and IDEs.


To configure the editor according to your preferences, create a file ''.editorconfig'':


<syntaxhighlight lang="javascript">
; EditorConfig helps developers define and maintain consistent
; coding styles between different editors and IDEs.


; For more visit https://editorconfig.org/
root = true


; Choose between lf or rf on "end_of_line" property
[*]
charset = utf-8
end_of_line = lf
indent_size = 2
indent_style = space
insert_final_newline = true
trim_trailing_whitespace = true


# editorconfig-tools is unable to ignore longs strings or URLs
max_line_length = null


[*.html]
indent_style = tab


# PSR-2
# [*.php]
# indent_size = 4
# indent_style = space


# Joomla! Coding Standards
[*.php]
indent_size = 4
indent_style = tab


[*.md]
trim_trailing_whitespace = false


[*.yml]
indent_style = space
indent_size = 2
</syntaxhighlight>
</translate>

<noinclude>
<translate>

[[Category:Development{{#translation:}}]]
[[Category:Beginner_Development{{#translation:}}]]
[[Category:Server configurations{{#translation:}}]]
[[Category:Server setup local{{#translation:}}]]
[[Category:Server configurations{{#translation:}}]]
[[Category:Bug Squad{{#translation:}}]]
[[Category:IDE (Integrated development environment){{#translation:}}]]
</translate>
</noinclude>

Visual Studio Code Primer

2023-06-27T21:59:28Z

Cmb: Changed 'sill' to 'still' and a few other changes.

<noinclude><languages /></noinclude>
<translate>
== VS Code - A Popular Free IDE == 
From [https://en.wikipedia.org/wiki/Visual_Studio_Code Wikipedia]:
<blockquote>Visual Studio Code, also commonly referred to as VS Code, is a source-code editor made by Microsoft for Windows, Linux and macOS. Features include support for debugging, syntax highlighting, intelligent code completion, snippets, code refactoring, and embedded Git. Users can change the theme, keyboard shortcuts, preferences, and install extensions that add additional functionality.</blockquote>

== Installation == 
The [https://code.visualstudio.com/ VS Code] site default page has a drop-down list for each supported platform. The chances are that your platform is pre-selected. So download and install and you are ready to go.

=== Getting Started === 
The VS Code ''Get Started'' page has some ''Start'' items, a list of ''Recent'' items, and a short list of ''Walkthroughs''. If you are completely new to VS Code these are recommended viewing. They only take a few minutes.


The VS Code Documentation is available from the ''Help / Documentation'' menu. The Introductory Videos are well worth viewing. Each takes 2 to 6 minutes and gives an excellent introduction to VS Code features


https://code.visualstudio.com/docs/getstarted/introvideos


The official documentation is the place to go to if you want to look up specific information.

=== VS Code Extensions === 
VS Code can be used for any type of text, including a wide range of programming languages. It works with JavaScript without adding extensions. Other languages are detected by context so if you start creating and saving PHP code you are likely to be prompted to install a PHP Support pack.


Click on the ''Extensions'' icon in the left ''Activity Bar'' to see what you have installed and what is recommended. You will need the PHP Debug extension!

=== The VS Code Screen Layout === 
Some terms used in subsequent instructions:
* '''Activity Bar:''' the narrow bar at the left of the screen. Select any icon to open or close the Primary Sidebar.
* '''Primary Side Bar:''' when open shows details of the selected activity.
* '''Status Bar:''' at the bottom of the screen. It shows what is going on.
* '''Panel:''' an area beneath the text editors to display other information.
Select a layout icon at the top right to open or close any one of these items.

== Coding a Joomla Extension == 
To create an extension your objective is to create a zip file that you can install in a working Joomla site. So you need a folder to contain your code. This should be within your personal file space on your laptop or desktop computer used for local development. It should not be in your website tree. For example you could use ''~/jextensions'' to contain subfolders for different extensions. I use ''~/git'' because it is short and easy to spell although potentially confusing because each subfolder uses a separate git repository.

=== Sample Code === 
If you would like some sample code to work on there is an extension available on GitHub named ''mod_debugme''. As the name implies, it is a module with some bugs. In addition to the module code there is a ''build.xml'' file to illustrate one way to automate building for testing and creating a zip file.


The module is designed to show the next few (3 by default) events (birthdays) from a list stored in a database table. You might imagine this being used in an office or family site in the expectation of cake.


It may be best to get going by using git commands from the command line. First create a folder for your code and then clone the remote repository:


<syntaxhighlight>
mkdir ~/git
cd ~/git
git clone https://github.com/ceford/j4xdemos-mod-debugme</syntaxhighlight>


The response should take just a few seconds:


<syntaxhighlight>
Cloning into 'j4xdemos-mod-debugme'...
remote: Enumerating objects: 23, done.
remote: Counting objects: 100% (23/23), done.
remote: Compressing objects: 100% (16/16), done.
remote: Total 23 (delta 3), reused 23 (delta 3), pack-reused 0
Unpacking objects: 100% (23/23), done.
</syntaxhighlight>


You should take a moment to look at the contents of the folder:


<syntaxhighlight>
cd j4xdemos-mod-debugme
ls -al
total 16
drwxr-xr-x 6 ceford staff 192 2 Sep 17:48 .
drwxr-xr-x 3 ceford staff 96 2 Sep 17:48 ..
drwxr-xr-x 12 ceford staff 384 2 Sep 17:48 .git
-rw-r--r-- 1 ceford staff 1402 2 Sep 17:48 README.md
-rw-r--r-- 1 ceford staff 927 2 Sep 17:48 build.xml
drwxr-xr-x 8 ceford staff 256 2 Sep 17:48 mod_debugme
</syntaxhighlight>


The ''.git'' folder contains information about the repo. The ''README.md'' file is a markdown document that describes this repo. The ''build.xml'' file is a file used to build the extension with an external tool, Phing - described later. The ''mod_debugme'' folder contains the code of the extension.

=== Install in Joomla === 
Compress the extension folder to create an installable zip file:


<syntaxhighlight>
zip -r mod_debugme.zip mod_debugme
</syntaxhighlight>


You can now install the zip file in the Joomla site you use for testing. After installation you need to create a Site module and assign it to a module position. As it is a broken module you could assign it to a position on ''All pages'' while you work on it; or you could assign it to a position on a single page; or you could position it in an article that has its own menu item.


After installation, delete the zip file.

=== Turn on Debug Mode === 
In Joomla's Global Configuration, set ''Debug System'' to ''Yes'' and ''Error Reporting'' to ''Maximum''.


When you open a page containing the buggy module you will see a stack trace telling you where an error was triggered.


[[File:J4.x-vscode-primer-stack-trace-en.png|border|800px]]


Sometimes the coding error is on the first line of the stack trace. Otherwise, if the error is triggered in library code, for example by passing invalid data to a database function, the coding error may be further down the list of function calls.

== Open Extension Folder in VS Code == 
In VS Code, use the File / Open Folder menu item to locate and open the folder containing your local copy of the ''mod_debugme'' extension code. You should see something similar to the following:


[[File:J4.x-vscode-primer-screen.png|border|800px]]


You may be able to diagnose the problem just by reading the code. In the case of the ''Class "DebugHelper" not found'' error you will see that a ''use'' statement has been commented out a few lines previously. Forgetting to insert a ''use'' statement is a common error during initial development!


Fix that problem and then compress and install the module again. That step gets a bit tedious when you have multiple problems. Which is where build tools come in useful.

== Phing == 
Phing is a command line tool, available for all platforms, used to build software packages using instructions stored in an XML file, named ''build.xml'' by default. For working with extension code it can be used to do two things:


* copy changed files from your extension source folder to the correct places in your website folder.
* generate a new zip file for new installations.


Download and install [https://www.phing.info/ Phing]. Other build tools are available! You could install Phing in your own bin folder or in a system ''bin'' folder. You need to note the path to your Phing code. In this example it is ''~/bin/phing-latest.phar''. You can try it out from the command line after changing into the folder containing your extension code:


<syntaxhighlight>
cd ~/git/j4xdemos-mod-debugme
php ~/bin/phing-latest.phar
</syntaxhighlight>


Response:


<syntaxhighlight>
Buildfile: /Users/ceford/git/j4xdemos-mod-debugme/build.xml

mod_debugme > main:
... Any copied files will be mentioned here
[zip] Building zip: /Users/ceford/zips/mod_debugme.zip

BUILD FINISHED

Total time: 0.0863 seconds
</syntaxhighlight>

== VS Code Tasks == 
To run Phing from within VS Code you need to create a ''tasks.json'' file in the ''.vscode'' folder in the root of the ''j4xdemos-mod-debugme'' folder. If the latter does not exist, create it. Then create the ''tasks.json'' file and enter the following code:


<syntaxhighlight>
{
// See https://go.microsoft.com/fwlink/?LinkId=733558
// for the documentation about the tasks.json format
"version": "2.0.0",
"tasks": [
{
"label": "Build mod_debugme",
"type": "shell",
"command": "php ~/bin/phing-latest.phar",
"windows": {
"command": "php ~/bin/phing-latest.phar"
},
"group": "build",
"presentation": {
"reveal": "always",
"panel": "shared"
}
}
]
}
</syntaxhighlight>


Windows users need to fix the Windows-specific command. You can now build the extension using the menu ''Terminal / Run Build Task''. The result of the command should appear in the Terminal Panel beneath the Edit area.

<syntaxhighlight>
* Executing task: php ~/bin/phing-latest.phar


Buildfile: /Users/ceford/git/gitdemo/j4xdemos-mod-debugme/build.xml


mod_debugme > main:


[zip] Nothing to do: /Users/ceford/zips/mod_debugme.zip is up to date.


BUILD FINISHED


Total time: 0.1031 seconds


* Terminal will be reused by tasks, press any key to close it.
</syntaxhighlight>


There may be incomprehensible error messages. The most likely cause is in having invalid paths to folders in the ''build.xml'' file or a folder has not been created. Just another sort of problem to debug!

== Debugging == 
You should be able to fix the first bug by code inspection. More complicated problems require stepping though the code with the debugger. That allows you to inspect variables to see if they contain values that you expect, for example when passing arguments to library functions.

=== ''php.ini'' Settings === 
To set up debugging with Xdebug you need to make some entries at the top of your ''php.ini'' file.


<syntaxhighlight>
zend_extension="xdebug.so"
xdebug.mode="debug"
xdebug.client_port=9003
xdebug.start_with_request = yes
</syntaxhighlight>


After saving any changes, restart your Apache server.

=== Add Website Window === 
Your extension folder contains just a few files, the '''''sources''''' of the files installed in your website. Runtime debugging involves setting breakpoints in your '''''site''''' files so you need access to those files. You could use the ''File / Add Folder to Workspace...'' menu to add the site folder to your Workspace. However, there is a very good chance you will end up making changes to site files instead of source files. So it is probably best to open a separate VS Code window for debugging.


* '''Open new window:''' From the VS Code menu, select ''File / New Window'' and select the folder containing your Joomla website.


* '''Open folder:''' In the newly opened window, select ''File / Open Folder...'' from the VS Code menu. Find your website folder and select it. You should see a list of all the files in your Joomla website in the Primary sidebar.

=== Launch Configuration === 
For debug to actually work in VS Code you need a launch configuration. In the root of your website create a folder named ''.vscode'' (note the leading stop) containing a file named ''launch.json'' with the following content:


<syntaxhighlight>
{
"configurations": [
{
"name": "Listen for XDebug",
"type": "php",
"request": "launch",
"hostname": "0.0.0.0",
"port": 9003,
"stopOnEntry": true,
"pathMappings": {
"/Users/ceford/Sites/j421rc2": "${workspaceFolder}"
}
}
]
}
</syntaxhighlight>
Remember to replace the pathMappings item in this example with the actual pathMappings on your own site. The stopOnEntry item will pause execution on the very first line of PHP code executed.

=== Debug ''mod_debugme'' === 
Now you are ready to find and fix the bugs in the installed module.


* '''Find module code:''' Find the first bug on line 16 of ''JROOT/modules/mod_debugme/mod_debugme.php''.
* '''Set breakpoint:''' Click in the space to the left of the number 16. A pale red blob will appear as you hover and turn full red after you click to indicate a break point has been set.
* '''Start debug:''' From the VS Code menu select ''Run / Start Debugging''. In your browser reload your site. Your VS Code window should reappear with the code stopped at the first line of the site ''index.php'' file. At the top of the screen are some icons to control the debug process. They should be self-explanatory. If not, look them up in the VS Code Help / Documentation.
* '''Continue:''' Select the continue button - the code will run on to your first breakpoint. Examine the code to see what the problem is.
* '''Hover:''' If you hover over a variable that has been assigned a value a small Tooltip will appear summarizing that variables attributes. There is no Tooltip for variables that have not been assigned values.
* '''Variables:''' The left column contains more information about the state of the code at the breakpoint. There are too many to cover here. Explore them as required!
* '''Stop Debugging:''' It is probably best to select the Continue icon, otherwise the web page is delivered blank. Otherwise you could use the Stop button or the Run / Stop Debugging menu.

=== Fix a Bug === 
'''Remember:''' Do not fix the bug in the website code! Fix it in the source code!


Fix the source code and then use ''Terminal / Run Build Task...''.


Restart debug.

=== Tips === 
A few not so obvious problems:


* You fix the first bug but it still crashes on that line. Look in mod_debugme.xml to see where the source of namespaced classes is defined. When fixed in the source you need to reinstall the zip file or delete ''administrator/cache/autoload_psr4.php''. When absent, Joomla rebuilds that file from manifest files. But if it has an incorrect or missing entry it does not get fixed until the extension is reinstalled.
* Sometimes you need to set a breakpoint a few lines before the line where the error occurs, especially if you wish to check values passed to function calls.
* Table ''xxx.yyy\_debugme'' doesn't exist. Ah yes, the code to create a table on install and remove on uninstall was never created. You will need to run an SQL query in phpMyAdmin using the content of the ''mod\_debugme.sql'' file. Remember to change ''#\_'' in the table names for your database prefix. And when it still fails check the table name in the code.

== Screenshot == 


When all is fixed this is what you might see:


[[File:J4.x-vscode-primer-debugme-fixed-en.png|border]]


Cake days?

== References == 


From Joomla! Documentation: [[Visual Studio Code]] also covers configuration of other tools, for example CodeSniffer and PHPUnit.
</translate>

Potential backward compatibility issues in Joomla 4

2023-06-23T22:45:13Z

Cmb: Several markup and capitalization changes. Some Words2Watch changes.

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

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

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

<translate>
=== PHP MySQL Extension === 
</translate>
<translate>
*Joomla no longer supports using PHP's ext/MySQL driver (which was removed in PHP 7.0). Joomla will automatically try to use the MySQLi extension (available since PHP 5.3) or the MySQL PDO Driver (available since PHP 5.3). Otherwise it will fail to create a database connection.</translate>
<translate> * Strict mode has been enabled. The following flags are now active by default in Joomla 4 and you may have to update your database queries accordingly. This will help us with future MySQL version upgrades and also aligns more closely with PostgreSQL to enable easier compatibility with queries in both languages.</translate>

<pre>
'STRICT_TRANS_TABLES',
'ERROR_FOR_DIVISION_BY_ZERO',
'NO_AUTO_CREATE_USER',
'NO_ENGINE_SUBSTITUTION',
</pre>
<translate>

As a consequence, Joomla 4 will only use '''NULL date defaults'''. The use of the ''invalid default date'' of 0000-00-00 00:00:00 in Joomla 4 has been deprecated.</translate>

<translate>
=== PHP PostgreSQL Extension === 
</translate>
*<translate> Joomla no longer supports using PHP's ext/pgsql driver. Joomla will automatically try to use the PostgreSQL PDO Driver (available since PHP 5.3 and Joomla 3.9). Otherwise it will fail to create a database connection with a PostgreSQL database.</translate>

<translate>
=== PHP GMP Extension === 
</translate>
<translate> This is required for using the [[WebAuthn Passwordless Login]] feature. Note the PHP GMP Extension is installed by default on the majority of hosting sites. The [[WebAuthn Passwordless Login]] System Plugin is enabled by default in Joomla 4 on HTTPS sites.</translate>
<translate>

=== PHP ''mcrypt'' Extension === 
</translate>
<translate> This is required for using the Joomla\CMS\Crypt\Cipher\CrytoCipher class and its alias JCryptCipherCrypto.</translate>

<translate>
== CMS Libraries == 
</translate>
<translate>
The following changes have been made to Joomla! CMS libraries (this is primarily code that was found in the “libraries/cms” directory in Joomla! 3.7 and earlier).</translate>

<translate>
=== Installer === 
</translate>
* <translate> Plugin discover installs will no longer search for XML files in the Joomla! 1.5 plugin folder layouts</translate>
* <translate> In 3.x, only plugins scripts have the preflight method called and none make postflight available during the uninstall process. All extensions types will have these hooks available in 4.0 when being uninstalled. If you currently preflight and postflight and assume they only apply in an install/update context - this logic is now incorrect and you should use the install route (given as one of the method parameters)</translate>
* <translate> When uninstalling a plugin the uninstall function in the extension script is now triggered before triggering any SQL queries (this is now consistent with all other extension types).</translate>

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

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

<translate> Custom Installer Adapters must now be autoloaded.</translate>

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

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

<translate>
==== JMenuItem ==== </translate>
<translate>

* You can no longer retrieve the params property from JMenuItem directly. Use the getParams() method instead (available since Joomla 3.7)</translate>
<translate>

* JMenuItem::set and JMenuItem::get have been removed. Properties must be explicitly named</translate>
<translate>

* There is now a AdministratorMenuItem class which extends from MenuItem that contains extra public properties used for the Administrator menu item.</translate>

<translate>
=== Pagination === </translate>
<translate>

* The magic pagination functions ''pagination_item_active'', ''pagination_item_inactive'' have been removed. Use the JLayout's joomla.pagination.link instead</translate>
<translate>

* The magic pagination function ''pagination_list_render'' is deprecated. Use the JLayout joomla.pagination.list instead</translate>

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

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

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

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

<translate>
==== Method Signature Changes ==== 
</translate>
<translate> The attachBuildRule and attachParseRule are now typehinted to require callables.</translate>

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

<translate> The following deprecated constants have been removed:</translate>
* JVersion::RELEASE
* JVersion::DEV_LEVEL
* JVersion::BUILD

<translate>
=== JHtml === 
</translate>
* <translate> The register function in JHtml is now typehinted to require a callable. Subclasses of JHtml will now need to match this signature (note this was already required at the function code level).</translate>
* <translate> JHtml::_ no longer allows you to call non-public methods in JHtml</translate>
* <translate> JHtml::_ is now a final method (you can no longer override it if you subclass JHtml) and its signature has changed to take advantage of modern PHP features (scalar and variadic typehints)</translate>
* <translate> JHtmlBootstrap::modal has been removed. Use JHtmlBootstrap::renderModal</translate>
* <translate> JHtmlSortablelist::sortable has been deprecated in favour of JHtmlDraggablelist::draggable - the old method acts as a proxy to the new method currently to facilitate the removal of jQuery UI from Joomla Core. All media assets relating to the original jQuery UI implementation have been removed.</translate>
* <translate> JHtmlBatch has been removed as all the code had been moved to layouts for template overrides. Use the JLayouts directly in your code.</translate>

<translate>
=== Updater === 
</translate>
<translate>

* We removed the deprecated integer client handling from the updater extension adapter class. Please use '''site''' and '''administrator''' now and not the integer values '''0''' / '''1'''.</translate>

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

<translate>
=== Access === </translate>
<translate>

* JAccess::$assetPermissionsById and JAccess::$assetPermissionsByName and JAccess::preloadPermissionsParentIdMapping have been removed without replacement. Since 3.6 we've used other methods and class properties to optimize the loading of assets. See the [https://github.com/joomla/joomla-cms/pull/12850 JAccess bug fixes and optimizations pull request] to see the reasons for this deprecation.</translate>
<translate>

* JAccess::getActions has been removed. Use JAccess::getActionsFromFile or JAccess::getActionsFromData instead.</translate>

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

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

All references to JSite and JAdministrator have been removed (these were just class alias' since Joomla 3.2)</translate>

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

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

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

<translate> The registerEvent method is now typehinted to require a callable for the $handler parameter.</translate>

<translate> Applications that want to support both Web and CLI Applications should now typehint against the \Joomla\CMS\Application\ CMSApplicationInterface - this contains common methods (some of which in Joomla 3.x were only found in the JApplicationCms class) that can be used by all code. It's strongly recommended any custom applications (especially CLI applications) implement this interface to make compatibility checks easier, simultaneously any typehints should use the interface rather than a concrete class.</translate>

===== JApplicationCli =====

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

===== JApplicationWeb =====

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

<translate>
* The legacy ways of calling JApplicationWeb::redirect have been removed
** With a message and messageType parameters. (Call enqueueMessage separately.)
** Passing in a true/false value as the 2nd/3rd parameters instead of a redirect code will give an InvalidArgumentException instead of defaulting to a 303.</translate>
<translate> * JApplicationWeb::$singleValueResponseHeaders has been removed because the Framework Application will be internally using PSR-7 Response objects as of its 2.0 release. This changes how the headers data is stored so it is always a multi-dimensional array with each top level key being the header names and the value being an array holding all of the values for that header.</translate>

===== CMSApplication =====

*<translate> The $_clientId, $_messageQueue and $_name class properties have all been renamed to remove their underscore prefix.</translate>
* <translate> Now implements CMSApplicationInterface.</translate>
* <translate> If there is an error retrieving a Pathway, Router or Menu object using the respective methods, the exception will now bubble up rather than the method silently catching the exception and returning null.</translate>
* <translate> CMSApplication::getInstance will now additionally try to load the user object (using the loadIdentity function).</translate>
* <translate> CMSApplication::isSite and CMSApplication::isAdmin have been removed as with the addition of the ConsoleApplication and ApiApplication can give misleading results. Please use CMSApplication::isClient (available from {{JVer | 3.7}}). For more information please see [[S:MyLanguage/J3.x:Discover_on_which_client_your_extension_code_is_running|Discover on which client your extension code is running]].</translate>

===== JApplicationSite =====
<translate>

The $_language_filter and $_detect_browser class properties have all been renamed to remove their underscore prefix.</translate>

<translate> The deprecated method JApplicationSite::getPageParameters has been removed in favour of its alias JApplicationSite::getParams</translate>

===== JApplicationHelper =====

<translate> JApplicationHelper::parseXMLLangMetaFile has been removed without replacement.</translate>

<translate>
=== Archive === 
</translate>
*<translate> The archive package has been removed in favour of the frameworks archive package. Note the API should remain unchanged.</translate>
* <translate> Errors handing now uses Exceptions rather than JError</translate>

=== Client ===
\Joomla\CMS\Client\ClientWrapper <translate> has been removed. Use the static methods in</translate> \Joomla\CMS\Client\ClientHelper

=== Crypt ===
* JCrypt::hasStrongPasswordSupport <translate> has been removed without replacement as all PHP versions Joomla 4 matches will support strong password hashing.</translate>

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

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

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

<translate>
==== Removed Methods ==== 
</translate>
* <translate> JCrypt::hasStrongPasswordSupport has been removed without replacement (this attempted to detect bcrypt polyfills on linux hosting but has always returned true since we required PHP 5.3.10 in Joomla 3.3)</translate>

<translate>
=== Cache === 
</translate>
* <translate> JCacheController::get now requires a callable. As a result JCacheControllerCallback::call has been removed.</translate>
* <translate> JCacheStorage::test has been removed. Use JCacheStorage::isSupported instead</translate>
* <translate> The default storage engines are no longer manually loaded as they are now autoloaded</translate>
* <translate> JCacheControllerOutput::start and JCacheControllerOutput::end have been removed without replacement</translate>
* <translate> Removed CacheLite storage as it not compatible with PHP7 (which is our minimum version)</translate>
* <translate> Error handling now uses Exceptions instead of JError</translate>

<translate>
=== Component === 
</translate>
* <translate> \Joomla\CMS\Component\ComponentRecord no longer extends JObject</translate>

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

<translate>
==== Inheritance Change ==== 
</translate>
<translate>
The following classes have had their inheritance changed:
*JDocumentError (now extends from \Joomla\Cms\Document\HtmlDocument instead of \Joomla\Cms\Document\Document)</translate>

<translate> Note as a result of this change rendering an error page resets the document object in Joomla\CMS\Factory::$document, the rationale being we want a clean document to work from; if the error page is triggered we aren't interested in the metadata your component has set, or the media added from some bad module, or whatever plugins are adding to the display. We want a clean environment for rendering the error page only containing the error page's loaded data.</translate>

<translate>
==== Renderers ==== 
</translate>
* <translate> In order to comply with the RSS feed specification, JDocumentRendererFeedRss now allows the lastBuildDate element to be configured using the JDocumentFeed::$lastBuildDate class property when a feed is rendered. This value defaults to the current time, as is the case with Joomla! 3.x and earlier, however the time can be correctly set by changing this class property to a JDate object representing the desired timestamp.</translate>
* <translate> There is now a RendererInterface that all Renderers should implement</translate>
* <translate> JDocumentRenderer is now an abstract class and implements RendererInterface</translate>
* <translate> As an alternative to <jdoc:include type="head" /> you can now individually load <jdoc:include type="metas" /> for metadata, <jdoc:include type="styles" /> for CSS and <jdoc:include type="scripts" /> for JavaScript. The intention of this is to optionally allow users to place all JavaScript at the bottom of the HTML Document in their templates.</translate>

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

<translate>
=== Database === 
</translate>
* <translate> This package has been replaced by the Joomla Framework Database Package</translate>
* <translate> Debug mode has been reworked (see the framework docs for more information</translate> [https://github.com/joomla-framework/database])

=== Factory ===
* <translate> Factory::getApplication no longer takes arguments. These were misleading as it always returned the active application after the first call in the bootstrap, whatever arguments were passed into the function.</translate>
* <translate> Factory::getXml has been removed along with JXMLElement. Use SimpleXMLElement directly instead.</translate>
* <translate> Factory:: getEditor has been removed use JEditor::getInstance instead.</translate>
* <translate> Factory:: getUri has been removed use Uri::getInstance() instead.</translate>

<translate>
=== Environment === 
</translate>
* <noinclude>JBrowser::isSSLConnection has been removed. Use JApplicationCms::isSSLConnection (available since Joomla 3.2)</noinclude>

<translate>
=== Filesystem === 
</translate>
* <translate> The filesystem wrapper classes have been removed. Continue using the original static methods.</translate>

=== Filter ===
* JFilterInput::_remove <translate> has been removed in favour of</translate> JFilterInput::remove
* JFilterInput::_cleanTags <translate> has been removed in favour of</translate> JFilterInput::cleanTags
* JFilterInput::_cleanAttributes <translate> has been removed in favour of</translate> JFilterInput::cleanAttributes
* JFilterInput::_decode <translate> has been removed in favour of</translate> JFilterInput::decode
* JFilterInput::_escapeAttributeValues <translate> has been removed in favour of</translate> JFilterInput::escapeAttributeValues
* JFilterInput::_stripCSSExpressions <translate> has been removed in favour of</translate> JFilterInput::stripCSSExpressions
<translate>

All of the above deprecations and removals are to allow the class to be reunified with the framework parent class.</translate>

=== Form ===
*<translate> The libraries/joomla/form/fields and libraries/joomla/form/rules directories are no longer registered to find form classes, all form classes should be autoloaded instead</translate>
*<translate> Two new properties added addfieldprefix which registers a namespace prefix for extensions (intended to be used as a replacement for addfieldpath). For example usage please see [https://github.com/joomla/joomla-cms/pull/16419 this GitHub PR]</translate>
* <translate> JForm::getControlGroup has been removed use the alias JForm::renderField (available since Joomla 3.2.3)</translate>
* <translate> JForm::getControlGroups has been removed use the alias JForm::renderFieldset (available since Joomla 3.2.3)</translate>
<translate>

* When rendering a field using the hiddenLabel option in JForm - it now only hides the label from the User Interface - the HTML is still rendered with the sr-only class for screen-reader accessibility purposes.</translate>
* <translate> JFormFieldUsergroup has been removed. Use Joomla\CMS\Form\Field\UsergrouplistField instead (available since Joomla 3.2)</translate>
<translate>

* The Form class has removed the protected methods filterField() and validateField(). This will break any custom Form classes that extends core Form and use these methods. This has been replaced in favour of filtering at the field level (see https://github.com/joomla/joomla-cms/pull/12414 for more information)</translate>

==== Fields ====
* <translate>
JFormFieldFilelist and JFormFieldFolderList have had their filter properties renamed to <code>fileFilter</code> and <code>folderFilter</code> respectively (in order to allow the use of the regular Joomla filter attribute on returned values)</translate>
* JFormPredefinedlistField <translate> has its filter properties renamed to <code>optionsFilter</code> (in order to allow the use of the regular Joomla filter attribute on returned values)</translate>
* JFormFieldEditor::save <translate> has been removed without replacement</translate>
* JFormFieldText::getSuggestions <translate> has been removed in favour of</translate> JFormFieldText::getOptions

==== Media Field ====

<translate> The Media field type now encodes image metadata into the internal value. This is a sample value:</translate></br>''images/banners/osmbanner1.png#joomlaImage://local-images/banners/osmbanner1.png?width=468&height=60''

<translate> To produce the final Image URL or the relative image file path, you can use the new helper:</translate></br>''echo \Joomla\CMS\HTML\HTMLHelper::cleanImageURL($oldValue);''

<translate> To get the clean value (without adapter information and metadata) from the value which is stored in media form field: </translate></br>''echo \Joomla\CMS\Helper\MediaHelper::getCleanMediaFieldValue($oldValue);''

<translate> Function cleanImageURL does not clean the image URL but returns object where one part of the object is cleaned URL. Using echo throws an error. For more information visit [https://github.com/joomla/joomla-cms/issues/35871#issuecomment-968107241]</translate>

<translate>
=== Wrapper === 
</translate>

<translate> * The form wrapper classes have been removed. Continue using the original static methods.</translate>

=== HTTP ===

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

<translate>
==== Class Changes ==== 
</translate>

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

===== JHttp =====
<translate> * JHttp no longer ships with a cacerts.pem bundle in the transports directory use the composer/ca-bundle instead which ships with core.</translate>

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

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

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

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

<translate>
==== Deprecated Classes and Interfaces ==== 
</translate>
<translate>
The following classes and interfaces have been deprecated and scheduled for removal in Joomla! 5.0:
* JImageFilter (use Joomla\CMS\Image\ImageFilter instead)
* JImageFilterBackgroundfill (use Joomla\CMS\Image\Filter\Backgroundfill instead)
* JImageFilterBrightness (use Joomla\CMS\Image\Filter\Brightness instead)
* JImageFilterContrast (use Joomla\CMS\Image\Filter\Contrast instead)
* JImageFilterEdgedetect (use Joomla\CMS\Image\Filter\Edgedetect instead)
* JImageFilterEmboss (use Joomla\CMS\Image\Filter\Emboss instead)
* JImageFilterGrayscale (use Joomla\CMS\Image\Filter\Grayscale instead)
* JImageFilterNegate (use Joomla\CMS\Image\Filter\Negate instead)
* JImageFilterSketchy (use Joomla\CMS\Image\Filter\Sketchy instead)
* JImageFilterSmooth (use Joomla\CMS\Image\Filter\Smooth instead)</translate>

<translate>
==== Class Changes ==== 
</translate>
<translate>
The classes from Framework's Image package have been inlined into CMS and JImage and the JImageFilter subclasses have been refactored to use them. I.e. all classes under Joomla\Image namespace moved to Joomla\CMS\Image namespace.</translate>

<translate>
=== Menu === 
</translate>
* <translate> JMenu::$_items, JMenu::$_default and JMenu::$_active have been had their underscore prefix's removed (note these properties were protected so this only affects custom subclasses of JMenu)</translate>

<translate>=== New MVC Layer === </translate>
<translate>

* This has been removed in Joomla 4. We have decided that this effort was not successful and as a result have continued development work on the original MVC Layer (see the "Legacy MVC" section). There is a plugin located [https://github.com/joomla-extensions/legacy-mvc on GitHub] you can ship with your extensions whilst you migrate them back to the Legacy MVC (note that this is not shipped by default in Joomla 4).</translate>

=== Keychain ===
<translate> Removing the keychain with 4.0 has resulted in the removal of the following class:</translate>
*JKeychain

=== Pathway ===
* <translate> JPathway::$_pathway and JPathway::$_count have been had their underscore prefix's removed (note these properties were protected so this only affects custom subclasses of JPathway)</translate>
* <translate> JPathway::_makeItem has been removed in favour of JPathway::makeItem (note this method was protected so this only affects custom subclasses of JPathway)</translate>

=== Profiler ===
* <translate> JProfiler::getmicrotime and JProfiler::getMemory have been removed in favour of the native PHP methods they wrapped (<source lang="php" inline>microtime(1)</source> and <source lang="php" inline>memory_get_usage()</source> respectively)</translate>

<translate>
=== Table === 
</translate>
<translate>

* JTable::__construct database object is now typehinted to be a JDatabaseDriver.
** Subclasses of JTable will need to ensure they are passing a JDatabaseDriver object to the parent constructor
** Subclasses of JTable will need to change the method signature of setDbo() if they have an extended version of that method to include the typehint
* There is a new method JTable::hasField - all instances of property_exists on JTable instances will now use this proxy method instead to allow better interoperability of Table instances
* The JTableObserver pattern (and corresponding classes) has been removed from JTable. JTable now triggers events and Tags, Content History (and any other custom uses of this pattern) should move to standard plugins.</translate>

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

<translate>
==== Exceptions ====  </translate>
<translate> JMail no longer catches exceptions from PHPMailer. It is now the object calling JMail's responsibility to handle these exceptions as appropriate. In addition if mail sending is disabled in global configuration calling <source lang="php" inline>\ Joomla\CMS\Mail\Mail::send()</source> will throw a <source lang="php" inline>\Joomla\CMS\Mail\Exception\MailDisabledException</source>.</translate>

<translate>
=== Language === 
</translate>
<translate>
* The functions setTransliterator, setPluralSuffixesCallback, setIgnoredSearchWordsCallback, setLowerLimitSearchWordCallback, setUpperLimitSearchWordCallback and setSearchDisplayedCharactersNumberCallback are now typehinted to require a callable.
* The <tt>"_QQ_"</tt> placeholder for double quotes has been removed (this only existed to work around an old PHP Bug that has been fixed). Escape double quotes if required (i.e. <tt>\"</tt>)
</translate>
<translate>

* The format for language file names has been changes to ease the work in 3rd party translation tools (such as Crowdin). INI language files no longer have to contain the language code (i.e. en-GB.com_contact.ini => com_contact.ini), in this case the special case of en-GB.ini has been renamed to ''joomla.ini'' in the core language pack. en-GB.xml has been named langmetadata.xml. There is a b/c layer that will continue to read the old Joomla 3 file names throughout Joomla 4.</translate>
<translate>

* \Joomla\CMS\Language\Multilanguage::getSiteLangs has been removed. Use \Joomla\CMS\Language\LanguageHelper::getInstalledLanguages(0) instead</translate>
<translate>

* JLanguage::exists has been removed. Use Joomla\CMS\Language\LanguageHelper::exists instead.</translate>
<translate>

* The wrapper classes JTextWrapper, LanguageHelperWrapper and TransliterateWrapper have been removed. Continue to use the static methods they wrapped.</translate>
<translate> * The pdf_fonts handling/support for language packs (<code>language/pdf_fonts</code>) has been removed from the language installer ([https://github.com/joomla/joomla-cms/pull/31288 see GitHub PR #31288]).</translate>

<translate>
=== Legacy MVC Layer === 
</translate>

<translate>
==== Legacy Controller ==== 
</translate>
<translate>
* JControllerLegacy has been removed from the legacy layer, and we no longer intend to remove it or its subclasses in the near future.
* JControllerLegacy no longer extends JObject. Controllers should not call any of the methods contained in the JObject class.
* JControllerLegacy implements an interface for multiple task controllers
* JControllerLegacy::_construct now takes additional arguments. If you were previously getting a Controller object through JControllerLegacy::getInstance you do not need to change your code.
** Parameter 2: An optional MVCFactoryInterface instance
** Parameter 3: An optional CMSApplicationInterface instance
** Parameter 4: An optional Input instance
** Parameter 5: An optional FormFactoryInterface instance
* JControllerForm now uses the StringInflector package to determine the list view. This should improve its ability to determine the list view of more view names. If extension developers find that their list view is no longer being found they should manually set the ''view_list'' class property in their controller.</translate>

<translate>
==== Legacy View ==== 
</translate>
<translate>
* JViewLegacy has been removed from the legacy layer, and we no longer intend to remove it or its subclasses in the near future.
* JViewHtml has been split into two classes - AbstractView and HtmlView. Abstract view contains the logic for accessing models and getting the name of the view and is intended to be a base class for non-Html views. Html view contains the same logic as before.
* There are now two subclasses of JViewHtml - \Joomla\CMS\MVC\View\ListView and \Joomla\CMS\MVC\View\FormView designed to speed up the development of list and form views and reduce code duplication.</translate>

=== Library ===
<translate>

* JLibraryHelper::_load has been removed. Use \Joomla\CMS\Helper\LibraryHelper::loadLibrary instead.</translate>

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

=== String ===
<translate> The old JString class alias has been removed. Use \Joomla\String\StringHelper instead.</translate>

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

<translate>
==== JSession ==== 
</translate>
<translate>
JSession now extends from the Framework's Joomla\Session\Session class. Many of the methods have a modified signature and a compatibility layer exists to help with the transition.</translate>

<translate>
===== Namespace Parameter Deprecated ===== 
</translate>
<translate>
The ''get'', ''set'', ''has'' and ''clear'' methods previously supported a namespace parameter. This parameter is now deprecated. The namespace should be prepended to the name before calling these methods.</translate>

<translate>
===== JSession::clear() Repurposed ===== 
</translate>
<translate>
In the Joomla\Session\Session class, the ''clear'' method is used to clear all data from the session store. In JSession, this method is used to remove a single key. When this method is called with parameters, it will call the new ''Joomla\Session\Session::remove()'' method.</translate>

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

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

<translate>
=== Social Media Libraries === 
</translate>
<translate> The facebook, github, google, linkedin, openstreetmap, mediawiki and twitter packages have all been removed from the CMS.</translate>

=== User ===
* <translate> JUser::getParameters has been removed. You can no longer retrieve all parameters for a user but instead use JUser::getParam to get individual parameters as required.</translate>

==== Helper ====
* <translate> JUserHelper::getCryptedPassword has been removed. Joomla 4 only supports hashing with the native PHP password_hash function (via JUserHelper::hashPassword (available since Joomla 3.2.1))</translate>
* <translate> JUserHelper::getSalt has been removed without replacement (it generated the hash's JUserHelper::getCryptedPassword which is now removed as above)</translate>
* <translate> JUserHelper::invalidateCookie, JUserHelper::clearExpiredTokens and JUserHelper::getRememberCookieData have been removed without replacement. They had been unused in core since Joomla 3.2 when their logic was moved into the Cookie Authentication Plugin</translate>
* <translate> JUserWrapperHelper has been removed. Continue using the original static methods in JUserHelper.</translate>

<translate>
=== Classes Removed Without Replacement === 
</translate>
* JNode
* JTree
* JGrid
* JError <translate> (use native exceptions when error handling is required)</translate>

<translate>
==== Utilities ==== 
</translate>

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

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

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

=== PHPMailer ===
<translate>
Joomla! 4.0 ships with PHPMailer 6. Please review the [https://github.com/PHPMailer/PHPMailer GitHub repository] for relevant changes.</translate>

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

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

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

=== jQuery UI ===
<translate> jQuery UI has been removed from Joomla 4. Whilst it hasn't been officially announced as dead, there hasn't been a release of jQuery UI since 2016.</translate>

=== Bootstrap ===
<translate>
Joomla! 4.0 ships with Bootstrap 5. Bootstrap 2.3.2 has been removed, however we have left some BS2 classes in to ease the migration (e.g. The old BS2 element-invisible still exists for screenreaders)</translate>

=== FOF ===
<translate> FOF 2.x has been removed.</translate>

<translate>
== Templates == 
</translate>
<translate>
All the Joomla! 3 templates - ISIS and Hathor in the Backend (Administrator), and Protostar and Beez in the Frontend (Site) are no longer supported. The new 4.0 Backend template is called Atum and the Frontend template is Cassiopeia.</translate>

<translate> As a consequence, all extensions must migrate to the new Bootstrap 5 style, away from the current Bootstrap 2.3.2 implementation. For more information about Bootstrap, visit the [https://getbootstrap.com/docs/5.0/getting-started/introduction/ Bootstrap 5] Website and the [https://getbootstrap.com/2.3.2/ Bootstrap 2.3.2] Website.</translate>

* <translate> Joomla 4 will load the template favicon first rather than the one in the Joomla Root in keeping with the concept the template is the single source of truth.</translate>
* <translate> Frontend components and module views now use Block Element Modifier (BEM) class markup to make it easier for templates to support frameworks other than bootstrap. See the [http://getbem.com/ BEM Website] for more information on how to build similar classes.</translate>

<translate> There where also changes to options of the core components that you should take a look at when your tempalte should support 3.x and 4.x at the same time: https://docs.joomla.org/J4.x:Changed_parameters_for_template_providers</translate>

<translate>
== Other == 
</translate>
* <translate> The ''$_PROFILER'' global variable has been removed. Use ''/Joomla/CMS/Profiler/Profiler::getInstance'' instead.</translate>

<translate>
=== Media in Libraries === 
</translate>
<translate> No media is allowed in the libraries root folder in the CMS. All assets associated with Joomla libraries should be put in the media folder per best practices. Direct access is blocked with a ''.htaccess'' and the ''web.config'' file in the root of the libraries directory.</translate>

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

<translate>
=== Components === 
</translate>
* <translate> All components have been namespaced and directories reworked accordingly. For more information about this read the tutorial on building a component in Joomla 4.</translate>
* <translate> com_admin profile view has been removed. (This appears to have been created historically due to issues accessing com_users. This is no longer the case so all user edits go through com_users edit user view in the backend.)</translate>
* <translate> com_actionlogs PHP 5.5 backfill code has been removed and accordingly <source inline lang="php">ActionlogsHelper::getCsvData()</source> is now type hinted to return a <source inline lang="php">Generator</source> object</translate>
* <translate> com_actionlogs CSV export headers have been changed to match the strings shown in the UI.</translate>
* <translate> Core components have had URL Routing 'Legacy' mode removed from Joomla 3.7. You should either use your .htaccess file or the redirect component to fix any internal URLs that change. You can try the 'Modern' mode in Joomla 3 by following the instructions [[S:MyLanguage/J3.x:New_Routing_System|here]]</translate>
* <translate> The MailTo component has been removed without replacement. If you used this functionality you will need to find an alternative component on JED.</translate>
* <translate> In com_contact 's frontend contact view - the contact property has been removed as it was a duplicate of the item property. We chose to keep $this->item as it was consistent with that in the article and tag views. Template overrides will need updating to reflect this.</translate>
* <translate> The repeatable field in com_fields has been removed in favour of the new subform field. Data from repeatable fields is automatically migrated to the new subform field but is stored in a different format.</translate>
* <translate> The xreference fields have been removed from ''#__contact_details'', ''#__content'' and ''#__newsfeeds'' as they were unused.</translate>

<translate>
=== Plugins === 
</translate>
* <translate> The Gmail authentication plugin has been removed. For more information please read [https://developer.joomla.org/news/724-removal-of-the-gmail-authentication-plugin-as-of-joomla-4-0.html this blog post].</translate>
* <translate> Google reCAPTCHA v1 support has been fully removed from the CAPTCHA plugin. This hasn't worked since Q2 2018. Google dropped support for it.</translate>
* <translate> The reCAPTCHA plugin now uses Google's official PHP library for CAPTCHA under the hood</translate>
* <translate> For plugins using the 3.x compatibility layer, the name result is a protected property for both input parameters and return values. For information on the new recommended approach to plugins please read [[S:MyLanguage/J4.x:Creating_a_Plugin_for_Joomla]]</translate>
* <translate> For plugins using the 3.x compatibility layer, for any type hints for events that require a class, that class '''must''' be autoloaded before the plugin is instantiated.</translate>
* <translate> The onContentBeforeSave event now requires the data parameter. This has been passed in \Joomla\CMS\MVC\Model\LegacyModel since 3.7 but is now passed in consistently by core extensions and used by the core Joomla content plugin.</translate>
* <translate> Returning before calling <source lang="php" inline>parent::__construct()</source> in the constructor of a plugin is no longer supported to avoid queuing the plugin into the event dispatcher.</translate>
* <translate> ''onUserBeforeDataValidation'' is deprecated as an event in favor of ''onContentBeforeValidateData'' (The event was usable by all content types and was not specific to users. Note that both events will be called for the duration of Joomla 4. You should migrate your code to the new event when you no longer need to support Joomla 3.</translate>

<translate>
=== Plugins (Events) === 
</translate>
* <translate>  In Joomla 4, events whose name does not start with "on" no longer work. They don't even produce an error, so it's hard to figure out why they don't work. This means that you need to overwrite both the names of functions in plugins and the names of their calls. For more information please read [https://github.com/joomla/joomla-cms/issues/36062]</translate>

<translate>
=== Administrator Helpers === 
</translate>
* <translate> JAdministratorHelper has been removed without replacement. (It's been merged into JApplicationAdministrator.)</translate>
* <translate> JSubMenuHelper has been removed without replacement. (Use JHtmlSidebar instead - available since 3.0.)</translate>
* <translate> JToolbarHelper has been moved to the main libraries directory.</translate>

<translate>
=== Modules === 
</translate>
* <translate> The administrator module ''submenu'' has been removed.</translate>
* <translate> Logic of ''Module Chromes'' (module styles) in template files <code>html/modules.php</code> have been moved to <code>JLayout</code> files. <code>modChrome_x</code> functions in <code>modules.php</code> are no longer supported. See https://github.com/joomla/joomla-cms/pull/23570 for details.</translate>
* <translate> ''Module Chromes'' (module styles) <code>modChrome_horz</code>, <code>modChrome_xhtml</code>, <code>modChrome_rounded</code> have been removed from template <code>system</code> without replacement.</translate>
* <translate> Module Class Suffixes have been renamed and standardized. These are now called Module Class and are appended to the list of classes in the Module Chrome. (They are no longer rendered in the module output itself.)</translate>

<translate>
=== Error Handling === 
</translate>
* <translate> Joomla will now handle PHP's E_USER_DEPRECATED errors and pipes them into JLog - this is useful for handling deprecations in many third party PHP Libraries. (Note it will block the page load if debug mode is enabled.)</translate>
* <translate> Joomla\CMS\Exception\ExceptionHandler now only operates on Exceptions thrown in JApplication::execute. We now use Symfony's ErrorHandler when this fails or exceptions are thrown outside of this. We expect this to have minimal effect on most users and should give a more helpful message in many cases than the traditional "Error displaying the error page" error for users when things go very wrong.</translate>
* <translate> Joomla\CMS\Exception\ExceptionHandler is now format-aware and will render errors in HTML, JSON, XML, feed- or cli-aware formats</translate>
* <translate> The Joomla\CMS\Exception\ExceptionHandler::render() signature is changed to include the Throwable typehint. Before 3.5 when PHP 7 support was added this was typehinted as Exception, and since 3.5 has been typechecked in the code itself.</translate>

=== Base Tag ===
<translate> Previous Joomla versions set a ''<base>'' header tag of the current URL in the Frontend. This has been removed as it served no clear purpose.</translate>

=== JavaScript ===
<translate> The ''caption.js'' file has been removed from Joomla. Use the native HTML elements ''figure'' and ''figcaption''. (You can look at JLayout in ''layouts/joomla/content/intro_image.php'' for an example).</translate>

<translate> saveOrderAjax does not send complete form data (like it did in Joomla 3), only cid and order variable. This may be insufficient because some extensions need more data for proper sorting - see: https://github.com/joomla/joomla-cms/issues/36346</translate>

=== Namespacing ===
<translate> Class usage like ''$msg = JText::_( 'Hello man!' );'' can now use namespacing. That would turn into ''$msg = Text::_( 'Hello man!' );''. To use namespacing, you need to add the proper namespace declaration. This should be added after the ''defined('_JEXEC') or die;''.</translate>

<translate>
To find out the proper namespace you can either follow the instructions here: [https://groups.google.com/forum/#!topic/joomla-dev-general/1ua9zIqlcVc SO confused about namespace & enquemessage...] or use the generated file PDF reference file:
[https://docs.joomla.org/images/9/9c/J%21_namespace_reference.pdf namespace reference.pdf]</translate>

<translate>
==== Namespace Mapping and Manifest File Name ====  </translate>
<translate> Automatic namespace mapping won't work with extension manifest files named <code>manifest.xml</code>. See: https://github.com/joomla/joomla-cms/issues/37750</translate>

<noinclude>
[[Category:Compatibility{{#translation:}}]]
[[Category:Development{{#translation:}}]]
[[Category:Platform{{#translation:}}]]
[[Category:Migration{{#translation:}}]]
[[Category:Update Working Group{{#translation:}}]]
[[Category:Joomla! 4.x{{#translation:}}]]
[[Category:Joomla! 4.0{{#translation:}}]]
</noinclude>

How to use user state variables

2023-05-10T22:21:17Z

Cmb: Replaced deprecated 'source' tags with 'syntaxhighlight' tags. Corrected some URLs.

Joomla! provides built in functionality to make it easy for Joomla! developers to store and retrieve variables that are stored with the session.

==Why Should I Use the Joomla! User State Variables?==
Joomla!'s built in session handling capabilities make it easy to retain values of certain variables across page accesses. This makes development much simpler because the developer no longer has to worry about losing variable values if it is left out of a form. Storing variables with sessions also makes the application cleaner and tidier since it reduces the amount of form variables, and persistent variables no longer have to be passed in either the query string (making very long URLs) or in POST variables.

The downside of using session variables is that it makes page URLs stateful. That is, if used improperly, a URL might point to certain information in one context, but different information in another context. This can make search engines less effective since the web crawler might pull up a certain page using a certain URL, that when the user links to the URL from the search engine, might pull up a different page, resulting in user confusion and frustration.

==Setting and Retrieving User State Variables==
There are two ways to set user state variables. The first is fairly intuitive, and is done using the [https://api.joomla.org/cms-2.5/classes/JApplication.html#method_setUserState JApplication::setUserState] method. The second is a little less obvious, and uses the [https://api.joomla.org/cms-2.5/classes/JApplication.html#method_getUserStateFromRequest JApplication::getUserStateFromRequest] method. There are also two ways to retrieve user state variables. The first is using the [https://api.joomla.org/cms-2.5/classes/JApplication.html#method_getUserState JApplication::getUserState] method, and the second is to use the [https://api.joomla.org/cms-2.5/classes/JApplication.html#method_getUserStateFromRequest JApplication::getUserStateFromRequest] method. [https://api.joomla.org/cms-2.5/classes/JApplication.html#method_getUserStateFromRequest JApplication::getUserStateFromRequest] can be used to both store and retrieve user state variables.

The following methods are used for accessing the user state variables:

===Method 1: JApplication::setUserState===
<syntaxhighlight lang="php">
$mainframe =JFactory::getApplication();

// store the variable that we would like to keep for next time
// function syntax is setUserState( $key, $value );
$mainframe->setUserState( "$option.state_variable", "state1" );
</syntaxhighlight>

The first parameter is the key under which to store the variable. You will note that in this example the key began with the $option variable. Although the value for $key is arbitrary, it is good practice to use this as a prefix for all user state variables since these are all in the same name space. Using an extension-specific prefix avoids extensions interfering with each other. In the example above, state_variable is the name of the state variable that will be stored, and the second parameter is the value to store with the state variable.

===Method 2: JApplication::getUserStateFromRequest===
<syntaxhighlight lang="php">
$mainframe =JFactory::getApplication();

// retrieve the value of the state variable. First see if the variable has been passed
// in the request. Otherwise retrieve the stored value. If none of these are specified,
// the specified default value will be returned
// function syntax is getUserStateFromRequest( $key, $request, $default );
$stateVar = $mainframe->getUserStateFromRequest( "$option.state_variable", 'state_variable', 'state1' );
</syntaxhighlight>

The first parameter is the key under which to store the variable. Note again that this is prefixed with the name of the current extension. This method will update the user state variable by looking in the variables that were passed with the request (in either GET or POST) and updating the user state variable if the specified request variable is set. This can be used to set user state variables with values that are passed from forms (i.e. from the user). If an existing value can be found either in the request or in the stored state variable, this is returned. Otherwise, the specified default value is returned (if it is specified), or NULL is returned if no value can be found.

===Method 3: JApplication::getUserState===
<syntaxhighlight lang="php">
$mainframe =JFactory::getApplication();

// retrieve the value of the state variable. If no value is specified,
// the specified default value will be returned.
// function syntax is getUserState( $key, $default );
$stateVar = $mainframe->getUserState( "$option.state_variable", 'state1' );
</syntaxhighlight>

The first parameter is the key under which to store the variable. Note again that this is prefixed with the name of the current extension. This method will retrieve the value of the specified user state variable. If this user state variable has not been set, then the value is read from the $default parameter. If the user state variable has not been set and $default is not specified, the method will return NULL.

==A Real Life Example of the Use of Joomla! User State Variables==
The following code excerpts are taken from the admin section of the Newsfeed component, which is a core Joomla! component. These snippets are meant to demonstrate how user state variable can be used in an actual application.

===Purpose===
Notice that many components that have database tables associated with them present to the user a list of items. In the case of the Newsfeed component, the administration section presents a list of Newsfeeds. If there are too many newsfeeds to list on one page, two variables are used to keep track of where the user is in the list: the limit variable and the limitstart variable. The Newsfeed component (like other components) uses state variables to store the value of limit and limitstart between page requests.

If a user goes to administer another component or navigates away from the component, these values are available when the user returns. In addition, these values only have to be passed if they are being changed. The developer does not have to bother with inserting hidden form feeds to pass these values along.

===Setting and Retrieving the Variables===
The following code is used to set and retrieve the values of these variables:
<syntaxhighlight lang="php">
$mainframe =JFactory::getApplication();

$limit = $mainframe->getUserStateFromRequest( "limit", 'limit', $mainframe->getCfg('list_limit') );
$limitstart = $mainframe->getUserStateFromRequest( "$option.limitstart", 'limitstart', 0 );
</syntaxhighlight>

The first variable that is stored is the limit variable. The limit variable specifies how many records should be retrieved from the database and displayed. Note that there is no '''$option''' prefix in the '''$key''' parameter. This variable is used as a global parameter (and its initial value is retrieved from the site configuration value). The value is retrieved from the request variable called 'limit'. If the state variable has not been specified yet and it is not specified in the request, then the value is retrieved from the site configuration using the [[JApplication/getCfg|JApplication::getCfg]] method.

The second variable that is stored is the limitstart variable. This specifies how many records to skip over before returning records from the database. Each component has its own list and so keeps its own place in its own list. The '''$option''' parameter in this case has the value 'com_newsfeeds', and so the session variable name is 'com_newsfeeds.limitstart'.

===Passing Values to JPagination class===
In this example, the stored values are used as parameters for constructing the pagination class, which helps the developer implement pagination functionality.

Ultimately, this will result in the following form elements being displayed on the page:
<syntaxhighlight lang="html4strict">
<div class="limit">Display #
<select name="limit" id="limit" class="inputbox" size="1" onchange="document.adminForm.submit();">
<option value="5" selected="selected">5</option>
<option value="10" >10</option>
<option value="15" >15</option>
<option value="20" >20</option>
<option value="25" >25</option>
<option value="30" >30</option>
<option value="50" >50</option>
<option value="100" >100</option></select>
</div>

<div class="start"><span>Start</span></div>
<div class="button2-right off"><div class="prev"><span>Prev</span></div></div>
<div class="button2-left"><div class="page">
<span>1</span>
<a title="2" onclick="javascript: document.adminForm.limitstart.value=5; document.adminForm.submit();return false;">2</a>
</div></div>

<div class="button2-left"><div class="next">
<a title="Next" onclick="javascript: document.adminForm.limitstart.value=5; document.adminForm.submit();return false;">Next</a>
</div></div>

<div class="button2-left"><div class="end"><a title="End" onclick="javascript: document.adminForm.limitstart.value=5; document.adminForm.submit();return false;">End</a></div></div>

<div class="limit">
Results 1 - 5 of 10</div>

<input type="hidden" name="limitstart" value="0" />
</syntaxhighlight>

One may be observant and notice that the values are passed in hidden form elements anyway, and claim therefore that it is really not necessary to use state variables. But this will not help in the situation where the user has navigated away from the component, and it will also not help in the situation which occurs in the list, for example, where each newsfeed is listed and linked using a standard link, and not the form. Using state variables saves having to add limit and limitstart on to the end of these URLs.

==See Also==
For information on the Joomla! API relating to session variables, please consult the following sources:
* [https://api.joomla.org/cms-2.5/classes/JApplication.html JApplication]
* [https://api.joomla.org/cms-2.5/classes/JSession.html JSession]
<noinclude>[[Category:Development]]</noinclude>

J4.x:Selecting data using JDatabase

2023-05-10T21:16:25Z

Cmb: Replaced deprecated 'source' tags with 'syntaxhighlight' tags.

How to debug your code

2023-05-09T21:11:36Z

Cmb: Corrected some markup, phrasing and syntax highlighting.

<noinclude><languages /></noinclude>
<translate>
==The Easy Way 1 (''echo'')== 
</translate>
<translate> The simplest way to see what is going on inside your code is to temporarily add ''echo'' statements for variables to show their values on the screen. For example, say you want to know what the value of some variables are when $i is "5". You could use code like this:</translate>

<syntaxhighlight lang="PHP">for ( $i = 0; $i < 10; $i++ ) {
if ( $i == 5 ) {
echo '$i=' . $i;
// other echo statements
}
}</syntaxhighlight>

<translate> This works for simple situations. However, if you are planning on doing a lot of Joomla! development, it is worth the effort to install and learn an integrated development environment (IDE) that includes a real PHP debugger.</translate>

<translate>
==The Easy Way 2 (Joomla ''message'')== 
</translate>
<translate> Your code won't always display simple echo statements. In that case you can try this alternative, still an easy way:</translate>
<syntaxhighlight lang="PHP">JFactory::getApplication()->enqueueMessage('Some debug string(s)');</syntaxhighlight>
<translate> You can choose different [[Display_error_messages_and_notices|message types]] which correspond to grouping with different styles (colors mainly).</translate>

<translate>
==Joomla Logging== 
</translate>
<translate> Joomla allows you to log messages to a log file, and optionally also display these on the web page (in the same way as ''enqueueMessage'' above) and on the Joomla Debug Console (described below).</translate>

<translate> To log a message in the log file:</translate>
<syntaxhighlight lang="PHP">
JLog::add('my error message', JLog::ERROR);
</syntaxhighlight>
<translate> To log a message and also display it on the screen:</translate>
<syntaxhighlight lang="PHP">
JLog::add('my error message', JLog::ERROR, 'jerror');
</syntaxhighlight>
<translate> The logging to the log file and to the Debug Console is controlled via the settings of the System – Debug plugin. To understand how this works, and the relevant settings of the System-Debug plugin, read the Joomla documentation page on [[S:MyLanguage/Using JLog|Using JLog]].</translate>

<translate>
==Using an IDE== 
</translate>
<translate> Check this 3 minutes video that shows</translate> [http://www.youtube.com/watch?v=sP4dHAuq2kc&feature=youtu.be <translate> how you can debug your code with a browser and an IDE</translate>]

{{#ev:youtube|sP4dHAuq2kc}}

<translate> Many Joomla! developers use the Eclipse IDE. This is free and includes a debugger. Instructions for installing it are available at [[S:Mylanguage/Setting up your workstation for Joomla! development|Setting up your workstation for Joomla! development]], or you can watch this video on setting up Eclipse and Xdebug:</translate>

{{#widget:YouTube|id=MiIEF8-XAkc}}
<translate>
==Using the PHP Expert Editor== 
</translate>
<translate> Another option is the PHP Expert editor with an installed extension for debugging. Add the following lines to the ''php.ini'' file:</translate>

extension=php_dbg.dll
[Debugger]
debugger.enabled=on
debugger.profiler_enabled=off

<translate> It is best to set ''profiler_enable'' to ''off''. Then you need to set options in the Run/Options menu to use HTTP-server and the directory in which your script is located.</translate>
<translate>

If all options are correct, you may run your script in debug mode by clicking on the Debug button (F8).</translate>

<translate>
==J!Dump== 
</translate>
<translate> An often handy extension that can be found in the JED is the J!Dump extension that will allow you to dump variable, stack traces, and system information into a popup window at run time. This extension works like the PHP command ''var_dump'' but formats the output in a more readable fashion.</translate>

<translate>
==Joomla Debug Console== 
</translate>
<translate> The Debug Console can be enabled from the Joomla! Global Configuration, System tab, by setting the Debug System option to Yes. Once enabled, the output of the debug plugin will be displayed at the bottom of each page.</translate>
[[File:Jdebug-module-<translate> en</translate>.jpg|<translate> The JDebug Plugin output</translate>]]

<translate> Setting this Debug System option also sets the global variable ''JDEBUG'' to true, so that you can control whether to log messages by testing this variable:</translate>
<syntaxhighlight lang="PHP">
if(JDEBUG)
{
// whatever debugging code you want to run, e.g.
JLog::add('my debug message', JLog::DEBUG, 'my-debug-category');
}
</syntaxhighlight>

<translate>

This plugin provides information that can assist in debugging and improving the performance of your component.</translate>

<translate>
===Session Information=== 
</translate>

<translate> This section displays state variables which are stored in the Session data to enable them to be 'remembered' across HTTP requests. Examples include variables defining the current search filters the user has defined, the pagination point in a list of records, etc.</translate>

[[File:session-<translate> en</translate>.jpg]]

<translate>
===Profile Information=== 
</translate>

<translate> The Profile Information tab from the debug plugin provides information about the time and memory taken to render the page based on each of the application events. This can help to identify areas outside of network speed that are contributing to long page load times and high server memory usage.</translate>

[[File:Jdebug-profile-<translate> en</translate>.jpg|<translate> JDEBUG Profile</translate>]]

<translate>
===Database Queries=== 
</translate>

<translate> One of the most useful tabs is the Database Queries tab. This will provide a log of all queries that have been executed while loading the page and identify both the time taken to execute the query and whether duplicate queries have occurred. This is particularly useful when debugging performance problems on larger components as duplicate queries are often a contributing factor.</translate>

[[File:Jdebug-query-<translate> en</translate>.jpg]]

<translate>
==Komodo IDE== 
</translate>

[[S:MyLanguage/Debugging Joomla with Komodo IDE|Debugging Joomla with Komodo IDE]]

<noinclude>
[[Category:Development{{#translation:}}]]
[[Category:Video{{#translation:}}]]
</noinclude>

WebAuthn Passwordless Login

2023-05-05T22:59:36Z

Cmb: Phrasing, capitalization, punctuation and markup changes.

<noinclude><languages /></noinclude>
<noinclude>{{Joomla version|version=4.x}}</noinclude>
{{-}}
<translate>
== System - WebAuthn Passwordless Login == 
</translate>

<translate> Web Authentication, or WebAuthn for short, allows a user to securely log into a site without using a password — though you still need to provide your username. It uses strong cryptography and in a manner which is extremely resistant to the most common problems of passwords: someone guessed it (brute force attack), someone intercepted it (man in the middle attack), someone tricked you into divulging it (phishing attack), someone cracked it after getting hold of a copy of your database data (SQL injection attacks) or someone stole it.</translate>

<translate> WebAuthn is not just secure; it is also user friendly! You no longer have to remember long passwords or use a password manager. All you need is an ''authenticator'', sometimes also called a ''passkey''. An authenticator can have many forms, physical or virtual. It can be a separate hardware key connecting to your device via USB, Bluetooth or NFC. It can be your device itself, unlocking its built-in authenticator with a PIN, fingerprint reader, facial scan or similar biometric check. This feature already works on Android and iOS/iPadOS devices and we're working on enabling it on Windows as well. It can even be your phone — currently this is possible with Android phones but this feature is also coming to iOS/iPadOS devices.</translate>

<translate> WebAuthn only works over HTTPS and only when your site is using a valid, trusted certificate for it. Don't worry, you don't have to spend any extra money; free of charge services such as Let's Encrypt are typically integrated into web hosting control panels and work perfectly fine with WebAuthn.</translate>

<translate> WebAuthn uses public key cryptography, the same proven technology that keeps your sites safe with HTTPS, your banking information secure and so on. The private key never leaves the authenticator. Your site only stores a public key. Even if you suffer a data breach the attacker will be left with a practically useless public key; it would take them thousands to millions of CPU years to crack it as opposed to a few minutes or hours required to crack the hash of a fixed password that you can remember.</translate>

<translate> WebAuthn is the future of authentication. Easy, secure and hassle-free. Everything that fixed passwords are not.</translate>

<translate> The following picture shows a hardware device inserted into a laptop computer's USB port. It cost £15 in February, 2022.</translate>

[[File:j4x-passwordless-login-hardware-device.jpg|center|Hardware device]]

<translate> WebAuthn uses a system plugin that is enabled by default. A ''Web Authentication'' button will be present in default Joomla 4 login screens, as illustrated in the Administrator login screen:</translate>

[[File:j4x-passwordless-login-admin-login.png|center|border|Administrator Login]]

<translate>
== User Configuration == 
</translate>

The user must first register with a normal Username and Password. After logging in, go to the User Profile form. For an Administrator:
* Select {{rarr|User Menu, Edit Account, W3C Web Authentication (WebAuthn) Login}} to bring up the form, initially with no authenticators registered.
* Select '''Add New Authenticator'''

The exact presentation of the next step depends on your browser. Typically, you will see an alert, message or window asking you to select an authenticator type or, if you're using a hardware authenticator attached to your device, reminding you to press the button on the hardware authenticator. For security and practical reasons there is a relatively short time interval allowed for activating the authenticator: 60 seconds.

[[File:j4x-passwordless-login-hardware-propmpt.png|center|Hardware Prompt]]

Once you unlock your authenticator — tapping on a button, scanning your fingerprint/face, entering a PIN or a combination of the above depending on your authenticator — the message disappears, the authenticator is registered and the screen appears as follows:

[[File:j4x-passwordless-login-registered-authenticator.png|center|Registered Authenticator]]

It is important to note that you can only register or remove authenticators on your own user account. For security reasons, even a Super User is disallowed from registering, editing or adding authenticators on other user accounts.

=== Authenticators ===
You can use any FIDO U2F or FIDO2 authenticator. FIDO U2F is an older standard which supports a more limited, less secure selection of cryptographic methods. FIDO2 is the newer standard which supports much more secure cryptographic methods including Elliptic Curve Cryptography, a cryptographic method which is believed to be resistant even to quantum computing (if and when it becomes a practical reality). Moreover, FIDO2 authenticators can be set up to have additional protections such as a PIN or a biometric control (e.g. fingerprint scan) which means that even if you lose physical possession of the authenticator itself whoever finds it cannot log into your sites.

If you are looking to buy a hardware authenticator you can look for "FIDO2" in your favorite marketplace, such as Amazon. There is a wide selection to choose from.

You may also use a software FIDO key such as Krypton as your authenticator.

Many devices have built-in FIDO2-compliant authentication:

* Windows 10 and 11 have Windows Hello with a PIN, fingerprint scanner, facial recognition camera or a combination of hardware key and PIN. Support for Windows Hello is being added to the plugin with a release target of Joomla 4.2.0.
* macOS has TouchID on all laptops with the T2 chipset or those based on Apple Silicon using the built-in TouchID sensor, as well as all Apple Silicon–based desktops using the new Apple Aluminium keyboard with a fingerprint scanner.
* iOS/iPadOS has TouchID on all devices with a fingerprint scanner and FaceID on all newer devices with a FaceID infrared dot projection camera.
* Some Android devices have a fingerprint scanner or a face recognition camera. These can also work as FIDO2 authenticators, on Android 9 or later using Google Chrome at least.
* Other devices may be available too. For example, Android phones using [https://groups.google.com/a/fidoalliance.org/g/fido-dev/c/go6GoFW27Dw/m/9flCLR5pBQAJ?pli=1 caBLE]

=== WebAuthn Compatible Browsers ===
Chromium and Firefox based browsers have supported WebAuthn since early 2019.

Safari and all iOS/iPadOS browsers (which are, in fact, Safari with a different skin) fully support WebAuthn since iOS/iPadOS 13 released late 2019.

Practically speaking, if your operating system and browser were released after mid-2020 you should have no problem. Only some uncommon browsers still lack support for WebAuthn.

== Authentication ==
To login you must enter your username in the login form Username field. You do not need to enter your password but if your browser enters it for you just leave it. The password is '''not''' sent to the server when the form is submitted via the Web Authentication button.

It follows that you can login with either your Username and Password or Username and Web Authentication.

== How To Disable the Plugin ==
If you do not wish to allow WebAuthn, just go to the list of plugins and find ''System - WebAuthn Passwordless Login'' in the System group and disable it. There are no parameters to set.

== Server Requirements ==
For WebAuthn to work the following preconditions must be met:

* HTTPS with a valid, signed certificate. Most hosts let you use free of charge certificates issues by Let's Encrypt. These work perfectly fine with WebAuthn.
* The OpenSSL extension for PHP must be installed and enabled.
* The PHP extension GMP or the PHP extension BCmath must be installed and enabled (either will do).
* The Sodium library should ideally be enabled; it enables the use of Elliptic Curve Cryptography on compatible FIDO2 authenticators which, as we said, is the most secure cryptographic method.

== Frequently Asked Questions and Troubleshooting ==
=== I can't see the “Web Authentication” login button ===
You are not accessing your site under HTTPS. WebAuthn is only available for HTTPS sites with a valid certificate. This is a security precaution baked into the WebAuthn standard. The plugin actually checks if the site is accessed through HTTPS using Joomla's Uri class. In rare cases where the server lies about the protocol you might not see the button even though your site (claims to be) HTTPS. The same applies if you have edited your ''configuration.php'' file and set up the optional ''$live_site'' configuration parameter with an ''http://'' protocol prefix instead of ''https://''.

Also note that third party login modules and components implementing their own login form may not display these buttons just yet. We added new infrastructure to support them, much like what we had to do in Joomla! 3.2 to support Two Factor Authentication.

=== I still need to provide a username. Isn't WebAuthn supposed to get rid of usernames? ===
Not really, no. The current specification of WebAuthn does not provide identity management. Web browsers require us to send them a list of acceptable WebAuthn public keys during the login phase. This means that we need your username to fetch them.

That said, using WebAuthn finally makes it clear that usernames '''are not to be considered secrets'''. They are considered public information which can be freely transmitted to an adversary, just like the public keys stored in the site's database. The only secret is stored in the authenticator itself and never leaves the authenticator!

=== I have registered an authenticator but trying to log in tells me that I haven't. Is this a bug? ===
It is a bug but not with the WebAuthn plugin itself.

One or more plugins on your site throw PHP Notices, Warnings or Errors, thus corrupting the reply sent back by your server. As a result the JavaScript on the page cannot parse the server response and is unsure whether any authenticators are registered by the user.

Go to your site's {{rarr|Backend,System,Global Configuration}} and set ''Error Reporting'' to ''None''. In most cases of misbehaving core and 3PD plugins this is enough. Otherwise please examine the output of the request using your browser's developer tools to see what is corrupting the request.

=== There is no prompt on Safari to use my authenticator ===
This should no longer be happening with iOS 13, iPadOS 13 and macOS Catalina or any later version.

This is a Safari bug in older versions of Safari. Older versions of Safari only included support for WebAuthn as an experimental feature and not quite finished.

=== I cannot use a biometric sensor (TouchID, fingerprint, Windows Hello) ===
Some older Chromium-based browsers (except Google Chrome proper) didn't have full support for built-in authenticators. They would crash or hang when you tried using one. These issues were fixed in these browsers around mid-2020.

If you are using Windows please remember that your device MUST have a Trusted Platform Module (TPM) chip and it must be enabled in the BIOS. Just having a Windows Hello-compatible biometric sensor won't do the trick. This is a security precaution in the WebAuthn standard itself: the authenticator information must be processed using secure, tamper-resistant hardware to prevent key subversion (e.g. malware running on the computer cannot steal the key used for authentication).

Finally, do keep in mind that Windows Hello support is still being worked on and will be released with Joomla 4.2.

=== If I can use a software authenticator why should I bother with a hardware token? ===
The linchpin of WebAuthn is the absolute secrecy of the private key. It is only known to the authenticator and it should be impossible to communicate to the outside world.

In the case of a hardware authenticator, be it a discrete hardware device or a TPM / Secure Enclave built into your device, this is a given by the very nature of that hardware.

A software authenticator generates a secret key and stores it in the filesystem. However, it is still a regular software application which runs inside your regular operating system, be it your phone's or your computer's. As a result it is susceptible to several classes of attacks which can be used to surreptitiously steal information (security issues in the software itself, malware using Spectre-class vulnerabilities in modern CPUs etc).

So, a software authenticator is far more convenient and secure than a regular password but a hardware authenticator offers the best security. Choose your authenticator based on your budget and security needs.

Considering that the price of a FIDO key–-which is compatible with WebAuthn–-is under €10 on Amazon you can use a hardware authenticator in most practical use cases.

=== Why are the credentials encrypted in the database? Isn't this an overkill? ===
The only thing stored in the database is the public key returned by the authenticator when we are performing the attestation ceremony (that's the formal name of registering an authenticator per the WebAuthn specification). Being a public key it does not need protecting from reading. Even if an unauthorised user was able to read this information they would not be able to impersonate the authenticator e.g. by cloning it.

However, if a malicious user had write access just to the ''#__webauthn_credentials'' database table, without read access to the filesystem and without write access to any other table, they could conceivably '''add''' their own authenticator, therefore being able to impersonate the targeted user on the system. This is a theoretical attack since they would also need to know the user handle for the user they are attacking which is harder to derive without some inside knowledge of the site itself. Besides, having write access to just this table and not the entire database (in which case they could create a new Super User) is extremely unlikely. Still, we are encrypting the credentials to make it impossible for even this theoretical attack to succeed.

We are fully aware that if a user has read access to the server filesystem they have access to the encryption key and the database connection information, all of which is stored in ''configuration.php''. However, in this case you are already hacked: the attacker can read ''configuration.php'' therefore they know how to connect to your database. In this case they can do whatever they please to your site, including deleting all existing Super Users and creating their own Super User account. Therefore there's no reason to try to address this situation; you'd be fully compromised (hacked). The only that could be a saving grace is regular, tested, off-site backups.

=== I have set up Two Factor Authentication but I am logged in without providing my Secret Key. Isn't this insecure? ===
No, it's intentional and by design.

When we added Two Factor Authentication (TFA) in Joomla! 3.2 you were only able to log into your site using a username and password. Passwords can be stolen or guessed. Therefore TFA was the only way to provide a modicum of security on high risk and high value targets. That was back in 2013.

WebAuthn is an entirely different authentication solution which has none of the problem of fixed passwords. It uses strong cryptography and secure hardware to make it practically impossible to subvert the authentication cryptographic keys. It's also unphishable, i.e. you cannot be fooled into using it on an impersonating site since the WebAuthn credential is tied to the exact domain name for which it was issued. (Yes, if you use multiple domains for your site or transfer your site to another domain you'll need to re-register all your WebAuthn authenticators – you got that right!). As a result, authentication with WebAuthn is incredibly secure and supersedes the reasons that necessitated TFA. This means that if you successfully authenticate using WebAuthn the TFA secret key needs not be-–and is therefore not–-checked at all.

In an ideal world, you would only be able to log into your site using WebAuthn. This is a feature we are working on and you may not want to enable; after all, if your domain name changes or you lose access to or reset all of your WebAuthn authenticators, you'd be locked out of your site. Therefore you should still enable TFA on your user account on the basis that password login can still be used as a fallback to logging into your site and must be protected from known attacks against fixed passwords.

=== Isn't TFA good enough? Why do we need WebAuthn? ===
TFA alone is good enough in most cases but suffers from two issues.

First, it is awkward user experience. You need to provide your ever-changing secret key with your username and password. Most people use TOTP (the six digit PIN that changes every 30 seconds) that slows down logging in and frustrates users. Using a YubiKey is much faster but more expensive and complicated to provision when you have more than a couple of users on the site. A YubiKey also has an expected life of about two years of everyday use when generating One Time Passwords. (It runs out of the write-once memory it uses to keep track of the signatures it has issued.)

Second, if you are using TOTP you still are susceptible to security issues such as keyloggers, phishing and the possibility that the secret key used for generating the TOTP is stolen. Moreover, with one million possibilities and thirty seconds to try them, it is conceivable that an attacker can get lucky since Joomla doesn't lock your account or otherwise employ rate limiting for failed login attempts. While these protections could be implemented, the implementation itself could be abused to create a denial of service situation which locks a legitimate user out of their site while the attacker is busy infiltrating it. It's a case of the cure being worse than the disease.

WebAuthn greatly improves the user experience. Major browsers embraced WebAuthn and offer a compelling user experience, guiding the users into using authenticators successfully. Logging in with WebAuthn is more convenient even when compared to using a password manager's auto-fill feature. With recent versions of mobile operating systems even that experience, once slightly confusing, is rapidly becoming easier than passwords and TFA ever were.

Where WebAuthn is truly killing it is at the security front. By virtue of using secure hardware and strong validation of the site's domain name it is practically immune to keyloggers, phishing and key subversion. It even has built-in protection against key cloning. Yes, you can still lose your hardware--but FIDO2 authenticators, be they external devices or built-in, can be locked out with a PIN or biometrics. Overall, using WebAuthn with FIDO2 authenticators is more theft- and loss-resistant than your house or car keys.

== Developer Notes ==
=== Extra Login Buttons ===
The plugin module and ''com_users'' now use the ''onUserLoginButtons'' event, defined and called in Joomla\CMS\Helper\AuthenticationHelper::getLoginButtons, to retrieve the definitions of any additional buttons which need to be placed after the regular login button.

All developers implementing a login module or, more generally, a login form should also use the Joomla\CMS\Helper\AuthenticationHelper::getLoginButtons public static method to retrieve said definitions and render these buttons to make their software fully compatible with Joomla 4.

Developers wishing to implement custom buttons should look at how the WebAuthn system plugin implements this functionality. Such buttons can be used for implementing third party single-sign-on services or even logging in using third party identity services such as those offered by popular social media (Facebook, Google, Twitter, GitHub etc).

This change does not adversely impact backwards compatibility. Third-party login modules and login forms will continue functioning normally even if they do not implement the extra login buttons feature with the notable omission of integration afforded by said feature such as Web Authentication itself. That is to say they won't stop functioning (which would be a b/c break) but they won't be feature-complete.

=== Allowing ''com_ajax'' in the Backend Login Page ===
The Administrator login page whitelists ''com_ajax'' in AdministratorApplication so it can be used to handle requests by guest users.

This change does not cause backwards compatibility issues as long as developers use sane practices and do not assume that being called by ''com_ajax'' in the Backend is proof that the user is logged into the Backend. That would be a bad security practice. The sane practice is to use Joomla's User object to detect if it's a guest user and, if not, whether the user is allowed a permission required to effect the action requested through ''com_ajax''. That is to say, if this change has broken your code then your code was already broken and needed to be reworked anyway.

== Further Information ==
''The initial documentation of this feature is in the pull request at [https://github.com/joomla/joomla-cms/pull/28094 PR #28094].

<noinclude>
[[Category:Joomla! 4.x{{#translation:}}]]
[[Category:Security{{#translation:}}]]
[[Category:Joomla! Wiki need pages]]
</noinclude>

J4.x:Web Assets

2023-05-02T23:51:48Z

Cmb: Phrasing, capitalization and markup changes.

<noinclude><languages /></noinclude>
<translate>
== Concept == 
</translate>

<translate> In the Frontend world many assets are related. For example, our ''keepalive'' script depends on the ''core.js'' file for options management. In Joomla there never was an easy way to specify this; you just had to include multiple files. Joomla 4 changes this with the concept of web assets.</translate>

<translate>
== Definition == 
</translate>

<translate> Related assets are defined in a JSON file such as [https://github.com/joomla/joomla-cms/blob/7b72c565b610e02c1b01f8958d622879631fa6a2/build/media_source/system/joomla.asset.json#L14-L21 system/joomla.asset.json#L14-L21]</translate>

<translate> This has a structure of having a schema definition (for validation), name, version, license and then one or more asset definitions. Assets comprise a list of JavaScript files and CSS files related to the assets and any dependencies. The dependencies section is just a list of asset names that are required for the asset to function. Example:</translate>

<syntaxhighlight lang="json">
{
"$schema": "https://developer.joomla.org/schemas/json-schema/web_assets.json",
"name": "com_example",
"version": "4.0.0",
"description": "Joomla CMS",
"license": "GPL-2.0+",
"assets": [
{
"name": "bar",
"type": "style",
"uri": "com_example/bar.css"
},
{
"name": "bar",
"type": "script",
"uri": "com_example/bar.js"
},
{
"name": "beer",
"type": "style",
"uri": "com_example/beer.css",
"dependencies": [
"bar"
],
},
{
"name": "beer",
"type": "script",
"dependencies": [
"core",
"bar"
],
"uri": "com_example/beer.js",
"attributes": {
"defer": true,
"data-foo": "bar"
}
}
]
}
</syntaxhighlight>

<translate> The <syntaxhighlight lang="json" inline>$schema</syntaxhighlight> attribute is a schema definition file that allows you to validate your file using JSON Schema. Read [https://json-schema.org/understanding-json-schema/index.html the official website] for more information on how JSON schema validation works.</translate>

<translate> '''Note''' Having ''joomla.asset.json'' for your extension or template are recommended but not required for WebAsset to work. (See the next section).</translate>

<translate> '''Note''' It is not recommended to add an inline asset to a JSON file. Prefer to use a file.</translate>

<translate>
== Explaining Asset Stages == 
</translate>

<translate> Each asset has two stages: registered and used.</translate>

<translate>

'''Registered''' is where an asset is loaded into '''WebAssetRegistry'''. That means '''WebAssetManager''' knows about the existence of these assets, but will not attach them to a document while rendering. All assets loaded from joomla.asset.json is at '''registered''' stage.</translate>

<translate> '''Used''' is where an asset is enabled via "$wa->useAsset()" (->useScript(), ->useStyle(), ->registerAndUseX() etc). That means '''WebAssetManager''' will attach these assets and their dependencies to a document while rendering.</translate>

<translate> An asset cannot be used if it was not registered before. This will cause an unknown asset exception.</translate>

<translate>
== Register an Asset == 
</translate>

<translate> All known assets loaded and then stored in '''WebAssetRegistry'''. (To enable/disable an asset item, use '''WebAssetManager'''. See the next section.)</translate>

<translate> Joomla! will look for next assets definition automatically at runtime (in following order):</translate>
<pre>
media/vendor/joomla.asset.json (on first access to WebAssetRegistry)
media/system/joomla.asset.json
media/legacy/joomla.asset.json
media/{com_active_component}/joomla.asset.json (on dispatch the application)
templates/{active_template}/joomla.asset.json
</pre>

<translate> And load them to the registry of known assets.</translate>

<translate> '''Note''' Each following assets definition will override asset items from previous assets definition, by item name.</translate>

<translate> You can register your own assets definition via '''WebAssetRegistry''':</translate>

<syntaxhighlight lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();
$wr = $wa->getRegistry();
$wr->addRegistryFile('relative/path/to/your/joomla.asset.json');
</syntaxhighlight>

<translate> To add a custom asset item at runtime:</translate>
<syntaxhighlight lang="php">
$wr->add('script', new Joomla\CMS\WebAsset\WebAssetItem('foobar', 'com_foobar/file.js', ['type' => 'script']));
</syntaxhighlight>

<translate> Or more simply, using '''WebAssetManager''':</translate>
<syntaxhighlight lang="php">
$wa->registerScript('foobar', 'com_foobar/file.js');
</syntaxhighlight>

<translate> The new asset item ''foobar'' will be added to the registry of know assets, but will not be attached to a document until your code (a layout, template etc) will request it.</translate>

<translate> To check whether an asset exists:</translate>
<syntaxhighlight lang="php">
if ($wa->assetExists('script', 'foobar'))
{
var_dump('Script "foobar" exists!');
}
</syntaxhighlight>

<translate>
== Enabling an Asset == 
</translate>
<translate> All asset management in the current Document handled by '''WebAssetManager''', which is accessible with '''$doc->getWebAssetManager();'''</translate>
<translate> By using AssetManager you can enable or disable needed asset easily in Joomla! through a standard methods.</translate>

<translate> To enable an asset in the page, use the useAsset function:</translate>

<syntaxhighlight lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();
$wa->useScript('keepalive');

// Or multiple
$wa->useScript('keepalive')
->useScript('fields.validate')
->useStyle('foobar')
->useScript('foobar');

// Add new asset item with dependency and use it
$wa->registerAndUseScript('bar', 'com_foobar/bar.js', [], [], ['core', 'foobar']);
</syntaxhighlight>

<translate> '''WebAssetManager''' will look to '''WebAssetRegistry''' whether the requested asset exists, and will enable it for current Document instance. Otherwise it will throw an UnknownAssetException.</translate>

<translate> To disable an asset in the page use the ''disableAsset'' function. The example below will disable the ''jquery-noconflict'' asset from being loaded.</translate>

<syntaxhighlight lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();
$wa->disableScript('jquery-noconflict');
</syntaxhighlight>

<translate> '''Note''' If there are any dependencies to the disabled asset, this asset will be re-enabled automatically, no matter what.</translate>

<translate> To check whether an asset is enabled, and the asset state:</translate>

<syntaxhighlight lang="php">
// Checking whether an asset are active (enabled manually or automatically as dependency).
if ($wa->isAssetActive('script', 'foobar'))
{
var_dump('Script "foobar" is active!');
}

// Checking state
switch($wa->getAssetState('script', 'foobar')){
case Joomla\CMS\WebAsset\WebAssetManager::ASSET_STATE_ACTIVE:
var_dump('Active! Was enabled manually');
break;
case Joomla\CMS\WebAsset\WebAssetManager::ASSET_STATE_DEPENDENCY:
var_dump('Active! Was enabled automatically while resolving dependencies');
break;
default:
var_dump('not active!');
}
</syntaxhighlight>

<translate>
== Overriding an Asset == 
</translate>

<translate>
Overriding may be useful when you need to redefine the URI of asset item or its dependencies.
As already noted, each of the following assets definition from joomla.asset.json will override asset items from previous assets definitions, by item name.</translate>
<translate>
If you provide joomla.asset.json which contains already loaded asset items, they will be replaced with your items.
Another way to override in the code is to register an item with the same name.
Example, we have ''foobar'' script, that loads the ''com_example/foobar.js'' library, and we want to use CDN for this exact library:</translate>

<translate> How it defined in the system initially:</translate>

<syntaxhighlight lang="json">
...
{
"name": "foobar",
"type": "script",
"uri": "com_example/foobar.js",
"dependencies": ["core"]
}
...
</syntaxhighlight>

<translate> To override the URI, we define the asset item with ''foobar'' name in our joomla.asset.json:</translate>

<syntaxhighlight lang="json">
...
{
"name": "foobar",
"type": "script",
"uri": "http://foobar.cdn.blabla/foobar.js",
"dependencies": ["core"]
}
...
</syntaxhighlight>

<translate> Or, register new asset item with AssetManager:</translate>

<syntaxhighlight lang="php">
$wa->registerScript('foobar', 'http://fobar.cdn.blabla/foobar.js', [], [], ['core']);
</syntaxhighlight>

<translate>
== Working with Styles == 
</translate>

<translate> AssetManager allows you to manage style sheet files. Style sheet asset items have a type "style".</translate>

<translate> Example JSON definition of item in joomla.asset.json:</translate>

<syntaxhighlight lang="json">
...
{
"name": "foobar",
"type": "style",
"uri": "com_example/foobar.css"
}
...
</syntaxhighlight>

<translate>
=== Methods to Work with Styles === 
</translate>

<translate> AssetManager offers the following methods to work with style files:</translate>

<syntaxhighlight lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();

// Attach foobar to the document
$wa->useStyle('foobar');

// Disable foobar from being attached
$wa->disableStyle('foobar');

// Register custom item without JSON definition
$wa->registerStyle('bar', 'com_example/bar.css', [], ['data-foo' => 'some attribute'], ['some.dependency']);
// And use it later
$wa->useStyle('bar');

// Register and attach a custom item in one run
$wa->registerAndUseStyle('bar', 'com_example/bar.css', [], ['data-foo' => 'some attribute'], ['some.dependency']);
</syntaxhighlight>

<translate>
=== Add Inline Style === 
</translate>

<translate>
Additionally to style files, WebAssetManager allows you to add an inline style, and maintain their relation to the file asset.
Inline styles may be placed directly before the dependency, after the dependency, or as usual after all styles.</translate>

<translate> Inline asset may have a name as well as other assets (but not required). The name can be used to retrieve the asset item from a registry, or as a dependency to another inline asset. If the name is not specified then a generated name based on a content hash will be used.</translate>

<syntaxhighlight lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();

// Add an inline content as usual, will be rendered in flow after all assets
$wa->addInlineStyle('content of inline1');

// Add an inline content that will be placed after "foobar" asset
$wa->addInlineStyle('content of inline2', ['position' => 'after'], ['data-foo' => 'bar'], ['foobar']);

// Add an inline content that will be placed before "foobar" asset
$wa->addInlineStyle('content of inline3', ['position' => 'before'], [], ['foobar']);

// Named inline asset
$wa->addInlineStyle('content of inline4', ['name' => 'my.inline.asset']);
</syntaxhighlight>

<translate> '''Note''' The ''foobar'' asset should exist in the asset registry, otherwise you will get an unsatisfied dependency exception.</translate>

<translate> The example above will produce:</translate>

<syntaxhighlight lang="html5">
...
<style>content of inline3</style>
<link rel="stylesheet" href="foobar.css" />
<style data-foo="bar">content of inline2</style>
...
...
<style>content of inline1</style>
<style>content of inline4</style>
...
</syntaxhighlight>

<translate> If an inline asset has multiple dependencies, then will be used last one for positioning. Example:</translate>

<syntaxhighlight lang="php">
$wa->addInlineStyle('content of inline1', ['position' => 'before'], [], ['foo', 'bar']);
$wa->addInlineStyle('content of inline2', ['position' => 'after'], [], ['foo', 'bar']);
</syntaxhighlight>
<translate> Will produce:</translate>

<syntaxhighlight lang="html5">
...
<link rel="stylesheet" href="foo.css" />
<style>content of inline1</style>
<link rel="stylesheet" href="bar.css" />
<style>content of inline2</style>
...
</syntaxhighlight>

<translate> '''Note''' Named inline assets may be a dependency to another inline asset, however it is not recommended to use an inline asset as dependency to non-inline asset. This will work, but this behavior may change in the future. Prefer to use ''position'' instead.</translate>

<translate>
== Working with Scripts == 
</translate>

<translate> AssetManager allow you to manage JavaScript files. Script asset items have a type "script".</translate>
<translate> Example JSON definition of item in joomla.asset.json:</translate>
<syntaxhighlight lang="json">
...
{
"name": "foobar",
"type": "script",
"uri": "com_example/foobar.js",
"dependencies": ["core"]
}
...
</syntaxhighlight>

<translate> Example JSON definition of ES6 module script, with fallback to legacy:</translate>

<syntaxhighlight lang="json">
...
{
"name": "foobar-legacy",
"type": "script",
"uri": "com_example/foobar-as5.js",
"attributes": {
"nomodule": true,
"defer": true
},
"dependencies": ["core"]
}
{
"name": "foobar",
"type": "script",
"uri": "com_example/foobar.js",
"attributes": {
"type": "module"
},
"dependencies": [
"core",
"foobar-legacy"
]
}
...
</syntaxhighlight>

<translate>
=== Methods to Work with Scripts === 
</translate>

<translate> AssetManager offers these methods to work with script files:</translate>

<syntaxhighlight lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();

// Attach foobar to the document
$wa->useScript('foobar');

// Disable foobar from being attached
$wa->disableScript('foobar');

// Register custom item without JSON definition
$wa->registerScript('bar', 'com_example/bar.js', [], ['defer' => true], ['core']);
// And use it later
$wa->useScript('bar');

// Register and attach a custom item in one run
$wa->registerAndUseScript('bar','com_example/bar.js', [], ['defer' => true], ['core']);
</syntaxhighlight>

<translate>
=== Add Inline Script === 
</translate>

<translate>
In addition to script files, WebAssetManager allows you to add an inline script, and maintain their relation to the file asset.
Inline script may be placed directly before the dependency, after the dependency, or as usual after all scripts.</translate>

<translate> Inline asset may have a name as well as other assets (but not required). The name can be used to retrieve the asset item form a registry, or as dependency to another inline asset. If a name is not specified, a generated name based on a content hash will be used.</translate>

<syntaxhighlight lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();

// Add an inline content as usual, will be rendered in flow after all assets
$wa->addInlineScript('content of inline1');

// Add an inline content that will be placed after "foobar" asset
$wa->addInlineScript('content of inline2', ['position' => 'after'], ['data-foo' => 'bar'], ['foobar']);

// Add an inline content that will be placed before "foobar" asset
$wa->addInlineScript('content of inline3', ['position' => 'before'], [], ['foobar']);

// Named inline asset
$wa->addInlineScript('content of inline4', ['name' => 'my.inline.asset']);

// Specify script type
$wa->addInlineScript('content of inline5', [], ['type' => 'module']);
</syntaxhighlight>

<translate> '''Note''' The ''foobar'' asset should exist in the asset registry, otherwise you will get an unsatisfied dependency exception.</translate>

<translate> Example above will produce:</translate>

<syntaxhighlight lang="html5">
...
<script>content of inline3</script>
<script src="foobar.js"></script>
<script data-foo="bar">content of inline2</script>
...
...
<script>content of inline1</script>
<script>content of inline4</script>
<script type="module">content of inline5</script>
...
</syntaxhighlight>

<translate> If an inline asset has multiple dependencies, it will be the last one for positioning. Example:</translate>

<syntaxhighlight lang="php">
$wa->addInlineScript('content of inline1', ['position' => 'before'], [], ['foo', 'bar']);
$wa->addInlineScript('content of inline2', ['position' => 'after'], [], ['foo', 'bar']);
</syntaxhighlight>

<translate> Will produce:</translate>

<syntaxhighlight lang="html5">
...
<script src="foo.js"></script>
<script>content of inline1</script>
<script src="bar.js"></script>
<script>content of inline2</script>
...
</syntaxhighlight>

<translate> '''Note''' Named inline assets may be a dependency on another inline asset, however it is not recommended to use an inline asset as dependency to non-inline asset. This will work, but this behavior may changes in future. Prefer to use ''position'' instead.</translate>

<translate>
== Working with a Web Component == 
</translate>

<translate>
Joomla! allows you to use [https://developer.mozilla.org/en-US/docs/Web/Web_Components Web Components] for your needs. In Joomla! web components are not loaded as regular scripts, but loaded via Web Component loader so that they are loaded asynchronously. Therefore, a web component asset item must have a flag ''webcomponent'' set to the boolean ''true''.
In all other aspects, working with web components in AssetManager is the same as working with a ''script'' asset item.</translate>

<translate> Example JSON definitions of some web components in joomla.asset.json (as ES6 module):</translate>

<syntaxhighlight lang="json">
...
{
"name": "webcomponent.foobar",
"type": "style",
"uri": "com_example/foobar-custom-element.css",
},
{
"name": "webcomponent.foobar",
"type": "script",
"uri": "com_example/foobar-custom-element.js",
"attributes": {
"type": "module"
},
}
...
</syntaxhighlight>

<translate> Example with fallback, for browsers that does not support ES6 "module" feature. Note that the legacy script should have "wcpolyfill" dependency, and module script should have dependency from legacy script:</translate>

<syntaxhighlight lang="json">
...
{
"name": "webcomponent.foobar",
"type": "style",
"uri": "com_example/foobar-custom-element.css",
},
{
"name": "webcomponent.foobar-legacy",
"type": "script",
"uri": "com_example/foobar-custom-element-es5.js",
"attributes": {
"nomodule": true,
"defer": true
},
"dependencies": [
"wcpolyfill"
]
},
{
"name": "webcomponent.foobar",
"type": "script",
"uri": "com_example/foobar-custom-element.js",
"attributes": {
"type": "module"
},
"dependencies": [
"webcomponent.foobar-legacy"
]
}
...
</syntaxhighlight>

<translate> Alternatively you can register them in PHP (as an ES6 module):</translate>

<syntaxhighlight lang="php">
$wa->registerStyle('webcomponent.foobar', 'com_example/foobar-custom-element.css')
->registerScript('webcomponent.foobar', 'com_example/foobar-custom-element.js', ['type' => 'module']);
</syntaxhighlight>

<translate> Attach to document:</translate>

<syntaxhighlight lang="php">
$wa->useStyle('webcomponent.foobar')
->useScript('webcomponent.foobar');
</syntaxhighlight>

<translate>

'''Note''' It is preferred to prefix the asset name with ''webcomponent.'' to make it easily to spot, and distinguish it from regular scripts in a layout.</translate>

<translate>
=== Methods to Work with Web Component === 
</translate>

<translate> All methods to work with a web component are the same as methods to work with script asset items.</translate>

<translate>
== Working with a Presets == 
</translate>

<translate>
A ''preset'' is a special kind of asset item that holds a list of items to be enabled, in the same way as direct call of ''useAsset()'' to each of item in the list.
Preset can hold mixed types of assets (script, style, another preset, etc.). The type should be provided after a # symbol and follows after an asset name. Example: foo#style, bar#script.</translate>

<translate> Example JSON definition of item in joomla.asset.json:</translate>

<syntaxhighlight lang="json">
...
{
"name": "foobar",
"type": "preset",
"uri": "",
"dependencies": [
"core#script",
"foobar#style",
"foobar#script",
]
}
...
</syntaxhighlight>

<translate>
=== Methods to Work with Preset === 
</translate>

<translate> AssetManager offers these methods to work with preset items:</translate>

<syntaxhighlight lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();

// Attach all items from foobar preset to the document
$wa->usePreset('foobar');

// Disable all items from foobar preset from being attached
$wa->disablePreset('foobar');

// Register custom item without JSON definition
$wa->registerPreset('bar', '', [], [], ['core#script', 'bar#script']);

// And use it later
$wa->usePreset('bar');

// Register and attach a custom item in one run
$wa->registerAndUsePreset('bar','', [], [], ['core#script', 'bar#script']);
</syntaxhighlight>

<translate>
== Advanced: Custom WebAssetItem Class == 
</translate>

<translate> The default class for all WebAsset items is '''Joomla\CMS\WebAsset\WebAssetItem'''.</translate>

<translate> You are also allowed to use a custom class, which must implement '''Joomla\CMS\WebAsset\WebAssetItemInterface''' or extend '''Joomla\CMS\WebAsset\WebAssetItem'''.</translate>

<translate> A custom class allows you to do advanced actions. For example, including a script file depending on an active language:</translate>

<syntaxhighlight lang="php">
class MyComExampleAssetItem extends WebAssetItem
{
public function getUri($resolvePath = true): string
{
$langTag = Factory::getApplication()->getLanguage()->getTag();
// For script asset use ".js", for style we would use ".css"
$path = 'com_example/bar-' . $langTag . '.js';

if ($resolvePath)
{
// For script asset use "script", for style we would use "stylesheet"
$path = $this->resolvePath($path, 'script');
}

return $path;
}
}
</syntaxhighlight>

<translate> Additionally, implementing ''Joomla\CMS\WebAsset\WebAssetAttachBehaviorInterface'' allows you to add script options (which may depend on the environment) when your asset is enabled and attached to the Document.</translate>

<syntaxhighlight lang="php">
class MyFancyFoobarAssetItem extends WebAssetItem implements WebAssetAttachBehaviorInterface
{
public function onAttachCallback(Document $doc): void
{
$user = Factory::getApplication()->getIdentity();
$doc->addScriptOptions('com_example.fancyfoobar', ['userName' => $user->username]);
}
}
</syntaxhighlight>

<translate> '''Important Note''' An asset item that implements ''WebAssetAttachBehaviorInterface'' should be enabled before a [https://docs.joomla.org/Plugin/Events/System#onBeforeCompileHead onBeforeCompileHead] event, otherwise ''onAttachCallback'' will be ignored.</translate>

<translate>
=== Defining a Custom WebAssetItem Class in ''joomla.asset.json'' === 
</translate>

<translate>
In joomla.asset.json you can define which Class should be used with a specific AssetItem.
For this you can use two properties '''namespace''' and '''class'''. '''namespace''' can be defined at Root level. (Then it will be used as default namespace for all Asset items in joomla.asset.json) or in the Item level. For example:</translate>

<syntaxhighlight lang="json">
{
"$schema": "https://developer.joomla.org/schemas/json-schema/web_assets.json",
"name": "com_example",
"version": "4.0.0",
"namespace": "Joomla\Component\Example\WebAsset",
"assets": [
{
"name": "foo",
"type": "script",
"class": "FooAssetItem",
"uri": "com_example/foo.js"
},
{
"name": "bar",
"type": "script",
"namespace": "MyFooBar\Library\Example\WebAsset",
"class": "BarAssetItem",
"uri": "com_example/bar.js"
}
]
}
</syntaxhighlight>

<translate> Here the asset ''foo'' will be associated with class ''Joomla\Component\Example\WebAsset\FooAssetItem'', and ''bar'' with class ''MyFooBar\Library\Example\WebAsset\BarAssetItem''.</translate>

<translate> '''Note''' If ''namespace'' is not defined, by default ''Joomla\CMS\WebAsset'' will be used. When ''namespace'' is defined but empty, no namespace will be used, only ''class''. Example:</translate>

<syntaxhighlight lang="json">
{
"$schema": "https://developer.joomla.org/schemas/json-schema/web_assets.json",
"name": "com_example",
"assets": [
{
"name": "foo",
"type": "script",
"class": "FooAssetItem",
"uri": "com_example/foo.js"
},
{
"name": "bar",
"type": "script",
"namespace": "",
"class": "BarAssetItem",
"uri": "com_example/bar.js"
}
]
}
</syntaxhighlight>

<translate> Here the asset ''foo'' will be associated with class ''Joomla\CMS\WebAsset\FooAssetItem'', and ''bar'' with class ''BarAssetItem'' (without namespace).</translate>

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

J4.x:Web Assets

2023-04-30T22:34:04Z

Cmb: Markup, spelling changes and some Words2Watch corrections.

<noinclude><languages /></noinclude>
<translate>
== Concept == 
</translate>

<translate> In the Frontend world many assets are related. For example our keepalive script depends on the core.js file for options management. In Joomla there never was an easy way to specify this; you just had to include multiple files. Joomla 4 changes this with the concept of web assets.</translate>

<translate>
== Definition == 
</translate>

<translate> Related assets are defined in a JSON file such as [https://github.com/joomla/joomla-cms/blob/7b72c565b610e02c1b01f8958d622879631fa6a2/build/media_source/system/joomla.asset.json#L14-L21 system/joomla.asset.json#L14-L21]</translate>

<translate> This has a structure of having a schema definition (for validation), name, version, license and then one or more asset definitions. Assets are comprised of a list of JavaScript files and CSS files related to the assets and any dependencies. The dependencies section is just a list of asset names that are required for the asset to function. Example:</translate>

<syntaxhighlight lang="json">
{
"$schema": "https://developer.joomla.org/schemas/json-schema/web_assets.json",
"name": "com_example",
"version": "4.0.0",
"description": "Joomla CMS",
"license": "GPL-2.0+",
"assets": [
{
"name": "bar",
"type": "style",
"uri": "com_example/bar.css"
},
{
"name": "bar",
"type": "script",
"uri": "com_example/bar.js"
},
{
"name": "beer",
"type": "style",
"uri": "com_example/beer.css",
"dependencies": [
"bar"
],
},
{
"name": "beer",
"type": "script",
"dependencies": [
"core",
"bar"
],
"uri": "com_example/beer.js",
"attributes": {
"defer": true,
"data-foo": "bar"
}
}
]
}
</syntaxhighlight>

<translate> The <syntaxhighlight lang="json" inline>$schema</syntaxhighlight> attribute is a schema definition file that allows you to validate your file using JSON Schema. Read [https://json-schema.org/understanding-json-schema/index.html the official website] for more information on JSON schema validation works.</translate>

<translate> '''Note:''' Having joomla.asset.json for your extension or template are recommend but not required to WebAsset to work (see next section).</translate>

<translate> '''Note''' It is not recommended to add an inline asset to a JSON file, prefer to use a file.</translate>

<translate>
== Explaining Asset Stages == 
</translate>

<translate> Each asset has two stages: registered and used.</translate>

<translate>

'''Registered''' is where an asset is loaded into '''WebAssetRegistry'''. That means '''WebAssetManager''' knows about the existence of these assets, but will not attach them to a document while rendering.
All assets loaded from joomla.asset.json is at '''registered''' stage.</translate>

<translate> '''Used''' is where an asset is enabled via "$wa->useAsset()" (->useScript(), ->useStyle(), ->registerAndUseX() etc). That means '''WebAssetManager''' will attach these assets and their dependencies to a document while rendering.</translate>

<translate> An asset cannot be used if it was not registered before, this will cause an unknown asset exception.</translate>

<translate>
== Register an Asset == 
</translate>

<translate> All known assets loaded and then stored in '''WebAssetRegistry''' (to enable/disable an asset item you have to use '''WebAssetManager''', see next section).</translate>

<translate> Joomla! will look for next assets definition automatically at runtime (in following order):</translate>
<pre>
media/vendor/joomla.asset.json (on first access to WebAssetRegistry)
media/system/joomla.asset.json
media/legacy/joomla.asset.json
media/{com_active_component}/joomla.asset.json (on dispatch the application)
templates/{active_template}/joomla.asset.json
</pre>

<translate> And load them to registry of known assets.</translate>

<translate> '''Note:''' Each following assets definition will override asset items from previous assets definition, by item name.</translate>

<translate> You can register your own assets definition via '''WebAssetRegistry''':</translate>

<syntaxhighlight lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();
$wr = $wa->getRegistry();
$wr->addRegistryFile('relative/path/to/your/joomla.asset.json');
</syntaxhighlight>

<translate> To add a custom asset item at runtime:</translate>
<syntaxhighlight lang="php">
$wr->add('script', new Joomla\CMS\WebAsset\WebAssetItem('foobar', 'com_foobar/file.js', ['type' => 'script']));
</syntaxhighlight>

<translate> Or more simply, using '''WebAssetManager''':</translate>
<syntaxhighlight lang="php">
$wa->registerScript('foobar', 'com_foobar/file.js');
</syntaxhighlight>

<translate> The new asset item '''foobar''' will be added to the registry of know assets, but will not be attached to a document until your code (a layout, template etc) will request it.</translate>

<translate> To check whether an asset exists:</translate>
<syntaxhighlight lang="php">
if ($wa->assetExists('script', 'foobar'))
{
var_dump('Script "foobar" exists!');
}
</syntaxhighlight>

<translate>
== Enabling an Asset == 
</translate>
<translate> All asset management in the current Document handled by '''WebAssetManager''', which is accessible with '''$doc->getWebAssetManager();'''</translate>
<translate> By using AssetManager you can enable or disable needed asset easily in Joomla! through a standard methods.</translate>

<translate> To enable an asset in the page use the useAsset function, for example:</translate>

<syntaxhighlight lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();
$wa->useScript('keepalive');

// Or multiple
$wa->useScript('keepalive')
->useScript('fields.validate')
->useStyle('foobar')
->useScript('foobar');

// Add new asset item with dependency and use it
$wa->registerAndUseScript('bar', 'com_foobar/bar.js', [], [], ['core', 'foobar']);
</syntaxhighlight>

<translate> '''WebAssetManager''' will look to '''WebAssetRegistry''' whether the requested asset exists, and will enable it for current Document instance. Otherwise it will throw an UnknownAssetException.</translate>

<translate> To disable an asset in the page use the disableAsset function. The example below will disable the jquery-noconflict asset from being loaded.</translate>

<syntaxhighlight lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();
$wa->disableScript('jquery-noconflict');
</syntaxhighlight>

<translate> '''Note''' If there are any dependencies to the disabled asset, then this asset will be re-enabled automatically, no matter what.</translate>

<translate> To check whether asset enabled, and the asset state:</translate>

<syntaxhighlight lang="php">
// Checking whether an asset are active (enabled manually or automatically as dependency)
if ($wa->isAssetActive('script', 'foobar'))
{
var_dump('Script "foobar" is active!');
}

// Checking state
switch($wa->getAssetState('script', 'foobar')){
case Joomla\CMS\WebAsset\WebAssetManager::ASSET_STATE_ACTIVE:
var_dump('Active! Was enabled manually');
break;
case Joomla\CMS\WebAsset\WebAssetManager::ASSET_STATE_DEPENDENCY:
var_dump('Active! Was enabled automatically while resolving dependencies');
break;
default:
var_dump('not active!');
}
</syntaxhighlight>

<translate>
== Overriding an Asset == 
</translate>

<translate>
Overriding may be useful when you need to redefine the URI of asset item or its dependencies.
As already was noted, each of the following assets definition from joomla.asset.json will override asset items from previous assets definitions, by item name.</translate>
<translate>
That means if you provide joomla.asset.json which contain already loaded asset items, they will be replaced with your items.
Another way to override in the code is to register an item with the same name.
Example, we have "foobar" script, that load com_example/foobar.js library, and we want to use CDN for this exact library:</translate>

<translate> How it defined in the system initially:</translate>

<syntaxhighlight lang="json">
...
{
"name": "foobar",
"type": "script",
"uri": "com_example/foobar.js",
"dependencies": ["core"]
}
...
</syntaxhighlight>

<translate> To override the URI we define the asset item with "foobar" name in our joomla.asset.json:</translate>

<syntaxhighlight lang="json">
...
{
"name": "foobar",
"type": "script",
"uri": "http://foobar.cdn.blabla/foobar.js",
"dependencies": ["core"]
}
...
</syntaxhighlight>

<translate> Or, register new asset item with AssetManager:</translate>

<syntaxhighlight lang="php">
$wa->registerScript('foobar', 'http://fobar.cdn.blabla/foobar.js', [], [], ['core']);
</syntaxhighlight>

<translate>
== Working with Styles == 
</translate>

<translate> AssetManager allow to manage Stylesheet files. Stylesheet asset item have a type "style".</translate>

<translate> Example JSON definition of item in joomla.asset.json:</translate>

<syntaxhighlight lang="json">
...
{
"name": "foobar",
"type": "style",
"uri": "com_example/foobar.css"
}
...
</syntaxhighlight>

<translate>
=== Methods to Work with Styles === 
</translate>

<translate> AssetManager offers the following methods to work with style files:</translate>

<syntaxhighlight lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();

// Attach foobar to the document
$wa->useStyle('foobar');

// Disable foobar from being attached
$wa->disableStyle('foobar');

// Register custom item without JSON definition
$wa->registerStyle('bar', 'com_example/bar.css', [], ['data-foo' => 'some attribute'], ['some.dependency']);
// And use it later
$wa->useStyle('bar');

// Register and attach a custom item in one run
$wa->registerAndUseStyle('bar', 'com_example/bar.css', [], ['data-foo' => 'some attribute'], ['some.dependency']);
</syntaxhighlight>

<translate>
=== Add Inline Style === 
</translate>

<translate>
Additionally to style files, WebAssetManager allows you to add an inline style, and maintain their relation to the file asset.
Inline styles may be placed directly before the dependency, after the dependency, or as usual after all styles.</translate>

<translate> Inline asset may have a name as well as other assets (but not required), the name can be used to retrieve the asset item from a registry, or as a dependency to another inline asset. If the name is not specified then a generated name based on a content hash will be used.</translate>

<syntaxhighlight lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();

// Add an inline content as usual, will be rendered in flow after all assets
$wa->addInlineStyle('content of inline1');

// Add an inline content that will be placed after "foobar" asset
$wa->addInlineStyle('content of inline2', ['position' => 'after'], ['data-foo' => 'bar'], ['foobar']);

// Add an inline content that will be placed before "foobar" asset
$wa->addInlineStyle('content of inline3', ['position' => 'before'], [], ['foobar']);

// Named inline asset
$wa->addInlineStyle('content of inline4', ['name' => 'my.inline.asset']);
</syntaxhighlight>

<translate> '''Note:''' "foobar" asset should exist in the asset registry, otherwise you will get an unsatisfied dependency exception.</translate>

<translate> Example above will produce:</translate>

<syntaxhighlight lang="html5">
...
<style>content of inline3</style>
<link rel="stylesheet" href="foobar.css" />
<style data-foo="bar">content of inline2</style>
...
...
<style>content of inline1</style>
<style>content of inline4</style>
...
</syntaxhighlight>

<translate> If inline asset has multiple dependencies, then will be used last one for positioning. Example:</translate>

<syntaxhighlight lang="php">
$wa->addInlineStyle('content of inline1', ['position' => 'before'], [], ['foo', 'bar']);
$wa->addInlineStyle('content of inline2', ['position' => 'after'], [], ['foo', 'bar']);
</syntaxhighlight>
<translate> Will produce:</translate>

<syntaxhighlight lang="html5">
...
<link rel="stylesheet" href="foo.css" />
<style>content of inline1</style>
<link rel="stylesheet" href="bar.css" />
<style>content of inline2</style>
...
</syntaxhighlight>

<translate> '''Note:''' Named inline assets may be a dependency to another inline asset, however it is not recommended to use an inline asset as dependency to non-inline asset. This will work, but this behavior may change in the future. Prefer to use "position" instead.</translate>

<translate>
== Working with Scripts == 
</translate>

<translate> AssetManager allow to manage Script files. Script asset item have a type "script".</translate>
<translate> Example JSON definition of item in joomla.asset.json:</translate>
<syntaxhighlight lang="json">
...
{
"name": "foobar",
"type": "script",
"uri": "com_example/foobar.js",
"dependencies": ["core"]
}
...
</syntaxhighlight>

<translate> Example JSON definition of ES6 module script, with fallback to legacy:</translate>

<syntaxhighlight lang="json">
...
{
"name": "foobar-legacy",
"type": "script",
"uri": "com_example/foobar-as5.js",
"attributes": {
"nomodule": true,
"defer": true
},
"dependencies": ["core"]
}
{
"name": "foobar",
"type": "script",
"uri": "com_example/foobar.js",
"attributes": {
"type": "module"
},
"dependencies": [
"core",
"foobar-legacy"
]
}
...
</syntaxhighlight>

<translate>
=== Methods to Work with Scripts === 
</translate>

<translate> AssetManager offer next methods to work with script files:</translate>

<syntaxhighlight lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();

// Attach foobar to the document
$wa->useScript('foobar');

// Disable foobar from being attached
$wa->disableScript('foobar');

// Register custom item without JSON definition
$wa->registerScript('bar', 'com_example/bar.js', [], ['defer' => true], ['core']);
// And use it later
$wa->useScript('bar');

// Register and attach a custom item in one run
$wa->registerAndUseScript('bar','com_example/bar.js', [], ['defer' => true], ['core']);
</syntaxhighlight>

<translate>
=== Add Inline Script === 
</translate>

<translate>
Additionally to script files WebAssetManager allow to add an inline script, and maintain their relation to the file asset.
Inline script may be placed directly before the dependency, after the dependency, or as usual after all scripts.</translate>

<translate> Inline asset may have a name as well as other assets (but not required), the name can be used to retrieve the asset item form a registry, or as dependency to another inline asset. If name not specified then will be used generated name based on a content hash.</translate>

<syntaxhighlight lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();

// Add an inline content as usual, will be rendered in flow after all assets
$wa->addInlineScript('content of inline1');

// Add an inline content that will be placed after "foobar" asset
$wa->addInlineScript('content of inline2', ['position' => 'after'], ['data-foo' => 'bar'], ['foobar']);

// Add an inline content that will be placed before "foobar" asset
$wa->addInlineScript('content of inline3', ['position' => 'before'], [], ['foobar']);

// Named inline asset
$wa->addInlineScript('content of inline4', ['name' => 'my.inline.asset']);

// Specify script type
$wa->addInlineScript('content of inline5', [], ['type' => 'module']);
</syntaxhighlight>

<translate> '''Note:''' "foobar" asset should exist in the asset registry, otherwise you will get an unsatisfied dependency exception.</translate>

<translate> Example above will produce:</translate>

<syntaxhighlight lang="html5">
...
<script>content of inline3</script>
<script src="foobar.js"></script>
<script data-foo="bar">content of inline2</script>
...
...
<script>content of inline1</script>
<script>content of inline4</script>
<script type="module">content of inline5</script>
...
</syntaxhighlight>

<translate> If inline asset have a multiple dependencies, then will be used last one for positioning. Example:</translate>

<syntaxhighlight lang="php">
$wa->addInlineScript('content of inline1', ['position' => 'before'], [], ['foo', 'bar']);
$wa->addInlineScript('content of inline2', ['position' => 'after'], [], ['foo', 'bar']);
</syntaxhighlight>

<translate> Will produce:</translate>

<syntaxhighlight lang="html5">
...
<script src="foo.js"></script>
<script>content of inline1</script>
<script src="bar.js"></script>
<script>content of inline2</script>
...
</syntaxhighlight>

<translate> '''Note:''' Named inline asset may be as dependency to another inline asset, however it is not recommended to use an inline asset as dependency to non-inline asset. This will work, but this behavior may changes in future. Prefer to use "position" instead.</translate>

<translate>
== Working with a Web Component == 
</translate>

<translate>
Joomla! allows you to use [https://developer.mozilla.org/en-US/docs/Web/Web_Components Web Components] for your needs. In Joomla! web components are not loaded as regular script, but loaded via Web Component loader so that they are loaded asynchronously. Therefore, a web component asset item must have a flag "webcomponent" set to the boolean "true".
In all other aspects, working with web components in AssetManager is the same as working with a "script" asset item.</translate>

<translate> Example JSON definition of some web components in joomla.asset.json (as ES6 module):</translate>

<syntaxhighlight lang="json">
...
{
"name": "webcomponent.foobar",
"type": "style",
"uri": "com_example/foobar-custom-element.css",
},
{
"name": "webcomponent.foobar",
"type": "script",
"uri": "com_example/foobar-custom-element.js",
"attributes": {
"type": "module"
},
}
...
</syntaxhighlight>

<translate> Example with fallback, for browsers that does not support ES6 "module" feature. Note that the legacy script should have "wcpolyfill" dependency, and module script should have dependency from legacy script:</translate>

<syntaxhighlight lang="json">
...
{
"name": "webcomponent.foobar",
"type": "style",
"uri": "com_example/foobar-custom-element.css",
},
{
"name": "webcomponent.foobar-legacy",
"type": "script",
"uri": "com_example/foobar-custom-element-es5.js",
"attributes": {
"nomodule": true,
"defer": true
},
"dependencies": [
"wcpolyfill"
]
},
{
"name": "webcomponent.foobar",
"type": "script",
"uri": "com_example/foobar-custom-element.js",
"attributes": {
"type": "module"
},
"dependencies": [
"webcomponent.foobar-legacy"
]
}
...
</syntaxhighlight>

<translate> Alternatively you can register them in PHP (as ES6 module):</translate>

<syntaxhighlight lang="php">
$wa->registerStyle('webcomponent.foobar', 'com_example/foobar-custom-element.css')
->registerScript('webcomponent.foobar', 'com_example/foobar-custom-element.js', ['type' => 'module']);
</syntaxhighlight>

<translate> Attach to document:</translate>

<syntaxhighlight lang="php">
$wa->useStyle('webcomponent.foobar')
->useScript('webcomponent.foobar');
</syntaxhighlight>

<translate>

'''Note:''' It is preferred to prefix the asset name with "webcomponent." to make it easily to spot, and distinct it from regular scripts in a layout.</translate>

<translate>
=== Methods to Work with Web Component === 
</translate>

<translate> All methods to work with a web component are the same as methods to work with script asset item.</translate>

<translate>
== Working with a Presets == 
</translate>

<translate>
"Preset" is a special kind of asset item that hold a list of items that has to be enabled, in same way as direct call of useAsset() to each of item in the list.
Preset can hold mixed types of assets (script, style, another preset, etc), the type should be provided after # symbol and follows after an asset name, example: foo#style, bar#script.</translate>

<translate> Example JSON definition of item in joomla.asset.json:</translate>

<syntaxhighlight lang="json">
...
{
"name": "foobar",
"type": "preset",
"uri": "",
"dependencies": [
"core#script",
"foobar#style",
"foobar#script",
]
}
...
</syntaxhighlight>

<translate>
=== Methods to Work with Preset === 
</translate>

<translate> AssetManager offer next methods to work with preset items:</translate>

<syntaxhighlight lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();

// Attach all items from foobar preset to the document
$wa->usePreset('foobar');

// Disable all items from foobar preset from being attached
$wa->disablePreset('foobar');

// Register custom item without JSON definition
$wa->registerPreset('bar', '', [], [], ['core#script', 'bar#script']);

// And use it later
$wa->usePreset('bar');

// Register and attach a custom item in one run
$wa->registerAndUsePreset('bar','', [], [], ['core#script', 'bar#script']);
</syntaxhighlight>

<translate>
== Advanced: Custom WebAssetItem Class == 
</translate>

<translate> The default class for all WebAsset items is '''Joomla\CMS\WebAsset\WebAssetItem'''.</translate>

<translate> You are also allowed to use a custom class, which must implement '''Joomla\CMS\WebAsset\WebAssetItemInterface''' or extend '''Joomla\CMS\WebAsset\WebAssetItem'''.</translate>

<translate> A custom class can allow you to do advanced actions, for example, including a script file depending on an active language:</translate>

<syntaxhighlight lang="php">
class MyComExampleAssetItem extends WebAssetItem
{
public function getUri($resolvePath = true): string
{
$langTag = Factory::getApplication()->getLanguage()->getTag();
// For script asset use ".js", for style we would use ".css"
$path = 'com_example/bar-' . $langTag . '.js';

if ($resolvePath)
{
// For script asset use "script", for style we would use "stylesheet"
$path = $this->resolvePath($path, 'script');
}

return $path;
}
}
</syntaxhighlight>

<translate> Additionally, implementing '''Joomla\CMS\WebAsset\WebAssetAttachBehaviorInterface''' allows you to add a script options (which may depend on the environment) when your asset is enabled and attached to the Document.</translate>

<syntaxhighlight lang="php">
class MyFancyFoobarAssetItem extends WebAssetItem implements WebAssetAttachBehaviorInterface
{
public function onAttachCallback(Document $doc): void
{
$user = Factory::getApplication()->getIdentity();
$doc->addScriptOptions('com_example.fancyfoobar', ['userName' => $user->username]);
}
}
</syntaxhighlight>

<translate> '''Important note:''' An asset item that implements '''WebAssetAttachBehaviorInterface''' should be enabled before [https://docs.joomla.org/Plugin/Events/System#onBeforeCompileHead onBeforeCompileHead] event, otherwise 'onAttachCallback' will be ignored.</translate>

<translate>
=== Defining a Custom WebAssetItem Class in ''joomla.asset.json'' === 
</translate>

<translate>
In joomla.asset.json you can define which Class should be used with specific AssetItem.
For this you can use 2 properties '''namespace''' and '''class'''. '''namespace''' can be defined at Root level (then it will be used as default namespace for all Asset items in joomla.asset.json) or in the Item level. For example:</translate>

<syntaxhighlight lang="json">
{
"$schema": "https://developer.joomla.org/schemas/json-schema/web_assets.json",
"name": "com_example",
"version": "4.0.0",
"namespace": "Joomla\Component\Example\WebAsset",
"assets": [
{
"name": "foo",
"type": "script",
"class": "FooAssetItem",
"uri": "com_example/foo.js"
},
{
"name": "bar",
"type": "script",
"namespace": "MyFooBar\Library\Example\WebAsset",
"class": "BarAssetItem",
"uri": "com_example/bar.js"
}
]
}
</syntaxhighlight>

<translate> Here the asset '''foo''' will be associated with class '''Joomla\Component\Example\WebAsset\FooAssetItem''', and '''bar''' with class '''MyFooBar\Library\Example\WebAsset\BarAssetItem'''.</translate>

<translate> '''Note:''' If '''namespace''' are not defined then by default will be used '''Joomla\CMS\WebAsset'''. When '''namespace''' is defined but empty, then no namespace will be used, only '''class'''. Example:</translate>

<syntaxhighlight lang="json">
{
"$schema": "https://developer.joomla.org/schemas/json-schema/web_assets.json",
"name": "com_example",
"assets": [
{
"name": "foo",
"type": "script",
"class": "FooAssetItem",
"uri": "com_example/foo.js"
},
{
"name": "bar",
"type": "script",
"namespace": "",
"class": "BarAssetItem",
"uri": "com_example/bar.js"
}
]
}
</syntaxhighlight>

<translate> Here the asset '''foo''' will be associated with class '''Joomla\CMS\WebAsset\FooAssetItem''', and '''bar''' with class '''BarAssetItem''' (without namespace).</translate>

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

J4.x:Creating a Simple Module

2023-04-30T17:28:16Z

Cmb: Several markup and capitalization changes. Some Words2Watch changes.

<noinclude><languages /></noinclude>
{{Joomla version|version=4.x|comment=><translate> Tutorial</translate>}}
{{-}}
{{Top portal heading|color=white-bkgd|icon=file-code-o|icon-color=#5091cd|size=5x|text-color=#333|title=<translate> Creating a Simple Module for Joomla 4.x</translate>}}
{{-}}

<translate> This is a tutorial on how to Create a simple module for Joomla Version 4x.</translate>
<translate>
== Introduction == 
</translate>
<translate> Joomlaǃ 4 provides five types of extensionsː</translate>
* '''[[S:MyLanguage/Component|<translate> Components</translate>]]'''<br /><translate> A component is the main part of the site. A component handles data manipulation as well as input and storage into the database. A component on most sites is the primary focus of the page.</translate>
* '''[[S:MyLanguage/Module|<translate> Modules</translate>]]''' <br /><translate> A module is an add-on to the site that extends the functionality. A module usually occupies a secondary portion of the web page and is not considered the primary focus of a page. It can be displayed on different positions and you can choose on which active menu items it should be displayed. Modules are lightweight and flexible extensions. They are used for small bits of the page that are generally less complex and are able to be seen across different components.</translate>
* '''[[S:MyLanguage/Plugin|<translate> Plugins</translate>]]'''<br /><translate> A Plugin manipulates output that is already generated by the system. It typically does not run as separate part of the site. It takes data from other sources (i.e. the content) and manipulates this data before displaying. A plugin typically work behind the scenes.</translate>
* '''[[S:MyLanguage/Languages|<translate> Languages</translate>]]'''<br /><translate> Probably the most basic extensions are languages. In essence the language package files consist of key/value pairs, which provide the translation of static text strings, assigned within the Joomla! source code.</translate>
* '''[[S:MyLanguage/Templates|<translate> Templates</translate>]]'''<br /><translate> A template is basically the design of your Joomla! powered website.</translate>

<translate> Joomla! 4 is constructed using five different applications:</translate>
<translate>
* Installation (used for installing Joomla and have to delete after installation)
* Administrator (Backend - used for managing content)
* Public or site (Frontend - used for displaying content)
* CLI (used for accessing Joomla on the command line and for cron jobs)
* API (web services - used for creating APIs for machine accessible content)</translate>
<translate>

The installation application is used once. The administrator and public are used through the concept of ''components'' with ''modules''. Each module has a single entry point located in the ''modules'' and accordingly ''administrator/modules'' directory. This entry point is called <tt>''mod_modulename/mod_modulename.php''</tt> (the ''mod_'' prefix is a historical trace). The entry point for the login module is for example ''/mod_login/mod_login.php''.</translate>

<translate>
=== Requirements === 
</translate>
<translate> You need Joomla! 4.x installation available to use for this tutorial ([https://github.com/joomla/joomla-cms/releases Download latest release here])</translate>

<translate> You can download Joomla! 4 at [https://github.com/joomla/joomla-cms/releases GitHub], on the [https://developer.joomla.org/nightly-builds.html Developer website] or you can create a free website at https://launch.joomla.org.</translate>

<translate>
== Creating a Simple Module/Developing a Basic Module == 
</translate>
<translate> You can see many examples of modules in the standard Joomla! install. For example:</translate>
<translate>
* Menus
* Latest News
* Login form
* and many more.</translate>

<translate> This tutorial will explain how to create a simple module. Through this tutorial you will learn the basic file structure of a Joomlaǃ 4 module. This basic structure can then be expanded to produce more elaborate modules.</translate>

<translate>
=== File Structure === 
</translate>
<translate> There are a few basic files that are used in the standard pattern of module development:</translate>
<translate> * <tt>mod_foo.php</tt> - This file is the main entry point for the module. It will perform any necessary initialization routines, call helper routines to collect any necessary data, and include the template which will display the module output.</translate>
<translate> * <tt>mod_foo.xml</tt> - This file contains information about the module. It defines the files that need to be installed by the Joomla! installer and specifies configuration parameters for the module.</translate>
<translate> * <tt>tmpl/default.php</tt> - This is the module template. This file will take the data collected by mod_foo.php and generate the HTML to be displayed on the page.</translate>
<translate> * <tt>language/en-GB/mod_foo.ini</tt> and <tt>language/en-GB/mod_foo.sys.ini</tt>- This are the files that provide the text in United Kingdom English.</translate>

<translate>
=== Creating mod_foo.php === 
</translate>
<translate> The <tt>mod_foo.php</tt> file will perform following tasks:</translate>
<translate> * Import the class <tt>ModuleHelper</tt> to the current scope. We need it later for displaying the output.</translate>
<translate> * Include the template to display the output.</translate>

<translate> The helper class is imported to our current scope at the begin of the file.</translate>

<syntaxhighlight lang="php">use Joomla\CMS\Helper\ModuleHelper;</syntaxhighlight>

<translate> Last we include the template to display the output via</translate>

<syntaxhighlight lang="php">require ModuleHelper::getLayoutPath('mod_foo', $params->get('layout', 'default'));</syntaxhighlight>

<translate>
==== Completed mod_foo.php File ==== 
</translate>
<translate> The complete <tt>mod_foo.php</tt> file is as follows:</translate>

<syntaxhighlight lang="php">
<?php
/**
* @package [PACKAGE_NAME]
*
* @author [AUTHOR] <[AUTHOR_EMAIL]>
* @copyright [COPYRIGHT]
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link [AUTHOR_URL]
*/

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

use Joomla\CMS\Helper\ModuleHelper;

require ModuleHelper::getLayoutPath('mod_foo', $params->get('layout', 'default'));
</syntaxhighlight>

<translate> ''Side note''ː In Joomla 3x you usually used a line like <tt>$moduleclass_sfx = htmlspecialchars($params->get('moduleclass_sfx'));</tt>. You don't need this anymore. See this PRː https://github.com/joomla/joomla-cms/pull/17447.</translate>

<translate> The one line that we haven’t explained so far is the first line <tt>defined('_JEXEC') or die;</tt>. This line checks to make sure that this file is being included from the Joomla application. This is necessary to prevent variable injection and other potential security concerns.</translate>

<translate>
=== Creating tmpl/default.php === 
</translate>
<translate> The <tt>default.php</tt> file is the template which displays the module output.</translate>

<translate>
==== Completed tmpl/default.php file ==== 
</translate>
<translate> The code for the tmpl/default.php file is as follows:</translate>

<syntaxhighlight lang="php">
<?php
/**
* @package [PACKAGE_NAME]
*
* @author [AUTHOR] <[AUTHOR_EMAIL]>
* @copyright [COPYRIGHT]
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link [AUTHOR_URL]
*/

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

echo '[PROJECT_NAME]';
</syntaxhighlight>

<translate> An important point to note is that the template file has the same scope as the <tt>mod_foo.php</tt> file. It means that a variable can be defined in the <tt>mod_foo.php</tt> file and then used in the template file without any extra declarations or function calls.</translate>

<translate>
=== Creating mod_foo.xml === 
</translate>
<translate> The <tt>mod_foo.xml</tt> file is the installation file. Most entries are self-explanatory.</translate>

<translate>
==== Completed mod_foo.xml file ==== 
</translate>
<translate> The code for the <tt>mod_foo.xml</tt> file is as follows:</translate>

<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="4.0" client="site" method="upgrade">
<name>MOD_FOO</name>
<creationDate>[DATE]</creationDate>
<author>[AUTHOR]</author>
<authorEmail>[AUTHOR_EMAIL]</authorEmail>
<authorUrl>[AUTHOR_URL]</authorUrl>
<copyright>[COPYRIGHT]</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<version>1.0</version>
<description>MOD_FOO_XML_DESCRIPTION</description>
<files>
<filename module="mod_foo">mod_foo.php</filename>
<folder>tmpl</folder>
<folder>language</folder>
<filename>mod_foo.xml</filename>
</files>
</extension>
</syntaxhighlight>

<translate>
=== Creating the Language Files === 
</translate>
<translate> The files <tt>language/en-GB/mod_foo.ini</tt> and <tt>language/en-GB/mod_foo.sys.ini</tt> are used to translate text in the Frontend and in the Backend. Note that the language file structure has been updated in Joomla 4, and language prefixes on the individual files in a language folder are no longer required.</translate>

<translate> The code for <tt>language/en-GB/mod_foo.sys.ini</tt> is as follows:</translate>

<syntaxhighlight lang="xml">
MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"
</syntaxhighlight>

<translate> The code for <tt>language/en-GB/mod_foo.ini</tt> is as follows:</translate>

<syntaxhighlight lang="xml">
MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"
</syntaxhighlight>

<translate> The <tt>.sys.ini</tt> file is used to translate the description of the extension upon installation, where as the <tt>.ini</tt> file is used to translate the remaining strings and the description when viewing your extension.</translate>

<translate> More information about language files can be found [[S:MyLanguage/Specification_of_language_files|here]].</translate>

<translate>
== Test Your Module == 
</translate>
<translate> Now you can zip all files and install them via the Joomla Extension Manager.<br /></translate>
<translate> After that you can choose your module in the module manager, when you create a new site module.</translate>
{{-}}
[[File:moduletutorial1-<translate> en</translate>.png|700px|center]]
{{-}}
[[File:moduletutorial2-<translate> en</translate>.png|700px|center]]

<translate> In the Frontend, you will see your module like displayed in the next image.</translate>
{{-}}
[[File:moduletutorial3-<translate> en</translate>.png|700px|center]]

<translate>
== Conclusion == 
</translate>
<translate> Module development for Joomla is a fairly simple, straightforward process. Using the techniques described in this tutorial, an endless variety of modules can be developed with little hassle.</translate>

<translate> You can find boilerplates hereː</translate>
* https://github.com/joomla-extensions/boilerplate/tree/master/module
<translate> The sample files for this Tutorial can be found hereː</translate>
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

<translate>
== Add a Helper Class Using Namespaces == 
</translate>

<translate>
=== Requirements === 
</translate>
<translate> You need Joomla! 4.x for this tutorial.</translate>

<translate>
== Namespaces == 
</translate>
<translate> With PHP 5.3, the namespaces came into their own. In other programming languages for a long time in use, these small structures now also help us with the clarity of our code.</translate>

<translate> Namespaces are separate areas in which certain logical things (in our case, classes, interfaces, functions, and constants) can live. These areas provide encapsulation of the code and prevent name conflicts.</translate>

<translate> Let's take a look how to use them in Joomla 4. We use the helper file for this.</translate>

<translate>
=== File Structure === 
</translate>
<translate> We will create/change the following files:</translate>
<translate>
* <code>Helper/FooHelper.php</code> - This is the file we use here as an example. We have to create it.
* <code>mod_foo.php</code> - In this file, we will mainly load the namespace.
* <code>tmpl/default.php</code> - In this file, we will demonstrate how the data of a helper can be displayed.
* <code>mod_foo.xml</code> - We create a new directory with a new file. This must be installed during the installation. For this we have to specify them in this file.</translate>

<translate>
=== Creating Helper/FooHelper.php === 
</translate>
<translate> Our new helper class should belong to a namespace. We achieve this with the following code. It is important, that this line is at the beginning of the file.</translate>

<syntaxhighlight lang="php">namespace Joomla\Module\Foo\Site\Helper;</syntaxhighlight>
<translate> Then we create a simple class with a simple method. Of course you can do a lot more here. Take a look at the Joomla core methods. Here are many examples. They show you first-hand what options you have.</translate>

<translate>
==== Completed Helper/FooHelper.php ==== 
</translate>
<translate> The complete <tt>FooHelper.php</tt> file is as follows:</translate>

<syntaxhighlight lang="php">
<?php
/**
* @package Joomla.Site
* @subpackage mod_foo
*
* @copyright Copyright (C) 2005 - 2019 Open Source Matters, Inc. All rights reserved.
* @license GNU General Public License version 2 or later; see LICENSE.txt
*/

namespace Joomla\Module\Foo\Site\Helper;

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

/**
* Helper for mod_foo
*
* @since 4.0
*/
class FooHelper
{
/**
* Retrieve foo test
*
* @param Registry $params The module parameters
* @param CMSApplication $app The application
*
* @return array
*/
public static function getText()
{
return 'FooHelpertest';
}
}
</syntaxhighlight>

<translate>
=== Editing mod_foo.php === 
</translate>
<translate> Our new helper class is imported to our current scope at the beginning of the file.</translate>

<syntaxhighlight lang="php">use Joomla\Module\Foo\Site\Helper\FooHelper;</syntaxhighlight>

<translate> Last use the helper file for testing if it is loaded correctlyː</translate>

<syntaxhighlight lang="php">$test = FooHelper::getText($params, $app);</syntaxhighlight>

<translate>
==== Completed mod_foo.php file ==== 
</translate>
<translate> The complete <tt>mod_foo.php</tt> file is as follows:</translate>

<syntaxhighlight lang="php">
<?php
/**
* @package [PACKAGE_NAME]
*
* @author [AUTHOR] <[AUTHOR_EMAIL]>
* @copyright [COPYRIGHT]
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link [AUTHOR_URL]
*/

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

use Joomla\CMS\Helper\ModuleHelper;
use Joomla\Module\Foo\Site\Helper\FooHelper;

$test = FooHelper::getText();

require ModuleHelper::getLayoutPath('mod_foo', $params->get('layout', 'default'));
</syntaxhighlight>

<translate>
=== Editing tmpl/default.php === 
</translate>
<translate> In this file you make only a small change to demonstrate in the Frontend that your helper file is working properly. You only add the value of the variable at the end of the current output.</translate>

<syntaxhighlight lang="php">echo '[PROJECT_NAME]' . $test;</syntaxhighlight>

<translate>
==== Completed tmpl/default.php ==== 
</translate>
<translate> The complete <tt>tmpl/default.php</tt> file is as follows:</translate>

<syntaxhighlight lang="php">
<?php
/**
* @package [PACKAGE_NAME]
*
* @author [AUTHOR] <[AUTHOR_EMAIL]>
* @copyright [COPYRIGHT]
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link [AUTHOR_URL]
*/

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

echo '[PROJECT_NAME]' . $test;
</syntaxhighlight>

<translate>
=== Editing mod_foo.xml === 
</translate>
<translate> First you have to add a line, so that the namespace is set automatically in Joomla. After this change, you have to re-install your module. A simple change in an already installed module is not enough. If you are doing local development you can also delete the files libraries/autoload_psr4.php and it will automatically be re-created. After inserting and installing, the namespace is known by the loader <tt>JPATH_LIBRARIES . '/autoload_psr4.php'</tt>.</translate>

<syntaxhighlight lang="xml"><namespace>Joomla\Module\Foo</namespace></syntaxhighlight>

<translate> Joomla! should copy your helper file when installing the module. So Joomla! needs to know your helper file. For this, you need to add the following line to your XML file.</translate>

<syntaxhighlight lang="xml"><folder>Helper</folder></syntaxhighlight>

<translate>
==== Completed mod_foo.xml ==== 
</translate>
<translate> The complete <tt>mod_foo.xml</tt> file is as follows:</translate>

<syntaxhighlight lang="xml">

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="4.0" client="site" method="upgrade">
<name>MOD_FOO</name>
<creationDate>[DATE]</creationDate>
<author>[AUTHOR]</author>
<authorEmail>[AUTHOR_EMAIL]</authorEmail>
<authorUrl>[AUTHOR_URL]</authorUrl>
<copyright>[COPYRIGHT]</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<version>1.0</version>
<description>MOD_FOO_XML_DESCRIPTION</description>
<namespace>Joomla\Module\Foo</namespace>
<files>
<filename module="mod_foo">mod_foo.php</filename>
<folder>tmpl</folder>
<folder>Helper</folder>
<folder>language</folder>
<filename>mod_foo.xml</filename>
</files>
</extension>
</syntaxhighlight>

<translate>
== Test Your Module == 
</translate>
<translate> Now you can zip all files and install them via the Joomla Extension Manager.</translate>
<translate> After that you can choose your module in the module manager, when you create a new site module.</translate>

<translate> In the Frontend you will see your module like displayed in the next image. The text from your helper file is displayed.</translate>
{{-}}
[[File:moduletutorial23-<translate> en</translate>.png|700px|center]]

<translate>
== Conclusion == 
</translate>
<translate> As you can see, once you get a bit into the namespaces, they are not that complicated anymore. In big projects they can bring a lot of benefits. However, we should plan namespaces, as otherwise it will soon be more time-consuming.</translate>

<translate> You can find boilerplates hereː</translate>
* https://github.com/joomla-extensions/boilerplate/tree/master/module
<translate> The sample files for this Tutorial can be found hereː</translate>
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

<translate>
== Customizationː Add Parameters Via Form Fields == 
</translate>

<translate>
=== Requirements === 
</translate>
<translate> You need Joomla! 4.x for this tutorial.</translate>

<translate>
== Customization with Form Fields and Parameters == 
</translate>
<translate> Form fields give a great deal of customization in Joomla and for modules are the sole way of allowing the user to tweak the module to the needs of their site.</translate>

<translate> In this case we are going to extend our previous example using a URL field for inserting a domain that we can use as link in the front end. To allow this to happen we will use the [[S:MyLanguage/URL_form_field_type|URL Form Field]] type.</translate>

<translate> After that, we insert parameters that allow to use standard functionality of Joomla.</translate>

<translate> Let's take a look on how to use them in Joomla 4.</translate>

<translate>
=== File Structure === 
</translate>
<translate> We will change the following files:</translate>
<translate>
* <tt>mod_foo.xml</tt> - This is the file where we add the fields.
* <tt>tmpl/default.php</tt> - In this file demonstrate how the data of a field can be used.
* <tt>language/en-GB/en-GB.mod_foo.ini</tt> - Here we use a language string so that the field can be labeled correctly in different languages.</translate>

<translate>
=== Editing mod_foo.xml === 
</translate>
<translate> First we set a custom parameter.</translate>

<syntaxhighlight lang="xml">
<field
name="domain"
type="url"
label="MOD_FOO_FIELD_URL_LABEL"
filter="url"
/>
</syntaxhighlight>

<translate> Then we insert Joomla default fields, so that we can use cache, moduleclass-suffix and layouts.</translate>

<syntaxhighlight lang="xml">
<field
name="layout"
type="modulelayout"
label="JFIELD_ALT_LAYOUT_LABEL"
class="custom-select"
/>

<field
name="moduleclass_sfx"
type="textarea"
label="COM_MODULES_FIELD_MODULECLASS_SFX_LABEL"
rows="3"
/>

<field
name="cache"
type="list"
label="COM_MODULES_FIELD_CACHING_LABEL"
default="0"
>
<option value="1">JGLOBAL_USE_GLOBAL</option>
<option value="0">COM_MODULES_FIELD_VALUE_NOCACHING</option>
</field>

<field
name="cache_time"
type="number"
label="COM_MODULES_FIELD_CACHE_TIME_LABEL"
default="0"
/>

<field
name="cachemode"
type="hidden"
default="itemid"
>
<option value="itemid"></option>
</field>
</syntaxhighlight>

<translate>
==== Completed mod_foo.xml ==== 
</translate>
<translate> The complete <tt>mod_foo.xml</tt> file is as follows:</translate>

<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="4.0" client="site" method="upgrade">
<name>MOD_FOO</name>
<creationDate>[DATE]</creationDate>
<author>[AUTHOR]</author>
<authorEmail>[AUTHOR_EMAIL]</authorEmail>
<authorUrl>[AUTHOR_URL]</authorUrl>
<copyright>[COPYRIGHT]</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<version>1.0</version>
<description>MOD_FOO_XML_DESCRIPTION</description>
<namespace>Joomla\Module\Foo</namespace>
<files>
<filename module="mod_foo">mod_foo.php</filename>
<folder>tmpl</folder>
<folder>Helper</folder>
<folder>language</folder>
<filename>mod_foo.xml</filename>
</files>
<config>
<fields name="params">
<fieldset name="basic">
<field
name="domain"
type="url"
label="MOD_FOO_FIELD_URL_LABEL"
filter="url"
/>
</fieldset>
<fieldset name="advanced">
<field
name="layout"
type="modulelayout"
label="JFIELD_ALT_LAYOUT_LABEL"
class="custom-select"
/>
<field
name="moduleclass_sfx"
type="textarea"
label="COM_MODULES_FIELD_MODULECLASS_SFX_LABEL"
rows="3"
/>
<field
name="cache"
type="list"
label="COM_MODULES_FIELD_CACHING_LABEL"
default="0"
>
<option value="1">JGLOBAL_USE_GLOBAL</option>
<option value="0">COM_MODULES_FIELD_VALUE_NOCACHING</option>
</field>
<field
name="cache_time"
type="number"
label="COM_MODULES_FIELD_CACHE_TIME_LABEL"
default="0"
/>
<field
name="cachemode"
type="hidden"
default="itemid"
>
<option value="itemid"></option>
</field>
</fieldset>
</fields>
</config>
</extension>
</syntaxhighlight>

<translate>
=== Editing tmpl/default.php === 
</translate>
<translate> We can use the value of the parameter for creating a hyperlink in the Frontend. We can access the value via the variable $params.</translate>

<syntaxhighlight lang="php">$domain = $params->get('domain', 'https://www.joomla.org');</syntaxhighlight>

<translate> Later we set use this value for creating the hyperlink.</translate>

<syntaxhighlight lang="php">
<a href="<?php echo $domain; ?>">
<?php echo '[PROJECT_NAME]' . $test; ?>
</a>
</syntaxhighlight>

<translate>
==== Completed tmpl/default.php file ==== 
</translate>
<translate> The complete <tt>tmpl/default.php</tt> file is as follows:</translate>

<syntaxhighlight lang="php">

<?php
/**
* @package [PACKAGE_NAME]
*
* @author [AUTHOR] <[AUTHOR_EMAIL]>
* @copyright [COPYRIGHT]
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link [AUTHOR_URL]
*/

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

$domain = $params->get('domain', 'https://www.joomla.org');
?>

<a href="<?php echo $domain; ?>">
<?php echo '[PROJECT_NAME]' . $test; ?>
</a>
</syntaxhighlight>

<translate>
=== Editing language/en-GB/en-GB.mod_foo.ini === 
</translate>
<translate> Here we can specify the text for the English version of the field label.</translate>

<syntaxhighlight lang="php">MOD_FOO_FIELD_URL_LABEL="Url"</syntaxhighlight>

<translate>
==== Completed language/en-GB/en-GB.mod_foo.ini ==== 
</translate>
<translate> The complete <tt>language/en-GB/en-GB.mod_foo.ini</tt> file is as follows:</translate>

<syntaxhighlight lang="php">
MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"
MOD_FOO_FIELD_URL_LABEL="Url"
</syntaxhighlight>

<translate>
== Test Your Module == 
</translate>
<translate> Now you can zip all files and install them via the Joomla Extension Manager.</translate>
<translate> After that you can choose your module in the module manager, when you create a new site module.</translate>

<translate> In the Backend, you will see your module like displayed in the next image.</translate>

<translate> In the basic tab, you will see the custom field where you can insert a domain. The text for the label is fetched from the language file.</translate>
{{-}}
[[File:moduletutorial31-<translate> en</translate>.png|700px|center]]

<translate> In the advanced tab, you will see all default options except the cache mode because of this is a hidden field.</translate>
{{-}}
[[File:moduletutorial32-<translate> en</translate>.png|700px|center]]

<translate> In the Frontend, you will see your module like displayed in the next image. The text form your helper file is displayed and you should see a hyperlink.</translate>
{{-}}
[[File:moduletutorial33-<translate> en</translate>.png|700px|center]]

<translate>
== Conclusion == 
</translate>
<translate> Form fields give the user an easy way to customize the module to their sites settings. This allows the modules scope to be increased.</translate>

<translate> You can find boilerplates hereː</translate>
* https://github.com/joomla-extensions/boilerplate/tree/master/module
<translate> The sample files for this Tutorial can be found hereː</translate>
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules
<translate> See this issue for possible future changes:</translate>
* https://github.com/joomla/joomla-cms/pull/23553

<translate>
== Use Install, Update and Uninstall Script == 
</translate>

<translate>
=== Requirements === 
</translate>
<translate> You need Joomla! 4.x for this tutorial.</translate>

<translate>
=== Scripts === 
</translate>
<translate> Installing, updating and uninstalling a module may require additional operations that cannot be achieved by the basic operations described in the main XML file. Joomla offers a new approach to solve this problem. It consists in using a PHP script file containing a class using five methods:</translate>
<translate>
* preflight which is executed before install and update
* install
* update
* uninstall
* postflight which is executed after install and update</translate>

<translate> Let's take a look how to use them in Joomla 4. We use the helper file for this.</translate>

<translate>
=== File Structure === 
</translate>
<translate> We will create/change the following files:</translate>
<translate>
* <tt>script.php</tt> - This is the file we use here as an example. We have to create it.
* <tt>language/en-GB/en-GB.mod_foo.sys.ini</tt> - In this file we will add text.
* <tt>mod_foo.xml</tt> - We create a new file. This must be installed during the installation. For this we have to specify it in this file.</translate>

<translate>
=== Creating script.php === 
</translate>
<translate> Writing an extension script consists in declaring a class whose name is <tt>mod_ModuleNameInstallerScript</tt> with these 5 methods. See the comments in the file for more information. In this comments I explain when a method is called.</translate>

<translate> In this example, I only use text to show when which method will be executed. In addition, I show you how to check the minimum requirements. Of course you can do much more. For example, you can delete files that are no longer needed in a new version of your module. This can be seen in the file. Another idea for this file is to create sample content, to show a success message with the current installed version number or you can redirect after a successful installation to the page with the module settings.</translate>

<translate>
==== Completed script.php ==== 
</translate>
<translate> The complete <tt>script.php</tt> file is as follows:</translate>

<syntaxhighlight lang="php">

<?php
/**
* @package [PACKAGE_NAME]
*
* @author [AUTHOR] <[AUTHOR_EMAIL]>
* @copyright [COPYRIGHT]
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link [AUTHOR_URL]
*/

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

use Joomla\CMS\Language\Text;
use Joomla\CMS\Log\Log;

/**
* Script file of Foo module
*/
class mod_fooInstallerScript {

/**
* Extension script constructor.
*
* @return void
*/
public function __construct() {
$this->minimumJoomla = '4.0';
$this->minimumPhp = JOOMLA_MINIMUM_PHP;
}

/**
* Method to install the extension
*
* @param InstallerAdapter $parent The class calling this method
*
* @return boolean True on success
*/
function install($parent) {
echo Text::_('MOD_FOO_INSTALLERSCRIPT_INSTALL');

return true;
}

/**
* Method to uninstall the extension
*
* @param InstallerAdapter $parent The class calling this method
*
* @return boolean True on success
*/
function uninstall($parent) {
echo Text::_('MOD_FOO_INSTALLERSCRIPT_UNINSTALL');

return true;
}

/**
* Method to update the extension
*
* @param InstallerAdapter $parent The class calling this method
*
* @return boolean True on success
*/
function update($parent) {
echo Text::_('MOD_FOO_INSTALLERSCRIPT_UPDATE');

return true;
}

/**
* Function called before extension installation/update/removal procedure commences
*
* @param string $type The type of change (install, update or discover_install, not uninstall)
* @param InstallerAdapter $parent The class calling this method
*
* @return boolean True on success
*/
function preflight($type, $parent) {
// Check for the minimum PHP version before continuing
if (!empty($this->minimumPhp) && version_compare(PHP_VERSION, $this->minimumPhp, '<')) {
Log::add(Text::sprintf('JLIB_INSTALLER_MINIMUM_PHP', $this->minimumPhp), Log::WARNING, 'jerror');

return false;
}

// Check for the minimum Joomla version before continuing
if (!empty($this->minimumJoomla) && version_compare(JVERSION, $this->minimumJoomla, '<')) {
Log::add(Text::sprintf('JLIB_INSTALLER_MINIMUM_JOOMLA', $this->minimumJoomla), Log::WARNING, 'jerror');

return false;
}

echo Text::_('MOD_FOO_INSTALLERSCRIPT_PREFLIGHT');
echo $this->minimumJoomla . ' ' . $this->minimumPhp;

return true;
}

/**
* Function called after extension installation/update/removal procedure commences
*
* @param string $type The type of change (install, update or discover_install, not uninstall)
* @param InstallerAdapter $parent The class calling this method
*
* @return boolean True on success
*/
function postflight($type, $parent) {
echo Text::_('MOD_FOO_INSTALLERSCRIPT_POSTFLIGHT');

return true;
}
}
</syntaxhighlight>

<translate>
=== Editing language/en-GB/en-GB.mod_foo.sys.ini === 
</translate>
<translate> There is not much to explain here. Write the text for the translation into this file.</translate>

<translate>
==== Completed language/en-GB/en-GB.mod_foo.sys.ini file ==== 
</translate>
<translate> The complete <tt>language/en-GB/en-GB.mod_foo.sys.ini</tt> file is as follows:</translate>

<syntaxhighlight lang="php">
MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"
MOD_FOO_INSTALLERSCRIPT_PREFLIGHT="<p>Anything here happens before the installation/update/uninstallation of the module</p>"
MOD_FOO_INSTALLERSCRIPT_UPDATE="<p>The module has been updated</p>"
MOD_FOO_INSTALLERSCRIPT_UNINSTALL="<p>The module has been uninstalled</p>"
MOD_FOO_INSTALLERSCRIPT_INSTALL="<p>The module has been installed</p>"
MOD_FOO_INSTALLERSCRIPT_POSTFLIGHT="<p>Anything here happens after the installation/update/uninstallation of the module</p>"
</syntaxhighlight>

<translate>
=== Editing mod_foo.xml === 
</translate>
<translate> You have to add a line, so that the script is called automatically in Joomla.</translate>

<syntaxhighlight lang="xml"><scriptfile>script.php</scriptfile></syntaxhighlight>

<translate>
==== Completed mod_foo.xml ==== 
</translate>
<translate> The complete <tt>mod_foo.xml</tt> file is as follows:</translate>

<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="4.0" client="site" method="upgrade">
<name>MOD_FOO</name>
<creationDate>[DATE]</creationDate>
<author>[AUTHOR]</author>
<authorEmail>[AUTHOR_EMAIL]</authorEmail>
<authorUrl>[AUTHOR_URL]</authorUrl>
<copyright>[COPYRIGHT]</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<version>1.0</version>
<description>MOD_FOO_XML_DESCRIPTION</description>
<namespace>Joomla\Module\Foo</namespace>
<scriptfile>script.php</scriptfile>
<files>
<filename module="mod_foo">mod_foo.php</filename>
<folder>tmpl</folder>
<folder>Helper</folder>
<folder>language</folder>
<filename>mod_foo.xml</filename>
</files>
<config>
<fields name="params">
<fieldset name="basic">
<field
name="domain"
type="url"
label="MOD_FOO_FIELD_URL_LABEL"
filter="url"
/>
</fieldset>
<fieldset name="advanced">
<field
name="layout"
type="modulelayout"
label="JFIELD_ALT_LAYOUT_LABEL"
class="custom-select"
/>
<field
name="moduleclass_sfx"
type="textarea"
label="COM_MODULES_FIELD_MODULECLASS_SFX_LABEL"
rows="3"
/>
<field
name="cache"
type="list"
label="COM_MODULES_FIELD_CACHING_LABEL"
default="0"
>
<option value="1">JGLOBAL_USE_GLOBAL</option>
<option value="0">COM_MODULES_FIELD_VALUE_NOCACHING</option>
</field>
<field
name="cache_time"
type="number"
label="COM_MODULES_FIELD_CACHE_TIME_LABEL"
default="0"
/>
<field
name="cachemode"
type="hidden"
default="itemid"
>
<option value="itemid"></option>
</field>
</fieldset>
</fields>
</config>
</extension>
</syntaxhighlight>

<translate>
== Test Your Module == 
</translate>
<translate> Now you can zip all files and install them via the Joomla Extension Manager.</translate>
<translate> Immediately after the installation, you will see the following information. This you had entered in the script so.</translate>
{{-}}
[[File:moduletutorial14-<translate> en</translate>.png|700px|center]]

<translate>
== Conclusion == 
</translate>
<translate> As you can see, Joomla offers you a lot to make your extension easy to use - right from the start.</translate>

<translate> You can find boilerplates hereː</translate>
* https://github.com/joomla-extensions/boilerplate/tree/master/module
<translate> The sample files for this Tutorial can be found hereː</translate>
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

<translate>
== Use Joomla Updaterː Adding Auto Update == 
</translate>

<translate>
=== Requirements === 
</translate>
<translate> You need Joomla! 4.x for this tutorial.</translate>

<translate>
=== Joomla Updater === 
</translate>
<translate> The first thing to do is to read the [[S:MyLanguage/J2.5:Managing_Component_Updates|Managing Component Upgrades with Joomla 2.5 - Part 1]] tutorial to give an idea of how the upgrade process works in Joomlaǃ. Whilst written for 2.5 the process hasn't changed. Also read [[S:MyLanguage/Deploying_an_Update_Server|Deploying an update server]] - this is what we'll be implementing in this tutorial.</translate>

<translate>
=== File Structure === 
</translate>
<translate> We will create/change the following files:</translate>
<translate> * <tt>mod_foo.xml</tt> - The only way to update our existing module is to add in a update server - for example <tt><nowiki>http://www.example.com/foo_update.xml</nowiki></tt> - into the xml file.</translate>
<translate> * <tt>foo_update.xml</tt> - Then we have to create the XML file for the update server at <tt><nowiki>http://www.example.com/foo_update.xml</nowiki></tt> to let Joomla know an update is available.</translate>

<translate>
==== Editing mod_foo.xml ==== 
</translate>
<translate> To add our update server, we need to insert the following lines in your XML-Fileː</translate>

<syntaxhighlight lang="php">
<updateservers>
<server type="extension" priority="1" name="[PROJECT_NAME]">https://www.example.com/mod_foo.xml</server>
</updateservers>
</syntaxhighlight>

<translate>
==== Completed mod_foo.xml ==== 
</translate>
<translate> The complete <tt>mod_foo.xml</tt> file is as follows:</translate>

<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="4.0" client="site" method="upgrade">
<name>MOD_FOO</name>
<creationDate>[DATE]</creationDate>
<author>[AUTHOR]</author>
<authorEmail>[AUTHOR_EMAIL]</authorEmail>
<authorUrl>[AUTHOR_URL]</authorUrl>
<copyright>[COPYRIGHT]</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<version>1.0</version>
<description>MOD_FOO_XML_DESCRIPTION</description>
<namespace>Joomla\Module\Foo</namespace>
<files>
<filename module="mod_foo">mod_foo.php</filename>
<folder>tmpl</folder>
<folder>Helper</folder>
<folder>language</folder>
<filename>mod_foo.xml</filename>
</files>
<updateservers>
<server type="extension" priority="1" name="[PROJECT_NAME]">https://www.example.com/mod_foo.xml</server>
</updateservers>
<config>
<fields name="params">
<fieldset name="basic">
<field
name="domain"
type="url"
label="MOD_FOO_FIELD_URL_LABEL"
filter="url"
/>
</fieldset>
<fieldset name="advanced">
<field
name="layout"
type="modulelayout"
label="JFIELD_ALT_LAYOUT_LABEL"
class="custom-select"
/>
<field
name="moduleclass_sfx"
type="textarea"
label="COM_MODULES_FIELD_MODULECLASS_SFX_LABEL"
rows="3"
/>
<field
name="cache"
type="list"
label="COM_MODULES_FIELD_CACHING_LABEL"
default="0"
>
<option value="1">JGLOBAL_USE_GLOBAL</option>
<option value="0">COM_MODULES_FIELD_VALUE_NOCACHING</option>
</field>
<field
name="cache_time"
type="number"
label="COM_MODULES_FIELD_CACHE_TIME_LABEL"
default="0"
/>
<field
name="cachemode"
type="hidden"
default="itemid"
>
<option value="itemid"></option>
</field>
</fieldset>
</fields>
</config>
</extension>
</syntaxhighlight>

<translate> Now that Joomlaǃ is searching for updates to our extension, let's create one to test our process. First we need to create the file <tt>foo_update.xml</tt>. So far we have only described the update server. We do not know yet if there is an update. In the file <tt>foo_update.xml</tt> we indicate when a new version is published and where it can be downloaded.</translate>

<translate>
=== Creating foo_update.xml === 
</translate>
<translate> Now we have to create the XML file at <tt><nowiki>http://www.example.com/foo_update.xml</nowiki></tt> to let Joomla know an update is available.</translate>

<translate>
==== Completed foo_update.xml ==== 
</translate>
<translate> The complete <tt>foo_update.xml</tt> file is as follows:</translate>

<syntaxhighlight lang="xml">
<?xml version="1.0" ?>
<updates>
<update>
<name>Foo</name>
<description>This is mod_foo 1.0.1</description>
<element>mod_foo</element>
<type>module</type>
<version>1.0.1</version>
<downloads>
<downloadurl type="full" format="zip">http://www.example.com/mod_foo_101.zip</downloadurl>
</downloads>
<maintainer>Joomla</maintainer>
<maintainerurl>http://www.example.com</maintainerurl>
<targetplatform name="joomla" version="4.0"/>
<client>site</client>
</update>
</updates>
</syntaxhighlight>

<translate> After uploading this file to the address <tt><nowiki>https://www.example.com/mod_foo.xml</nowiki></tt> the update will be displayed in the Joomla Backend.</translate>

<translate>
=== Test Your Module Update === 
</translate>
<translate> Create a copy of the module as it is now. Then let's update the version number to 1.0.1. Now you can zip all files. After that you should load your zip to the URL <tt><nowiki>http://www.example.com/mod_foo_101.zip</nowiki></tt>. Now you can update your module via the Joomla Updater.</translate>

<translate>
=== Commercial Modules === 
</translate>
<translate> Note that in our files we have linked to the extensions updates xml file. And from that xml file we have a location for the zip of the module. This means that if someone was to track this backwards they could find the physical source of your modules zip file. If you don't do like this, you can find a solution in this PRː https://github.com/joomla/joomla-cms/pull/15185 .</translate>

<translate>
=== Conclusion === 
</translate>
<translate> With the Joomlaǃ updater, you can easily reach all users and tell them that there is a new version. Even the update itself is easy.</translate>

<translate> Each extension should use an update server--especially for security reasons.</translate>

<translate> You can find boilerplates hereː</translate>
* https://github.com/joomla-extensions/boilerplate/tree/master/module
<translate> The sample files for this Tutorial can be found hereː</translate>
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

<noinclude>
[[Category:Beginner Development{{#translation:}}]]
[[Category:Tutorials{{#translation:}}]]
[[Category:Tutorials in a Series{{#translation:}}]]
[[Category:Development{{#translation:}}]]
[[Category:Module Development{{#translation:}}]]
[[Category:Joomla! 4.x{{#translation:}}]]
[[Category:Joomla! 4.0{{#translation:}}]]
</noinclude>

Using Tag Manager

2023-04-15T18:10:00Z

Cmb: Several markup changes. URL corrections.

==What is the Google Tag Manager?==
The Google Tag Manager is a way to combine all your tracking and marketing scripts into one, version-controlled container which is inserted into your site, calling a single file instead of multiple files that can slow your site down.

It also allows you to fire specific tags—such as conversion tags—on specific pages, without having to edit the code of the component or extension that powers the page.

==Configuring the Google Tag Manager==
Before you can use the Google Tag Manager you must [https://marketingplatform.google.com/about/tag-manager/ sign up].

Once you have a Google Tag Manager account, you'll log in and see the dashboard from which you can create a new account.

Generally you should create a new account for each client you work with. One account can have multiple containers and many users with these levels of access:

# View only
# View and edit
# View, edit, delete and publish

==Installing Tag Manager on Your Joomla Website==

Inserting Google Tag Manager into your website requires either editing your template file or using an extension to insert the container in the correct location.

There are pros and cons for both approaches. Inserting into the template requires you to edit the code of the ''index.php'' file. However it means it's not easy to remove or unpublish accidentally. Using a plugin requires an additional call on page load, and can potentially have compatibility issues if code changes are necessary.

===Google Tag Manager Extensions===
There are several extensions you can use to embed the Google Tag Manager code. Browse them on the [https://extensions.joomla.org/ Joomla! Extensions Directory™].

Joomla 1.5 to 4.x Step by Step Migration

2023-02-20T19:12:59Z

Cmb: Expanded Migration Tool section.

<noinclude><languages /></noinclude>

<translate>
The following are step-by-step instructions to migrate your 1.5 site to Joomla 4.x. While there are many ways to migrate your site, this will give you the basic procedure to follow.</translate>

<translate>== Introduction == </translate>

<translate>
The migration from Joomla! 1.5 to 4.x is a major migration. There are many changes in features and database tables between these two versions. It is '''not''' a one-click update. You will be building and installing a fresh Joomla! 4 installation and then migrating (moving) your data into it. If you haven't already, you may want to start with the [[S:MyLanguage/Migration Step by Step Self Assessment|Self Assessment]] and [[S:MyLanguage/Planning Migration - Joomla 1.5 to 3|Planning]] documents.</translate>

<translate>
Let’s first distinguish between Joomla Core data and third-party extension data. Joomla Core data (Components) are:</translate>

<translate>

* Categories
* Articles
* Menus
* Modules (core modules - not third-party)
* Banners
* Contacts
* Messaging
* News Feeds
* Redirect
* Search
* Smart Search
</translate>

<translate>== Step-by-Step == </translate>
<translate>
Moving Joomla core data is fairly straight-forward with the use of a migration tool. Everything else is a third-party extension or a custom built extension. This includes the template. Each third-party extension needs to be researched to determine if it’s ready for Joomla 4.x and has a migration path. You may have done this in the [[S:MyLanguage/Planning Migration - Joomla 1.5 to 3|planning]] process. If not, do it now. Some third-party extensions can be migrated with a third-party tool. Some cannot. Read. Research. Plan.</translate>

<translate>
Since there are many ways to migrate data and each site is different, the exact steps are going to be slightly different for every site.</translate>

<translate>=== Prepare a Location for Joomla 4 === </translate>

<translate>
# Make sure your server environment meets the [https://downloads.joomla.org/technical-requirements technical requirements for Joomla! 4] before proceeding.</translate>{{-}}{{note|<translate>
'''Note''' If your host does not meet the technical requirements, you will need to change hosts. If you need to change hosts, set up a new hosting account on a host that meets the specifications and install your fresh Joomla 4.x site in the root of the server on a temporary domain. This will make it easier when it’s time to go live. Alternatively, you can set up a development location on a local device. (See below.)</translate>}}
# {{anchor|new-j3-database}}<translate>
Create a new database and new user for your Joomla! 4.x site. Document the database name, database username and database password as you’ll need these when you [[#install-j3|install Joomla 4]]</translate>.

<translate>=== Set Up a Development Location === </translate>
<translate>
# Create a testing site or build area to work in with one of the following:
#* A subdomain
#* A subdirectory
#* A local device via [https://www.wampserver.com/en/ WAMP], [https://www.mamp.info/en/windows/ MAMP], [https://sourceforge.net/projects/lampas/ LAMP], [https://sourceforge.net/projects/xampp/ XAMPP].
#* A new hosting account on a temporary domain in the root (if you would like to change hosts in the process of migration)
#**Restoring a site on a local device. See [[S:MyLanguage/Installing Joomla locally|Installing Joomla locally]] and [[S:MyLanguage/Setting up your workstation for Joomla development|Setting up your workstation for Joomla development]].
#**Restoring a site with Akeeba Backup. (Read the developer documentation or videos for how to restore a backup of an Akeeba Backup file.)''</translate>
<translate>
# {{anchor|install-j3}}[[S:MyLanguage/J3.x:Installing_Joomla|Install a fresh installation]] of the [https://downloads.joomla.org/ latest version of Joomla 4.x] into your testing site location using your new database name and database credentials. </translate>{{-}}{{note|<translate>
'''Warning''' Do '''not''' install the sample data.</translate>|type=serious}}{{-}}{{note|<translate>
'''Note''' If you will be migrating any of the core extensions that will be decoupled from Joomla! 3.4+, you will need to install Joomla 4.x '''and''' the core supported extension. Core supported extensions will be accessible via the [https://extensions.joomla.org/ Joomla Extensions Directory] and via the Install from web tab of the Extension Manager. Make sure you install any core supported extensions before migrating data. See the [https://developer.joomla.org/roadmap.html Project Roadmap] for more details on what will be decoupled/removed. As of August 2021, only Web Links has been decoupled.</translate>}}
<translate>
# Run a backup of your Joomla 4 site. ([[S:MyLanguage/Backup_Basics_for_a_Joomla!_Web_Site|Backup Basics for a Joomla! Web Site]] or see [[#Suggested Tools|Suggested Tools]])</translate>

<translate>=== Prepare Your Current 1.5 Site === </translate>
<translate>
# On your 1.5 site, update it to the latest version 1.5.26 after backing it up.
# Clean up your sections, categories, articles, modules, menu items. Make sure they all have unique aliases.
# Empty the trash in the content manager (sections, categories, articles), menu manager, module manager.</translate>{{-}}{{note|<translate>
'''Note''' Sections no longer exist in Joomla 4. Sections become a parent Category. Categories became nested categories of the parent category.</translate>}}{{-}}
<translate>
# Notify users that any changes on the current site from this point forward will have to be reentered on the new site. For complex migrations with changing data, see the [https://magazine.joomla.org/all-issues/issue-march-2014/complex-joomla-15-migration-with-minimal-downtime Complex Joomla! 1.5 Migration With Minimal Downtime] magazine article and the [https://www.youtube.com/watch?v=lPwcWaKB6dY&list=UUy6ThiEDnalZOd_pgtpBk1Q&index=7 Complex Migrations video].</translate>

<translate>=== Choose a Migration Tool === </translate>
<translate>
# There are many migration tools. Some are free, some cost a bit of money. Some only migrate certain data. Some migrate more types of data than others.
# Migration tools can be found at the [https://extensions.joomla.org/category/migration-a-conversion/ Migration & Conversion category] in the Joomla Extension Directory.
# Verify that the candidate migration tool has been updated to work with Joomla 4.
# Each migration tool has its own step-by-step documentation on how to move data. (If they don’t don’t use it.) Some migration tools will require the 1.5 site and 4 site on the same server. If you’re switching hosts, you will want to restore a *subdomain* of your 1.5 site on your new hosting account to pull the data from. Then kill it when you’re done.
</translate>
<translate>
# When you choose a tool, select one that allows you to preserve the ItemIDs. This is necessary to keep your search engine ranking intact or you may have more redirects to do. More information on redirects follow.
# If you have a small site, you may want to do the migration manually. Create categories and articles and copy the HTML over into your new site. Then copy the image directory over. Keep the ''/stories'' directory (which is no longer the default image directory in Joomla 4.x) or your image links will be broken until you fix each one.
# One of the migration tools (a free one) allows you to bring articles and only images associated with those articles over. This is helpful if your Media Manager is out of control.</translate>

<translate>=== Migration === </translate>
<translate>
# Migrate all core data you want to move to Joomla 4.x. If your migration tool asks to move Sections and Categories, definitely do both. The conversion will happen to categories and nested categories automatically.
# Run the Database Fix by going to {{rarr|Extension Manager,Database}} and click the ''Fix'' button in the top toolbar.
# Install your new template or converted template so that you can see your content. See more about [[S:MyLanguage/Template_Considerations_During_Migration|Template Considerations]].</translate>
<translate>
# Add new menus if the tool you chose to use didn't bring over menus. If you want to use [[S:MyLanguage/Split_menus|split menus]], set that up now.
# Add modules if the tool you chose to use didn't bring over modules. If the tool you chose to use brought over modules, change the module positions to the positions in your new template if required so that your modules show up and you can see what you’re working with.</translate>
<translate>
# Check for duplicate alias issues and fix them.
# Check your internal links. If any are broken, fix them.
# Take a backup.
# Install other third-party extensions and configure them. (For example editors, Akeeba backup, slideshows, or plugins.)
# Take a backup.</translate>
<translate>
# If you have large extensions with data to migrate, do each one according to the developer documentation and then take a backup after each one.
# If your migration tool didn't move the images, you will want to move your images from the 1.5 site to the 4.x site. Note: keep the ''/stories'' directory unless you want to relink all your images. You can start a new organisational structure in the ''/images'' directory from here forward if stories is a mess.</translate>
<translate>
# Recommended but not required unless you have issues: [[S:MyLanguage/Fixing_the_assets_table|Fix asset issues]]. See [[#Suggested_Tools|below for a helpful tool]].
# If you are going to add anything to your site or use new core features such as Tags or Custom Fields, get them set up and configured at this time.</translate>
<translate>
# Check your URLs on the Joomla 4 site and compare to the Joomla 1.5 site. If they are different, document each 1.5 URL and what Joomla 4.x URL they will be going to so that you can do redirects and keep your ranking. (An Excel spreadsheet is helpful.) See:</translate>
<translate>
#*[https://magazine.joomla.org/all-issues/issue-april-2014/migration-seo-tips-series-part-1-planning-your-link-migration-strategy Migration SEO Tips Series - Part 1 - Planning Your Link Migration Strategy]; and
#*[https://magazine.joomla.org/all-issues/issue-may-2014/migration-seo-tips-series-part-2-monitoring-your-migrated-site-health Migration SEO Tips Series - Part 2 - Monitoring Your Migrated Site's Health].</translate>
<translate>
# Take a backup.
# Check everything.
# Clean up more.
# Test everything.
# Take a backup.
# Move or change or add updated data from the 1.5 site to the Joomla 4 site.
# Add Google Analytics to the template or use a third-party plugin.
# Check the Global Configuration and make sure all is as it should be.</translate>
<translate>
# Take a final backup of the Joomla 4.x site.
# Take a final backup of the 1.5 site.
# Move your 1.5 site from the root to another subdomain or subdirectory or simply delete it. (This is so that you have it again for a brief time if you need to refer to it.)</translate>
<translate>
# Backup and restore using a suggested tool (below) or simply move files to restore your 4.x site to the root of your hosting.</translate>{{-}}{{note|<translate>
'''Note''' If you are changing hosts, you can leave your Joomla 4.x site where it is and simply change name servers on the domain to make it live. Make sure you've addressed any email issues first.</translate>}}
<translate>
# Enable ''.htaccess'' if necessary for Search Engine Friendly URLs.
# Create a sitemap and submit to Google Webmaster Tools or any other search engine you would like.
# Do all your redirects from the spreadsheet you created earlier for URLs that changed in the migration process.</translate>
<translate>
# Make any other changes that needed to wait until the 4.x site was live.
# Test again.
# Take another backup.
# Kill any instance(s) of the 1.5 site as soon as possible.</translate>
<translate>
# Remove all other development sites you may have been working with or keep them up-to-date if they are running a current version in order to ward off hack attempts on your server.
# Welcome to Joomla! 4.x!</translate>

<translate>== Suggested Tools == </translate>

<translate>
*[https://extensions.joomla.org/extension/access-a-security/site-security/akeeba-backup Akeeba Backup] for backup and restore.
*[https://extensions.joomla.org/extension/access-a-security/site-access/acl-manager ACL Manager] to fix asset issues in a few clicks.</translate>

<translate>

[[Category:Migration]]
[[Category:Tutorials]]
</translate>

Smart Search quickstart guide

2023-02-20T02:16:09Z

Cmb: Markup changes including right arrow markup. Changes for Words2Watch compliance.

{{version|2.5}}
==Enabling the Smart Search Content Plugin==
Smart Search is not enabled by default. To start using Smart Search, enable the Smart Search content Plugin:

# Log in to the Administrator.
# Click on the {{rarr|Extensions,Plugin Manager}} menu item.
# Filter the Plugin list so that only content Plugins are shown by selecting ''content'' from the ''Select Type'' filter drop-down.
# Find ''Content - Smart Search'' on the list of Plugins.
# Click on the red circle icon in the Status column for the Smart Search Plugin. The red circle should change to a green tick indicating that the Plugin is now enabled.

'''Note''' If you have content items that are not available for public view then the auto-completion feature will still show terms contained in those content items. The content items themselves cannot be viewed and will not be listed in search results, but if revealing the presence of a word or phrase in a restricted content item is of concern you should disable auto-completion. To disable auto-completion:

# Log in to the Administrator.
# Click on {{rarr|Components,Smart Search}}.
# Click on the ''Options'' toolbar button.
# Change ''Search Suggestions'' from ''Show'' to ''Hide''.
# Click ''Save and Close''.

==Preparing Smart Search Plugins==
For content to be displayed in search results it must first be indexed by one of the Smart Search Plugins. Before starting the indexer, it is recommended that you review the available Plugins and disable any that will not be necessary for your site. To review the available Smart Search Plugins use the following procedure:

# Log in to the Administrator.
# Click on the {{rarr|Extensions,PluginManager menu item}}.
# Filter the Plugin list so that only Smart Search Plugins are shown by selecting ''finder'' from the ''Select Type'' filter drop-down.
# Review the list of Plugins and disable any that will not be necessary for your site by clicking on the green tick icon in the Status column for the Plugin. This should change to a red circle to indicate that the Plugin is disabled.

==Running the Indexer==
After you have reviewed the search Plugins, it is time to start the Smart Search indexer. This will scan the content on your website and build an index that will enable fast and intelligent searching by your site visitors. To run the indexer use the following procedure:

# Log in to the Administrator.
# Click on the {{rarr|Components,Smart Search menu item}}.
# Click on the Index button in the toolbar to start the indexer. This will cause a modal window to load with some indexer status information and a progress bar. Depending on the size of your site, this can take a few minutes to a few hours to complete. The indexer uses AJAX requests to complete the overall process in small chunks so as to avoid timeouts and memory problems. Indexing is complete when the progress bar disappears and you see a message indicating that it is now safe to close the modal window.

Once the indexer has finished, closing the modal window will cause the Indexed Content screen in the background to refresh with an updated list of all the indexed content. If you would prefer that specific items not be displayed in search results, you can unpublish them from the Smart Search database by selecting the checkbox next to the title of the item and then pressing the Unpublish button. For more information on the Indexed Content screen see the [[Help25:Components Finder Manage Indexed Content|Manage Indexed Content help screen]].

'''Note''' If your site has a large amount of content, or particularly large content items, or has restricted disk space, you should read about [[Smart Search on large sites]].

==Exposing Smart Search to Site Users==
Now that the Smart Search index is prepared and ready, you need to expose Smart Search to your website's users. Smart Search offers two ways to do this:

===The Module Interface===
Smart Search includes a module that can be enabled to display a simple search form on any page in virtually any position. To enable the Smart Search module use the following procedure:

# Log in to the Administrator.
# Click on the {{rarr|Extensions,Module Manager menu item}}.
# Click the New button in the Module Manager toolbar.
# Select ''Smart Search Module'' from the list of module types shown.
# Configure the module by (at least) entering a title, selecting the module position, and adjusting the pages for it to display on if desired. Additional module configuration options are described on the [[Help25:Extensions Module Manager Smart Search|Smart Search module help screen]].
# Click on the Save button in the toolbar to publish the module.

===The Component Interface===
Smart Search can also be linked to via a Joomla menu item so that users can navigate directly to the main search form. To create a menu item link to Smart Search use the following procedure:

# Log in to the Administrator.
# Click on the {{rarr|Extensions,Module Manager menu item}}.
# Press the New button in the Menu Manager toolbar.
# Click the Select button next to the Menu Item Type field.
# Click on ''Search'' under the ''Smart Search'' entry on the list of menu item types shown.
# Configure the menu item by (at least) entering a Menu Title and adjusting the parent item if desired.
# Click on the Save button in the toolbar to publish the menu item.

==Testing, Testing, Testing==
To test Smart Search, navigate to one of the menu items you created and enter a query in the search form or enter a query into one of the instances of Smart Search module. You should be taken to a list of search results if any could be found for the word or phrase you entered. If no results could be found, a message will be displayed indicating no results. If no results could be found and the system has a search suggestion based on your term, the suggested search phrase will display above the message indicating no results.

==Finalizing the Switch==
To finalize the switch to Smart Search, remove all instances of ''mod_search'' and all menu items linking to ''com_search''. Smart Search does not interact with the old Joomla search system and exposing both systems may create a negative user experience by giving inconsistent and confusing search results.

==Removing Joomla Search Modules==
If you have the old Joomla search still available then you will probably want to remove it once you have Smart Search running correctly. To remove old Joomla search modules, use the following procedure:

# Log in to the Administrator.
# Click on the desired menu under the Menus menu item.
# Filter the modules listed so that only search modules are shown by selecting ''Search'' from the ''Select Type'' filter drop-down. If no such modules are listed then there are no instances of the old search available and you can skip this part.
# Select the checkbox at the top of the table to select all of the items in the list. Once all the instances of the old search have been selected, press the Delete button in the Module Manager toolbar. Be careful that you do not accidentally delete any other modules in the process.

==Removing Joomla Search Menu Items==
Unfortunately, there is no quick and easy way to remove all links to the old Joomla search system. To remove all the menu items to the old Joomla search system you will have to browse the menu items in each of your site's menus and manually remove the links. To make this process somewhat quicker, adjust the order of the table to list menu items by type in reverse alphabetical order. Now scroll down and look for links with type ''Search >> Search''. Delete those menu items by checking the checkbox to the left of the title and then pressing the Delete button in the Menu Manager toolbar.

[[Category:Smart Search]]

Smart Search quickstart guide

2023-02-19T16:57:11Z

Cmb: /* Enabling the Smart Search content plug-in */ Words2Watch and markup changes.

{{version|2.5}}
==Enabling the Smart Search Content Plugin==
Smart Search is not enabled by default. To start using Smart Search, enable the Smart Search content Plugin:

# Log in to the Administrator.
# Click on the {{rarr|Extensions,Plugin Manager}} menu item.
# Filter the Plugin list so that only content Plugins are shown by selecting ''content'' from the ''Select Type'' filter drop-down.
# Find ''Content - Smart Search'' on the list of Plugins.
# Click on the red circle icon in the Status column for the Smart Search Plugin. The red circle should change to a green tick indicating that the Plugin is now enabled.

'''Note''' If you have content items that are not available for public view then the auto-completion feature will still show terms contained in those content items. The content items themselves cannot be viewed and will not be listed in search results, but if revealing the presence of a word or phrase in a restricted content item is of concern you should disable auto-completion. To disable auto-completion:

# Log in to the Administrator.
# Click on {{rarr|Components,Smart Search}}.
# Click on the ''Options'' toolbar button.
# Change ''Search Suggestions'' from ''Show'' to ''Hide''.
# Click ''Save and Close''.

==Preparing Smart Search plug-ins==
For content to be displayed in search results it must first be indexed by one of the Smart Search plug-ins. Before starting the indexer, it is recommended that you review the available plug-ins and disable any that will not be necessary for your site. To review the available Smart Search plug-ins use the following procedure:

# Log in to the Administrator.
# Click on the Extensions → Plug-in Manager menu item.
# Filter the plug-in list so that only Smart Search plug-ins are shown by selecting "finder" from the "Select Type" filter drop-down.
# Review the list of plug-ins and disable any that will not be necessary for your site by clicking on the green tick icon in the Status column for the plug-in. This should change to a red circle to indicate that the plug-in is disabled.

==Running the Indexer==
After you have reviewed the search plug-ins, it is time to start the Smart Search indexer. This will scan the content on your Website and build an index that will enable fast and intelligent searching by your site visitors. To run the indexer use the following procedure:

# Log in to the Administrator.
# Click on the Components → Smart Search menu item.
# Click on the Index button in the toolbar to start the indexer. This will cause a modal window to load with some indexer status information and a progress bar. Depending on the size of your site, this can take a few minutes to a few hours to complete. The indexer uses AJAX requests to complete the overall process in small chunks so as to avoid timeouts and memory problems. Indexing is complete when the progress bar disappears and you see a message indicating that it is now safe to close the modal window.

Once the indexer has finished, closing the modal window will cause the Indexed Content screen in the background to refresh with an updated list of all the indexed content. If you would prefer that specific items not be displayed in search results, you can unpublish them from the Smart Search database by selecting the checkbox next to the title of the item and then pressing the Unpublish button. For more information on the Indexed Content screen see the [[Help25:Components Finder Manage Indexed Content|Manage Indexed Content help screen]].

'''IMPORTANT NOTE''': If your site has a large amount of content, or particularly large content items, or has restricted disk space, you should read about [[Smart Search on large sites]].

==Exposing Smart Search to Site Users==
Now that the Smart Search index is prepared and ready, you need to expose Smart Search to your Website's users. Smart Search offers two ways to do this:

===The Module Interface===
Smart Search includes a module that can be enabled to display a simple search form on any page in virtually any position. To enable the Smart Search module use the following procedure:

# Log in to the Administrator.
# Click on the Extensions → Module Manager menu item.
# Click the New button in the Module Manager toolbar.
# Select "Smart Search Module" from the list of module types shown.
# Configure the module by (at least) entering a title, selecting the module position, and adjusting the pages for it to display on if desired. Additional module configuration options are described on the [[Help25:Extensions Module Manager Smart Search|Smart Search module help screen]].
# Click on the Save button in the toolbar to publish the module.

===The Component Interface===
Smart Search can also be linked to via a Joomla menu item so that users can navigate directly to the main search form. To create a menu item link to Smart Search use the following procedure:

# Log in to the Administrator.
# Click on the Extensions → Module Manager menu item.
# Press the New button in the Menu Manager toolbar.
# Click the Select button next to the Menu Item Type field.
# Click on "Search" under the "Smart Search" entry on the list of menu item types shown.
# Configure the menu item by (at least) entering a Menu Title and adjusting the parent item if desired.
# Click on the Save button in the toolbar to publish the menu item.

==Testing, Testing, Testing==
To test Smart Search, navigate to one of the menu items you created and enter a query in the search form or enter a query into one of the instances of Smart Search module. You should be taken to a list of search results if any could be found for the word or phrase you entered. If no results could be found, a message will be displayed indicating that no results could be found. If no results could be found and the system has a search suggestion based on your term, the suggested search phrase will display above the message indicating no results could be found.

==Finalizing the Switch==
To finalize the switch to Smart Search, you should remove all instances of mod_search and all menu items linking to com_search. Smart Search does not interact with the old Joomla search system and exposing both systems may create a negative user experience by giving inconsistent and confusing search results.

==Removing Joomla Search Modules==
If you have the old Joomla search still available then you will probably want to remove it once you have Smart Search running correctly. To remove old Joomla search modules, use the following procedure:

# Log in to the Administrator.
# Click on the desired menu under the Menus menu item.
# Filter the modules listed so that only search modules are shown by selecting "Search" from the "Select Type" filter drop-down. If no such modules are listed then there are no instances of the old search available and you can skip this part.
# Select the checkbox at the top of the table to select all of the items in the list. Once all the instances of the old search have been selected, press the Delete button in the Module Manager toolbar. Be careful that you do not accidentally delete any other modules in the process.

==Removing Joomla Search Menu Items==
Unfortunately, there is no quick and easy way to remove all links to the old Joomla search system. To remove all the menu items to the old Joomla search system you will have to browse the menu items in each of your site's menus and manually remove the links. To make this process somewhat quicker, adjust the order of the table to list menu items by type in reverse alphabetical order. Now scroll down and look for links with type "Search >> Search". Delete those menu items by checking the checkbox to the left of the title and then pressing the Delete button in the Menu Manager toolbar.

[[Category:Smart Search]]

Creating a Smart Search plug-in

2023-02-19T15:41:49Z

Cmb: Some changes for Word2Watch compliance and other markup changes.

<noinclude><languages /></noinclude> <translate>

Smart Search Plugins are gathered together for convenience into a Plugin group called "finder". Take a look in the ''plugins/finder'' directory and you will see the Plugins that support the core Joomla content types. It is best to create your own Plugin by taking a copy of one of these Plugins and adapting it to meet your needs.


All Smart Search Plugins extend the ''FinderIndexerAdapter'' class which contains many methods to deal with maintaining the index. For most of custom content requirements you only need to override a few of these methods.


There is [https://magazine.joomla.org/issues/issue-feb-2012/item/671-Developing-a-Smart-Search-Plugin some additional information] on writing a Smart Search Plugin.

==The Principal Properties== 
Before looking at the methods, there are a few properties that need to be set up correctly:
* $context
*: This should be a unique identifier for the Plugin and establishes the context that the Plugin will respond to (e.g. "Content").
* $extension
*: The name of the extension (component) that handles the content type (e.g. "com_content").
* $layout
*: The sublayout to use when rendering search results. For example, of $layout is set to "article" then the default view will look for a layout file called ''default_article.php'' when it needs to render a search result of this type. If no such file is found then the layout file called ''default_result.php'' will be used instead.
* $table
*: The name of the table to retrieve data from (e.g. "#__content").
* $state_field
*: The database field in your table that the published state of an item is stored in. Defaults to "state".

==The Principal Methods== 
The first methods you will want to override when developing a new Smart Search Plugin are the ''setup'', ''index'' and ''getListQuery'' methods. In the majority of cases those three methods will be enough to get your content indexed, although the Plugin will not be complete as there are other methods that must be implemented to deal with issues such as updating the index when the content changes. But those three methods are the working core of the Plugin.
* setup
*: This method is called by the indexer once before an indexing run begins. It can be used to load libraries or initialise variables for the Plugin. Must return true.
* index
*: This is the main method called by the indexer. It is called once for each content item that is to be indexed (or the index updated). The index method essentially describes the content to the indexer by telling the indexer which fields to parse for terms/phrases and their relative weights, which fields to map into branches of the content map and what data to include in the index as "payload". This method is described in more detail later.
* getListQuery
*: This method must return a JDatabaseQuery object that will form the basis of a query that will return a list of objects of the given content type. There are constraints on this query to ensure that it is compatible with other methods used by the indexer. This method is described in more detail later.

==Some Other Methods== 
For a complete Smart Search Plugin there are other methods you may need to override.


* translateState
*: Given a content item this method translates the native state of the content item into a state that the indexer can use. It must return an integer 0 if the content item is not to appear in search results, or an integer 1 if the content item can appear in search results.
* getURL
*: Returns the non-SEF URL for an item. The default return, using ''plg_finder_content'' for example, is ''index.php?option=com_content&view=article&id=1''.
* getStateQuery
*: This method is used to build a generic query for checking the access and state of items and their parent categories. This method uses the ''$table'' and ''$state_field'' properties to select the correct data.

==Event Methods== 
The following methods are called via the Smart Search content Plugin in response to specific trigger events in Joomla.
* onFinderBeforeSave
*: Called in response to an onContentBeforeSave event.
* onFinderAfterSave
*: Called in response to an onContentAfterSave event.
* onFinderAfterDelete
*: Called in response to an onContentDelete event.
* onFinderChangeState
*: Called in response to an onContentChangeState event.
* onFinderCategoryChangeState
*: Called in response to an onCategoryChangeState event.

==Methods in More Detail== 

===getListQuery=== 
This method must return a JDatabaseQuery object that will form the basis of a query that will return a list of objects of the given content type. There are constraints on this query to ensure that it is compatible with other methods used by the indexer. If the following conditions are not true you will need to override other methods in the FinderIndexerAdapter class.
* The primary database table that is being indexed must have an alias of "a".<ref>If this condition is not true you will also have to override the getItem, getUpdateQueryByTime and getUpdateQueryByIds methods</ref>

===Index=== 
This method is called whenever a content item needs to be indexed (or re-indexed). It is passed an object of type FinderIndexerResult and its purpose is to make adjustments to that object and to add metadata before handing control to FinderIndexer::index method to do the indexing proper.

===Setup=== 
This method is called prior to the index method and is used to set up the index process. This method is where you would typically include any externally-required classes to allow for proper indexing.

==FinderIndexerResult Properties== 
* url
* route
* title
* description
* published
* state
* access
* language
* publish_start_date
* publish_end_date
* extension (only used in core for com_categories plugin)

==Testing== 
Testing a finder plugin can be difficult due to the fact that it is typically run using an Ajax process, so you don't tend to actually see any results from the process.


As such, one way to test is to use the command line indexer.<ref>[http://docs.joomla.org/Setting_up_automatic_Smart_Search_indexing Setting up automatic Smart Search Indexing]</ref>


Open a command prompt/SSH session on the server and go to the root directory of the website.
From there, you can run the indexer and errors and log messages will go to the screen.
''php cli/finder_indexer.php''

==Notes== 
<references/>
</translate>
[[Category:Smart Search]]
[[Category:Plugin Development]]

Planning Migration - Joomla 1.5 to 4

2023-02-18T18:12:47Z

Cmb: Some markup and phrasing changes.

<noinclude><languages /></noinclude>
<translate>

Going from Joomla! 1.5 to 4.x is considered a major migration. This means that considerable changes in how Joomla works, tables, technology have occurred that require a migration instead of an upgrade or update. Both Joomla core extensions and any third-party extensions will need to migrate to Joomla 4.x. This includes the site template. Every single thing needs to be looked at, planned, decided upon, and executed. You will need to be diligent with staying organized throughout the process.

== Intro == 


The fabulous thing about migration is that it is a great time to reassess goals, create a new look and feel (template), clean up, and develop other areas/elements of your site. The more organized you can be with your ideas/thoughts/plans, the better. Planning makes execution easier.


Start planning by asking the following questions or doing the tasks listed below. You may have more items to plan for depending on the complexity of your site. Sadly, there is no way we can list every possible scenario.
</translate>
{{dablink|<translate>
You can ask specific questions on the [[jforum:808|Joomla 4.x General Questions/New to Joomla 4.x Forum]].</translate>}}
<translate>
== Planning Action Items == 

=== General === 


# Assess your original site goals. Migration is an opportunity to get back into focus with your goals or change direction.
# Does your server meet the minimum [http://www.joomla.org/about-joomla/technical-requirements.html technical requirements] for Joomla 4? If not, you will need to change hosts. No better time to change hosts than during a migration.
# What kind of development environment will you use? A development environment on your local device? A subdomain or subdirectory on your server? A new server/hosting account due to technical specifications?
</translate>
<translate>
=== Joomla Core === 


# Clean-up your current site. Take a look at your Sections, Categories, and Articles. Sections are converted to higher level categories from Joomla 2.5 on. Is there clean-up that needs to be done so that you don’t migrate unnecessary content? Document what you want to delete. Alternatively, you may want to document what you want to bring over depending on quantity.
# Organize your content on the current site. Do the Categories you have still apply? Document new categories you may want to add in your new site.</translate>
<translate>

# Do you have any articles in the trash? If so, delete them (and any applicable media that may be associated with them if not in use elsewhere on the site). Articles (categories and menu items too) left in the trash can cause duplicate alias issues once migrated.
# The Media Manager: Decide whether you want to bring your entire ''/images'' directory over or just part of it. If your Media Manager has become a disaster, you may decide to bring over specific images via FTP or cPanel instead of migrating the entire directory. In the future, organize folders in the Media Manager so you don’t end up with a big mess.</translate>
<translate>

# If you are using core components like Joomla Contacts, Web Links, or News Feeds, document this as you will need to bring those over.
# Check your menus and determine if you will bring them all over or only specific menus and menu items. Delete any menu items from the trash to prevent duplicate aliases.
# If you redesign or make changes to your site design or navigation, will you have obsolete pages that will require a redirect? Track all URLs that need redirects on a spreadsheet or notepad.</translate>
<translate>

# Did you “hack the core” of your 1.5 site? If so, those changes will not migrate to Joomla 4. You will want to find alternatives to hacking the core in Joomla 4 ([[S:MyLanguage/Understanding Output Overrides|Understanding Output Overrides]], [[S:MyLanguage/Layout Overrides in Joomla|Layout Overrides in Joomla]]).
# Check your User Manager. Are you intending to bring them all over? Is there clean up required? Perhaps Super Users that no longer should have access or spam users that need to be deleted? Are you using some kind of third-party extension to enhance User Profiles? This part needs careful planning especially if the user data changes frequently.
# Are there new features of Joomla that you wish to use, such as Access Control Levels (ACLs), tags, workflows, or custom fields? Start planning for that now. Planning ACLs is cautious business. Being thorough is very important.
</translate>
<translate>
=== Third-party Extensions === 


# Make a list of all third-party extensions in use. This includes components, modules, plugins, languages, and templates. You may copy/paste them from the Manage page into a document for reference if you’d like. A piece of paper and a pen will suffice. Include if these extensions are used heavily, moderately, hardly ever, or not at all.</translate>
<translate>

# Determine whether the third-party extensions you rely on are ready for Joomla 4.
# Determine if you really need all the extensions you are using. Perhaps Joomla 4 has built-in features that could eliminate the third-party extension.
# What about your site template? If you purchased your template from a third-party source, is there a 4.x version released for it? Would you like to continue using it? Is there a migration path published by the developer? Is the new version of it responsive? Is your template a custom template? Or was it heavily customized from a third-party template? For an expansion of Template-based considerations, see [[S:MyLanguage/Template Considerations During Migration|Template Considerations During Migration]].</translate>
<translate>

# If you are changing your template for a new one, will it require any new images? For example, if your current site has a white background and your logo or other images are ''.jpg'' images with a white background, it won’t look very nice against a new template with an off-white or coloured background.</translate>

{{Basic button|Joomla 1.5 to 4.x Step by Step Migration|<translate>
Joomla! 1.5 to 4.x Step by Step Migration</translate>|class=expand}}
<translate>

[[Category:Migration]]
[[Category:Tutorials]]</translate>

How do I use Gmail as my mail server?

2023-02-11T23:04:27Z

Cmb: Several markup changes.

If you have a working Gmail account you can use Gmail as your mail server by setting it in the Global Configuration.

On the server tab set the following:

*Mailer: SMTP
*SMTP Host: smtp.gmail.com
*SMTP Port 465
*SMTP Security: SSL/TLS
*SMTP Authentication: Yes
*Set the next two lines with your information. Use an app-specific password (ASP), described below.
*SMTP Username: your Gmail username
*SMTP Password: the app-specific password (ASP) you generated, described below.

The following are also working combinations:
*SMTP Port 587
*SMTP Security: STARTTLS

*SMTP Port 25
*SMTP Security: STARTTLS

The SSL module does not need to be enabled in Apache.

The OpenSSL extension needs to be enabled in PHP. The details can be found at the [https://www.php.net/manual/en/openssl.installation.php php.net Installation page].

If you are using WAMP on Windows, the ''openssl'' module is not enabled by default and you need to enable it:
# Open the ''php.ini'' file and uncomment the line <code>extension=php_openssl.dll</code> by removing the semicolon ; from the beginning of the line.
# Save the ''php.ini'' file and restart the Apache service.

{{tip|title=Note|Note that if you use 2-step verification in Gmail, add a new password in Settings - Accounts - Change accounts settings - Other Google Account settings - Security - 2-step verification - Manage your application specific passwords.}}

When the new Application-Specific Password (ASP) is presented in groups of four characters separated by spaces, make sure that you do '''not''' enter the spaces into the SMTP password in the mail server settings in Joomla.

* Application Specific Passwords (ASPs): See the Google Support [https://support.google.com/accounts/answer/185833 Sign in with App Passwords] page.
* 2-Step Verification: See the Google Support [https://support.google.com/accounts/answer/185839 Turn on 2-Step Verification] page.

<noinclude>[[Category:FAQ]][[Category:Server configurations]]</noinclude>

How do you report a bug?

2023-02-07T18:44:14Z

Cmb: Some markup changes. Words2Watch corrections.

== Reporting bugs ==

To report a bug in the Joomla! bug trackers, create a tracker item. Once the tracker item is created, the developers will check the validity of it and act accordingly.

=== Register an Account at ''issues.joomla.org'' ===
[https://issues.joomla.org Register]with Github account.

=== Access the Joomla! Development Bug Tracker. ===

*Once registered it will take you to the tracker directly. This tracker contains all issues reported for all supported versions of Joomla!

=== Check to See If the Bug is Already Reported. ===

There will be no filters set by default but you can use the provided search filters to narrow your search. If the issue you are experiencing is not already reported, click on the top-left Button "New Item".

A new screen will display and there, the more information you give, the easier it is for the developers. Fill as many fields as you can.

* [[Priority]] : Use the default "Medium" except if you know the code enough to make another choice.
* PHP : Choose the version you are testing on. You can find this information by clicking the Menu {{rarr|Help,System Info}} in the Administrator Backend of Joomla!.
* Estimated Time : Leave this blank.
* Build : Type here the #SVN number if you know it, or Nightly Build date, or Version used if using a Released version.
* Browser : Self-explanatory.
* Database : The version of MySQL is also available in {{rarr|Help,System Info}}.
* Status : Leave this to "Open".
* Percent Complete : Leave this blank.
* Category : This one is more tricky. Use "Administration" if you do not know better.
* Customer : Use "User" if the issue is in Frontend, "Developer" if the issue concerns an extension you are developing, "Administrator" in other cases.
* Web Server : The version/server type is also available in {{rarr|Help,System Info}}.

=== Provide a Summary ===

Describe in a few words the issues you are having. It is a good idea to use existing tracker items as examples if this is your first time reporting a bug.

Examples:

* Frontend: Warning such and such.
* Backend: Unable to save article when "nameofplugin" is published.

Note: Take care to be descriptive in your summary as this is the first thing the developers will see when they are perusing the tracker for something to fix.

=== Provide Details About the Bug ===

This is the most important part of reporting the bug. Describe here step by step how you got the error you are noticing. Include all of the information that someone will need to re-trace your steps and see the problem. Remember: Your bug will not be fixed unless others can see the problem, so you want to be as clear and detailed as possible. You do not need to know anything about programming to write a great bug report. But if you do understand the code and think you know how to fix the bug, please include this in the report.

The general format should be something like:
# "Here is ''exactly'' what I did."
# "This is what happened."
# "This is what I think should have happened."
# "Other information, possible solution, proposed code patch."

The more details, the better. Also, it is important to reproduce the bug using the sample Joomla! website or with easy, clear instructions for how to set it up. Remember that others will not have access to your site's database, so you will need to be able to tell someone how to see the bug with data that is readily available -- the sample site.

'''Example A'''

; What I did : Started with sample website. Everything was ok. I enabled "nameofplugin". Try to save any article from Backend.
; What happened : I get a blank screen and article is not saved.
; What should have happened : Articles should save correctly.
; Other information : These are the plugins enabled at the same time. SEF is on (or Off). My site is in a sub-folder. I also remark that... etc. Files such and such are the issues IMHO (if you know what you are talking about).

'''Example B'''

; What I did : Navigate to Backend. Click on "menu_name" Menu.
; What happened: Page opened is blank.
; What should have happened : Menu should have opened correctly.
; Other information : Any other menu works OK. etc.

'''Real-Life Example'''
; What I did
: Started with the sample website.
: Added an unpublished article from the Backend, with Section=FAQ, Category=General.
: In the advanced parameters for the article, set Show Title to "No" and Print, PDF, and Email Icons to "Hide".
: Save the article and navigate to Frontend. Login to the Frontend as admin and navigate to the Example Pages -> Category Blog menu item.
; What happened : The newly added article shows but there is no edit icon for the Frontend user to click on.
; What should have happened : The edit icon should show, allowing a Frontend user to edit this article.
; Other information : This only happens with the ''rhuk_milkyway'' template. By changing this code [code proposed] in file [name and hierarchy of file], line(s) #, the issue looks solved on my settings.

=== Add an Attachment to Your Report ===

To better describe the issue or/and propose a fix, you can add attachments to the tracker item you are creating by using the "Browse" buttons at the bottom of the screen.
A screen capture of the page(s) concerned helps a lot. If you can, try to optimise the size of the image through an image editor.
If you know what part(s) of the code base to change, a patch [patches] or a full file where your changes are '''well''' shown will help the developers to solve the problem quicker.

=== Finish and Send in the Report ===

You will receive an email confirming that you posted the tracker item. When someone comments or asks for supplementary details or solves the issue, you will receive a notification email and may reply if needed.

=== Extra Tips and Tricks ===

Well-written bug reports are incredibly helpful. However, there's a certain amount of overhead involved in working with any bug tracking system, so your help in keeping our ticket tracker as useful as possible is appreciated. In particular:

* Do read the [http://docs.joomla.org/FAQs FAQ] to see if your issue might be a well-known question.
* Do search [https://issues.joomla.org the tracker] to see if your issue has already been filed.
* Do ask on [http://forum.joomla.org/index.php/board,199.0.html testing forums] first if you're not sure if what you're seeing is a bug.
* Do write complete, reproducible, specific bug reports. Include as much information as you possibly can, complete with code snippets, test cases, etc. A minimal example that illustrates the bug in a nice small test case is the best possible bug report.
* Don't use the tracker system to ask support questions. Use the [http://forum.joomla.org/ Joomla! forums], or the [irc://irc.freenode.net/joomla #joomla] IRC channel on freenode for that.
* Don't use the trackers to make large-scale feature requests. We like to discuss any big changes to Joomla!'s core on the [http://forum.joomla.org/index.php#6 developers forums] before actually working on them.
* Don't reopen issues that have been marked "not a bug". This mark means that the decision has been made that we can't or won't fix this particular issue. If you're not sure why, please ask on developer forums.
* Don't use the tracker for lengthy discussions, because they're likely to get lost. If a particular tracker item is controversial, please move discussion to [http://forum.joomla.org/index.php#6 developer forums].

== Reporting Security Issues ==

Report security issues to security [at] joomla [dot] org. This is a private list only open to long-time, highly trusted Joomla! developers, and its archives are not publicly readable.

In the event of a confirmed vulnerability in Joomla! itself, we will take the following actions:

* Acknowledge to the reporter that we've received the report and that a fix is forthcoming. We'll give a rough timeline and ask the reporter to keep the issue confidential until we announce it.
* Halt all other development as long as is needed to develop a fix, including patches against the current and two previous releases.
* Determine a go-public date for announcing the vulnerability and the fix. To try to mitigate a possible "arms race" between those applying the patch and those trying to exploit the hole, we will not announce security problems immediately.
* Publicly announce the vulnerability and the fix on the pre-determined go-public date. This will probably mean a new release of Joomla! but in some cases it may simply be patches against current releases.

[[Category:Development]] [[Category:Bug_Squad]]
[[Category:Joomla! Resources]]

Joomla 3.x to 4.x Step by Step Migration

2023-02-06T22:37:04Z

Cmb: Some markup, phrasing and Words2Watch changes.

<noinclude><languages /></noinclude>
{{warning|title=<translate>

Warning!</translate>|<translate>

This guide assumes you are starting on Joomla 3.10.x. If you are on a earlier version make sure you upgrade to Joomla 3.10 first before moving to Joomla 4.


There is no rush. Make sure all your extensions are ready for Joomla 4.x. Joomla 3.10.x will be supported until 16 August 2023.</translate>}}

<translate>

The following are step-by-step instructions to migrate your 3.10.x site to Joomla! 4.x. While there are different scenarios, this will give you the basic procedure to follow. Complex migrations will likely be a result of installed third-party extensions. You are encouraged to contact the developers of third-party extensions installed on your Joomla site for their suggested migration path.
</translate>

<translate>
== Intro == 
The migration from Joomla! 3.10.x to 4.x is considered a mini-migration. This is because the Joomla core extensions will upgrade with a “one-click” upgrade via the Joomla! Update component in the Backend (Administrator) of Joomla. Many third-party extensions are a one-click upgrade too. Some are not. Look at each one and determine what path the extension needs to follow to get from 3.10 to 4.x. If you haven't already, read the [[S:MyLanguage/Migration Step by Step Self Assessment|Self Assessment]] and [[S:MyLanguage/Planning for Mini-Migration - Joomla 3.10.x to 4.x|Planning for 3.10 to 4.x Migration]] prior to following the steps below.</translate>
<translate>

</br>Joomla! Core Extensions are:
* Categories
* Articles
* Menus
* Modules (core modules - not third-party)
* Action Logs
* Banners
* Fields
* Content History
* Contacts
* Messaging
* Newsfeeds
* Redirect
* Search (decoupled in 4.x. Existing 3.x sites will still migrate it. However we recommend using Smart Search going forward. See Notes under Assess Each Extension)
* Smart Search
* Tags
* Weblinks (decoupled but your site may be using it and it will migrate. See Notes under Assess Each Extension.)
</translate>

<translate>
== Step by Step == 
=== Set Up a Development Location ===
</translate>
<translate>

# Make sure you are running the latest Joomla 3.10.x version before proceeding.
# Take a backup of your live 3.10.x site. You can use a suggested tool (see the ''Suggested Tools'' at the bottom of page) or you can do this manually.
#*[[S:MyLanguage/Backup_Basics_for_a_Joomla!_Web_Site|Backup Basics for a Joomla! Web Site]]
#*[[S:MyLanguage/What_are_the_best_practices_for_site_backups%3F|What are the best practices for site backups?]]
# Make sure your environment meets the [https://downloads.joomla.org/technical-requirements technical requirements for Joomla 4].
# Create a new database and new user to restore your 3.10.x site to.
# Create a testing site or build area to work in and restore the backup copy of your 3.10.x site in one of the following places:
#* A subdomain.
#* A subdirectory.
#* A local device. Joomla has a detailed tutorial on installing [https://sourceforge.net/projects/xampp/ XAMPP] at [[XAMPP]]. However [https://www.wampserver.com/en/ WAMP], [https://www.mamp.info/en/windows/ MAMP], [https://sourceforge.net/projects/lampas/ LAMP] are all suitable alternatives.
#* A new hosting account on a temporary domain in the root. (If you would like to change hosts in the process of migration.)
#** Restoring a site on a local device. See [[S:MyLanguage/Installing Joomla locally|Installing Joomla locally]] and [[S:MyLanguage/Setting up your workstation for Joomla development|Setting up your workstation for Joomla development]].
#** Restoring a site with a tool listed at the bottom of the page. (Read the developer documentation.)
# In your test location, update your Joomla! 3.10.x instance to the latest maintenance release.
# Make sure you have the latest database schema updated to the latest version 3.10.x version by going to {{rarr|Extension Manager,Database}} tab. If your schema is not up to date as in the following image, click the '''Fix''' button:</translate>{{-}}[[File:J310-admin-extension-database-fix-<translate>

en</translate>.png|border|800px]]
<translate>

# Empty trash: Do you have any articles in the trash? Delete them (and any associated media if not in use elsewhere on the site). Articles (categories and menu items too) left in the trash can cause migration issues.
# Test.
# Backup again.
</translate>

<translate>
=== Assess Each Extension === 
</translate>
<translate>

In your [[S:MyLanguage/Planning_for_Mini-Migration_-_Joomla_3.10.x_to_4.x|planning]], you determined that third-party extensions were staying or going and how they migrate. For this portion of the Step by Step, you’ll be using two different sections of the site extensively; The Pre-Update Check in {{rarr|Components,Joomla! Update}} and {{rarr|Extensions,Manage,Manage}}. You are going to be looking at every single extension installed on your site. You will be determining if they need to be updated to the latest version or uninstalled. More details in [[Special:MyLanguage/:Pre-Update_Check|Pre-Update Check]].</translate>
<translate>

# Using the '''Pre-Update Check''': in order to use the Pre-Update Check, you will need to set the Joomla! Update component to Joomla 4. To do this follow:
# Go to {{rarr|Components,Joomla Update}}. (It should say no updates found. If it doesn’t, update Joomla to the latest version (must be 3.10.x) and test. Then do another backup.) Click on the Options button at the top right corner.
# Select ''Joomla Next'' from the drop-down for Update Channel.</translate>{{-}}[[File:Migration_J3toJ4_update_channel-<translate> en</translate>.png|border|800px]]{{-}}
<translate>
# Click Save & Close
# You will then see your Installed Joomla Version, the latest Joomla! version and the URL for the update package. Joomla will show you the requirements again for Joomla 4. If it flags that you have either an incompatible system or extensions it will tell you here. Take a moment to review this page.</translate>{{-}}[[File:J310-admin-update_to_4-pre_update_check-<translate> en</translate>.png|border|800px]]<translate>

{{amboxNew|image=notice|style=notice|title={{{title|Important Notice}}}|text='''Do NOT update to Joomla! 4 right now. This is only to prepare your third-party extensions and get the site compatible with Joomla! 4.'''}}
# Look at the Pre-Update Check and the Extension Pre-Update Check in the Pre-Update Check tab of the Joomla Update component. If any extension that isn’t in your planning is listed here, add it to your list of extensions to investigate.
# If you migrated from Joomla! 2.5 to 3.x in the past, there may be some leftover extensions that need to be cleaned up. The following are older 2.5 or 3.x extensions that need to be uninstalled before updating to Joomla 4:
#;* plg_content_geshi
#;* Bluestork Administrator Template
#;* Beez_20
#;* Beez5
#;* Atomic</translate>
<translate> ## When it comes to templates, uninstall all core Frontend or Backend templates except Protostar and Beez3 (site templates) and Isis or Hathor (Administrator templates). '''Note''' Protostar is '''not''' compatible with Joomla 4. Upon migration it will disappear. You'll need to have one template selected as "default" and you can use Protostar or Beez3. Protostar will disappear upon migration to Joomla 4.x.</translate>
<translate> ## If you come across other files that need to be uninstalled, please add them to this page. This is a wiki so anyone can add to the page. Thank you in advance for your service.</translate>
<translate> # You will notice the tags for whether an extension is compatible or not. These tags generally tell a true story if they say No or Yes. If they say “Missing Compatibility Tag” it means that the extension developer didn’t use a tag in their extension so we don’t know if it is or isn’t compatible with Joomla 4. Talk to the developer to verify.</translate>
<translate> # '''Update Extensions''': update any extensions that you will keep in your website. In Joomla! 3.10.x you can go to {{rarr|Extension Manager,Update tab}} and click '''Find Updates''' that will add a tooltip in the Version column, under the Manage tab, giving some compatibility information from the Backend. This functionality only supports extensions that update via the Extension Manager Update tab. If you have extensions installed that do not use the Joomla extension update they need to be assessed manually as detailed below. The same goes for those extensions that have a tooltip. You will still need to check the type of package and migration path with the extension developer to verify how to upgrade/migrate.</translate>
<translate>
# Investigate and Uninstall Extensions Extensions: go to {{rarr|Extension Manager,Manage}}
# Click the Button ''Search Tools'' to show the filter options
# Select Package from the ''Select Type'' drop-down.</translate>{{-}}[[File:J310-admin-extension-manage-package-<translate>

en</translate>.png|800px]]{{-}}{{note|<translate>

Selecting Package first is recommended because if there is something you need to uninstall in a package, it will automatically uninstall the associated Modules, Plugins, or anything else in the package at one time.</translate>}}
<translate>

# Uninstall any Packages that are no longer needed or will not be migrating to Joomla 4.
# Repeat this process of going through the Manage tab for all Types in the drop-down: Component, File, Language, Library, Module, Plugin and Template. If the Author states Joomla! Project, then leave those extensions alone. For all others, make sure that you uninstall those not in use or not compatible with Joomla! 4.x.</translate>{{-}}{{note|<translate>

'''NOTE!''' You will not be able to uninstall any template that is set as default. Select a Core supported template such as Beez3 or Protostar and then uninstall the template if you need to do so. <br />''Another reminder:'' '''Protostar is not compatible with Joomla 4.x'''. Upon migration it will disappear. Selecting it as default simply gets you to Joomla 4.x.</translate>|type=serious}}
<translate>

# Make a note of any versions of Packages and Components currently running that you will be keeping on your site. You can copy/paste them into a document for reference.</translate>
<translate> # For any extensions you are keeping but don't use the Extension Manager to one-click update ({{rarr|Extensions,Manage,Update}}) update all extensions to the latest versions.</translate>
<translate> # Before and as you update, note if the extensions have both 3.10.x & 4.x versions in the same package. If so, they will be fine to "one-click update." If not, and 3.10 and 4.x have different packages, look at them case by case. They will normally fall into one of the following scenarios:</translate>
<translate> #* The extension has separate packages but upon upgrading to 4.x, they automatically detect this and still work. Make sure the developer confirms this.</translate>
<translate> #* The extension has separate packages that need to be uninstalled in 3.10.x and then installed with the Joomla 4.x version once the site is migrated. An example of this might be a content plugin. It is simple to uninstall it in 3.10.x and then install it again in 4.x.</translate>
<translate> #* See [[S:MyLanguage/Template_Considerations_During_Migration|Template Considerations]] for more specific information on templates and [[S:MyLanguage/J3.x:Converting_A_Previous_Joomla!_Version_Template|Converting a previous Joomla! Version template]]</translate>

<translate>
==== Notes on Search (com_search) ==== 
Search (com_search) will be decoupled in Joomla 4.x. Search (com_search) will migrate to Joomla 4. After migration, you'll need to update it to the Joomla 4.x version via com_installer. It will continue to be maintained, but more the same way a third-party extension is by receiving updates via com_installer. It is recommended to use Smart Search (com_finder) going forward. Search will still be available at https://extensions.joomla.org/category/official-extensions/.</translate>

<translate>
==== Notes on Weblinks ==== 
Weblinks was decoupled back in Joomla 3.4. If it was in use on a 2.5 site, the migration process would note this and migrate the Weblinks component and data. For the migration from 3.10.x to 4.x, it will be the same. It is still available and maintained on the JED at [https://extensions.joomla.org/category/official-extensions/ Official Extensions].</translate>

<translate>
==== Notes on Legacy Routing ====  </translate>
<translate> Legacy routing will not be available in Joomla 4.x. Only Modern will be available. When you do the migration, if you are using Legacy routing, the system will automatically change them to Modern routing. You will want to run a broken link checker on your site after migrating to Joomla 4.x and ''before you go live''.</translate>

<translate>
=== Going to Joomla! 4.x === 
Once you have either updated or uninstalled your third-party extensions so that only those compatible with Joomla! 4 remain in your installation, continue with the following steps:
</translate>
<translate>

# Go to {{rarr|System,Global Configuration,Server tab}} and turn Error Reporting from System Default to Maximum. Make sure to Save & Close.</translate>{{-}} [[File:J310-system-global-config-server-tab-<translate>

en</translate>.png|border|500px]]
<translate>

# Take another backup.
# Go to {{rarr|Components,Joomla Update}}. (It should say no updates found. If it doesn’t, update Joomla to the latest version and test. Then do another backup.) Click on the Options button at the top right corner.
# Select ''Joomla Next'' from the drop-down for Update Channel.</translate>{{-}}[[File:J310-component-joomla-update-select-support-<translate>

en</translate>.png|border|500px]]
<translate>

# Click Save & Close.
# You will then see your Installed Joomla Version, the Latest Joomla! version and the URL for the update package. Joomla will show you the requirements again for Joomla 4. If it flags that you have either an incompatible system or extensions it will tell you here. Take a moment to review this page.</translate>{{-}}[[File:J310-to-j4-dev-update-found-<translate>

en</translate>.png|border|800px]]
<translate>

# If the update is not showing up, go to {{rarr|Extension manager,Update}} and press Purge Cache from the toolbar. Now the update to Joomla! 4 should show up.</translate>
<translate> # Cross your fingers, and make sure you have that backup available in case.</translate>
<translate> # Click the Install the Update button.</translate>
<translate> # Make tea whilst the status bar loads to fully green. The amount of time this takes is dependent on your site, Internet connection and server speed. The process takes about two minutes. When the update is finished, you will probably be logged out of the Administrator. Sign in again. Twice.</translate>
<translate> # If all goes well, you will get to a totally new look to the Backend panel.</translate>{{-}}[[File:j4-administrator-overview-<translate>

en</translate>.png|border|800px]]
<translate> # Go to {{rarr|System,Maintenance,Database}} and click ''Fix'' if any errors show.</translate>
<translate> # In {{rarr|System,Install,Discover}} see if there are any extensions to install. (There shouldn't be any!)</translate>
<translate> # Go to the Frontend of your site and see if it shows up even if it’s not the right template. If so, continue. If not, see [[S:MyLanguage/Joomla 3.10 to 4.x Common Migration Errors|common errors during migration]].</translate>
<translate> # Take a backup.</translate>
<translate> # Install your new template or other extensions if you have them to install. Back up often.</translate>
<translate> # Configure them. Back up often.</translate>
<translate> # Run a broken link checker and fix any broken links.</translate>
<translate> # Test everything. Back up often.</translate>
<translate>
# If everything works as expected, turn Error Reporting back to System Default ({{rarr|System,Global Configuration,Server tab}}). Make sure to Save & Close.
</translate>

<translate>
=== Going Live with Your Joomla! 4.x Site === 
# When you’re ready to go live, back up your 3.10 site for the last time. Restore it in a subdirectory or subdomain if you would like to.
# Back up your Joomla! 4.x site and move or restore your Joomla! 4.x site to the root (or change nameservers if you were building on a temporary domain at a new hosting account root).
# Test again.
# '''If''' you have made security changes to ''.htaccess'' file in the past, you may need to change a line (or lines) in it to update to Joomla 4. Please go to [https://docs.joomla.org/Htaccess_changes_after_joomla4.0.4 Htaccess changes after joomla4.0.4] to determine if you need to change your file.
# Remove the Joomla! 3.10 site from the server within a couple of days unless you have edited your ''robots.txt'' file to block the search engine spiders and disabled the Frontend of the site.
# Remove all development sites you have been working with or keep them up-to-date if they are running a current version in order to ward off hack attempts on your server. </translate>

<translate>

If you had data change on the 3.10 site while you were migrating to 4.x, you will want to get that data moved over to the 4.x site before going live. You can do this manually (make sure you keep the same user IDs - go in order) or by using a [https://extensions.joomla.org/category/migration-a-conversion/data-import-a-export%20transfer%20tool/third-party%20extension/ third party extension].
</translate>

<translate>
== Suggested Tools == </translate>
<translate>
* [http://extensions.joomla.org/extensions/access-a-security/site-security/backup/1606 Akeeba Backup] is popular for backup and restore. See more [https://extensions.joomla.org/tags/backup/ backup tools].
</translate>
<translate>
==Related information==  </translate>
[[Special:MyLanguage/:Pre-Update_Check|<translate> Pre-Update_Check</translate>]]
<noinclude>
<translate>

[[Category:Migration{{#translation:}}]]
[[Category:Tutorials{{#translation:}}]]
[[Category:Joomla! 4.x{{#translation:}}]]
</translate></noinclude>