J4.x:Web Assets/ru

2022-01-04T11:00:40Z

Dzandut: Created page with "Связанные ресурсы определены в файле JSON, например [https://github.com/joomla/joomla-cms/blob/7b72c565b610e02c1b01f8958d622879631fa6a2..."

<noinclude><languages /></noinclude>
== Концепция ==

Во внешнем интерфейсе многие активы ("assets") связаны. Например, наш скрипт keepalive зависит от файла core.js для управления параметрами. В Joomla никогда не было простого способа указать это, нужно было просто включить несколько файлов. Joomla 4 меняет это понятие с помощью концепции веб-ресурсов.

== Определение ==

Связанные ресурсы определены в файле JSON, например [https://github.com/joomla/joomla-cms/blob/7b72c565b610e02c1b01f8958d622879631fa6a2/build/media_source/system/joomla.asset.json#L14-L21 system/joomla.asset.json#L14-L21]

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 js 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:

<source 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"
}
}
]
}
</source>

The <source lang="json" inline>$schema</source> 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.

'''Note:''' Having joomla.asset.json for your extension or template are recommend but not required to WebAssset to work (see next section).

'''Note:''' It is not recommended to add an inline asset to a json file, prefer to use a file.

== Explaining asset stages ==

Each asset has 2 stages: registered and used.

'''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.

'''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.

An asset cannot be used if it was not registered before, this will cause an unknown asset exception.

== Register an asset ==

All known assets loaded and then stored in '''WebAssetRegistry''' (to enable/disable an asset item you have to use '''WebAssetManager''', see next section).

Joomla! will look for next assets definition automatically at runtime (in following order):
<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>

And load them to registry of known assets.

'''Note:''' Each following assets definition will override asset items from previous assets definition, by item name.

You can register your own assets definition via '''WebAssetRegistry''':

<source 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');
</source>

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

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

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.

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

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

To enable an asset in the page use the useAsset function, for example:

<source 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']);
</source>

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

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

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

'''Note:''' If there are any dependencies to the disabled asset, then this asset will be re-enabled automatically, no matter what.

To check whether asset enabled, and the asset state:

<source 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!');
}
</source>

== Overriding an asset ==

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.
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:

How it defined in the system initially:

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

To override the URI we define the asset item with "foobar" name in our joomla.asset.json:

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

Or, register new asset item with AssetManager:

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

== Working with styles ==

AssetManager allow to manage Stylesheet files. Stylesheet asset item have a type "style".

Example json definition of item in joomla.asset.json:

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

=== Methods to work with styles ===

AssetManager offers the following methods to work with style files:

<source 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']);
</source>

=== Add inline style ===

Additionaly 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.

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.

<source 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']);
</source>

'''Note:''' "foobar" asset should exist in the asset registry, otherwise you will get an unsatisfied dependency exception.

Example above will produce:

<source 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>
...
</source>

If inline asset has multiple dependencies, then will be used last one for positioning. Example:

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

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

'''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.

== Working with scripts ==

AssetManager allow to manage Script files. Script asset item have a type "script".
Example json definition of item in joomla.asset.json:
<source lang="json">
...
{
"name": "foobar",
"type": "script",
"uri": "com_example/foobar.js",
"dependencies": ["core"]
}
...
</source>

Example json definition of ES6 module script, with fallback to legacy:

<source 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"
]
}
...
</source>

=== Methods to work with scripts ===

AssetManager offer next methods to work with script files:

<source 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']);
</source>

=== Add inline script ===

Addittionaly 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.

Inline asset may have a name as well as other assets (but not required), the name can be used to retrive the asset item form a registry, or as dependecy to another inline asset. If name not specified then will be used generated name based on a content hash.

<source 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']);
</source>

'''Note:''' "foobar" asset should exist in the asset registry, otherwise you will get an unsatisfied dependency exception.

Example above will produce:

<source 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>
...
</source>

If inline asset have a multiple dependencies, then will be used last one for positioning. Example:

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

Will produce:

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

'''Note:''' Named inline asset may be as dependency to another inline asset, hovewer it is not recomended 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.

== Working with a web component ==

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.

Example json definition of some web components in joomla.asset.json (as ES6 module):

<source 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"
},
}
...
</source>

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:

<source 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"
]
}
...
</source>

Alternatively you can register them in PHP (as ES6 module):

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

Attach to document:

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

'''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.

=== Methods to work with web component ===

All methods to work with a web component are the same as methods to work with script asset item.

== Working with a presets ==

"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.

Example json definition of item in joomla.asset.json:

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

=== Methods to work with preset ===

AssetManager offer next methods to work with preset items:

<source 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']);
</source>

== Advanced: Custom WebAssetItem class ==

The default class for all WebAsset items is '''Joomla\CMS\WebAsset\WebAssetItem'''.

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

A custom class can allow you to do advanced actions, for example, including a script file depending on an active language:

<source 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;
}
}
</source>

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.

<source 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]);
}
}
</source>

'''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.

=== Defining a custom WebAssetItem class in joomla.asset.json ===

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:

<source 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"
}
]
}
</source>

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

'''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:

<source 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"
}
]
}
</source>

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

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

2022-01-04T10:57:11Z

Во внешнем интерфейсе многие активы связаны. Например, наш скрипт keepalive зависит от файла core.js для управления параметрами. В Joomla никогда не было простого способа указать это, нужно было просто включить несколько файлов. Joomla 4 меняет это понятие с помощью концепции веб-ресурсов.

J4.x:Web Assets/ru

2022-01-04T10:51:52Z

Dzandut: Created page with "== Концепция =="

<noinclude><languages /></noinclude>
== Концепция ==

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.

== Definition ==

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]

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 js 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:

<source 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"
}
}
]
}
</source>

The <source lang="json" inline>$schema</source> 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.

'''Note:''' Having joomla.asset.json for your extension or template are recommend but not required to WebAssset to work (see next section).

'''Note:''' It is not recommended to add an inline asset to a json file, prefer to use a file.

== Explaining asset stages ==

Each asset has 2 stages: registered and used.

'''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.

'''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.

An asset cannot be used if it was not registered before, this will cause an unknown asset exception.

== Register an asset ==

All known assets loaded and then stored in '''WebAssetRegistry''' (to enable/disable an asset item you have to use '''WebAssetManager''', see next section).

Joomla! will look for next assets definition automatically at runtime (in following order):
<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>

And load them to registry of known assets.

'''Note:''' Each following assets definition will override asset items from previous assets definition, by item name.

You can register your own assets definition via '''WebAssetRegistry''':

<source 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');
</source>

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

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

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.

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

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

To enable an asset in the page use the useAsset function, for example:

<source 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']);
</source>

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

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

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

'''Note:''' If there are any dependencies to the disabled asset, then this asset will be re-enabled automatically, no matter what.

To check whether asset enabled, and the asset state:

<source 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!');
}
</source>

== Overriding an asset ==

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.
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:

How it defined in the system initially:

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

To override the URI we define the asset item with "foobar" name in our joomla.asset.json:

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

Or, register new asset item with AssetManager:

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

== Working with styles ==

AssetManager allow to manage Stylesheet files. Stylesheet asset item have a type "style".

Example json definition of item in joomla.asset.json:

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

=== Methods to work with styles ===

AssetManager offers the following methods to work with style files:

<source 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']);
</source>

=== Add inline style ===

Additionaly 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.

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.

<source 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']);
</source>

'''Note:''' "foobar" asset should exist in the asset registry, otherwise you will get an unsatisfied dependency exception.

Example above will produce:

<source 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>
...
</source>

If inline asset has multiple dependencies, then will be used last one for positioning. Example:

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

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

'''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.

== Working with scripts ==

AssetManager allow to manage Script files. Script asset item have a type "script".
Example json definition of item in joomla.asset.json:
<source lang="json">
...
{
"name": "foobar",
"type": "script",
"uri": "com_example/foobar.js",
"dependencies": ["core"]
}
...
</source>

Example json definition of ES6 module script, with fallback to legacy:

<source 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"
]
}
...
</source>

=== Methods to work with scripts ===

AssetManager offer next methods to work with script files:

<source 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']);
</source>

=== Add inline script ===

Addittionaly 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.

Inline asset may have a name as well as other assets (but not required), the name can be used to retrive the asset item form a registry, or as dependecy to another inline asset. If name not specified then will be used generated name based on a content hash.

<source 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']);
</source>

'''Note:''' "foobar" asset should exist in the asset registry, otherwise you will get an unsatisfied dependency exception.

Example above will produce:

<source 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>
...
</source>

If inline asset have a multiple dependencies, then will be used last one for positioning. Example:

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

Will produce:

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

'''Note:''' Named inline asset may be as dependency to another inline asset, hovewer it is not recomended 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.

== Working with a web component ==

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.

Example json definition of some web components in joomla.asset.json (as ES6 module):

<source 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"
},
}
...
</source>

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:

<source 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"
]
}
...
</source>

Alternatively you can register them in PHP (as ES6 module):

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

Attach to document:

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

'''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.

=== Methods to work with web component ===

All methods to work with a web component are the same as methods to work with script asset item.

== Working with a presets ==

"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.

Example json definition of item in joomla.asset.json:

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

=== Methods to work with preset ===

AssetManager offer next methods to work with preset items:

<source 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']);
</source>

== Advanced: Custom WebAssetItem class ==

The default class for all WebAsset items is '''Joomla\CMS\WebAsset\WebAssetItem'''.

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

A custom class can allow you to do advanced actions, for example, including a script file depending on an active language:

<source 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;
}
}
</source>

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.

<source 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]);
}
}
</source>

'''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.

=== Defining a custom WebAssetItem class in joomla.asset.json ===

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:

<source 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"
}
]
}
</source>

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

'''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:

<source 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"
}
]
}
</source>

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

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

Translations:J4.x:Web Assets/114/ru

2022-01-04T10:51:47Z

Dzandut: Created page with "== Концепция =="

== Концепция ==

Category:Joomla! 4.x/ru

2022-01-03T16:18:21Z

Dzandut: Created page with "Чтобы появиться в этой категории, на каждой странице темы в конце должен быть вставлен следующи..."

<noinclude><languages /></noinclude>

{{Joomla version|version=4.x|status=future|comment=series}}

This page contains articles related to Joomla! version 4.x.

Чтобы появиться в этой категории, на каждой странице темы в конце должен быть вставлен следующий код:

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

Translations:Category:Joomla! 4.x/3/ru

2022-01-03T16:18:21Z

Чтобы появиться в этой категории, на каждой странице темы в конце должен быть вставлен следующий код:

JDOC:Joomla 4 Tutorials Project/ru

2022-01-03T16:15:05Z

Dzandut: Created page with "Это '''Joomla! Документация Wiki Tutorial Project''' ориентирована на предоставление учебных пособий, чтобы по..."

<noinclude><languages /></noinclude>
{{Top portal heading|color=white-bkgd|icon=joomla|icon-color=#5091cd|size=5x|text-color=#333|title=Joomla 4 Tutorials Project}}
Это '''Joomla! Документация Wiki Tutorial Project''' ориентирована на предоставление учебных пособий, чтобы помочь новичкам и разработчикам с основными изменениями Joomla 4. Joomla Docs Wiki создается и поддерживается сообществом, любой может принять участие в Joomla 4 Tutorials Project! В этом проекте JDOC есть много небольших задач, которые в сочетании друг с другом помогут создать высококачественные учебные пособия для начинающих и средних разработчиков Joomla!. Покажите другим свой интерес к проекту Joomla, зарегистрируйтесь, чтобы помочь с этим проектом Docs Wiki на странице обсуждения.
<div class="large-6 column">
{{section portal heading|icon=magic|title=Joomla 4 Tutorials Maintained}}

== For Newcomers ==
* [[S:MyLanguage/J4.x:Getting_Started_with_Joomla!|Getting Started with Joomla!]]

== For Upgraders ==

* [[S:MyLanguage/Potential backward compatibility issues in Joomla 4|Potential backward compatibility issues in Joomla 4]]
* [[S:MyLanguage/Joomla_3.x_to_4.x_Step_by_Step_Migration|Joomla 3.x to 4.x Step by Step Migration]]

== For Maintainers ==

* [[S:MyLanguage/J4.x:Adding_a_menu_link_in_an_article|Adding a menu link in an article]]
* [[S:MyLanguage/J4.x:Adding_a_Custom_Administrator_Menu| Adding a Custom Administrator Menu]]
* [[S:MyLanguage/J4.x:Workflow|Workflow]]
* [[S:MyLanguage/J4.x:Http_Header_Management|How to Use the New HTTP Header Management]]
* [[S:MyLanguage/J4.x:CLI_Database_Exporter_Importer|CLI Database Exporter Importer]]
* [[S:MyLanguage/J4.x:Improved_Override_Management|Improved Override Management]]
* [[S:MyLanguage/J4.x:Media_Manager|The New Media Manager in Joomla 4.0]]
** [[S:MyLanguage/J4.x:How_to_use_the_new_Media_Manager|How to use the new media manager in Joomla 4.0]]
* [[S:MyLanguage/J4.x:Using Bootstrap Components in Joomla 4|Using Bootstrap Components in Joomla 4]]

== For Developers ==

* [[S:MyLanguage/J4.x:Creating_a_Plugin_for_Joomla|Creating a Plugin for Joomla 4]]
* [[S:MyLanguage/J4.x:Creating_a_Simple_Module| Creating a simple Module for Joomla 4]]
* [[S:MyLanguage/J4.x:SCSS_and_Sass|SCSS and Sass]]
* [[S:MyLanguage/J4.x:Setting_Up_Your_Local_Environment|Setting up your local environment]]
* [[S:MyLanguage/Setting_up_Eclipse_PDT_2020_and_Git_for_Pulls|Setting up Eclipse PDT 2020 and Git for Pulls]]
* [[S:MyLanguage/J4.x:Web_Assets|Web Assets]]
* [[S:MyLanguage/Adding changelog to your manifest file|Adding changelog to your manifest file]]
* [[S:MyLanguage/J4.x:Dependency_Injection_in_Joomla_4|Dependency Injection in Joomla 4]]
* [[S:MyLanguage/J4.x:Moving_Joomla_To_Prepared_Statements|Moving Joomla to Prepared Statements]]
* [[S:MyLanguage/J4.x:Namespace_Conventions_In_Joomla|Namespace conventions in Joomla 4]]
* [[S:MyLanguage/J4.x:Writing_A_CLI_Application|Writing a CLI Application with the new Console Package]]
** [[S:MyLanguage/J4.x:Cloud_File_Systems_for_Media_Manager|How to build a cloud file system plugin for the new Media Manager]]
* Joomla 4's API: There are several pages documentation which you can find linked [[S:MyLanguage/Category:Joomla!_Api|in this Category on the Wiki]]

== For Documenters ==

* [[S:MyLanguage/Help4.x:Help_screens|Joomla 4 Help Screens]]
* [[S:MyLanguage/Help4.x:Chunks| Joomla 4 Chunks]]
* [[S:MyLanguage/J4.x:Doc_Pages| Joomla 4 Doc Pages]]
* [[S:MyLanguage/J4.x:Help_pages| Joomla 4 Help Pages]]
* [[S:MyLanguage/J3.x:Doc_Pages| Joomla 3 Doc Pages]] (for comparison)
== Appendices ==

=====Joomla 4.x Extensions - Simple working examples explained=====

* [[S:MyLanguage/J4 Plugin example - Table of Contents|J4 Plugin example - Table of Contents]]
* [[S:MyLanguage/J4 Component example - Mywalks|J4 Component example - Mywalks]] - Updated for Beta 4
* [[S:MyLanguage/J4 Module example - Mydownmsg|J4 Module example - Mydownmsg]]
* [[S:MyLanguage/J4 CLI example - Onoffbydate|J4 CLI example - Onoffbydate]]

* [[J4.x:Tips and Tricks for Joomla 4 Developers|Tips and Tricks for Joomla 4 Developers]]

</div>
<div class="large-6 column">
{{section portal heading|icon=check-square|title=To Do List}}
These are a few 'to do's' to get this project startedː
* How to use the new Publishing Workflow
* How to create an accessible template
* How to test the accessibility of an extension
* [[S:MyLanguage/J4.x:Developing_an_MVC_Component|Developing an MVC component]]
* Joomla! 4 Component Development Tutorial
* Cassiopeia Template - Front End Template for Joomla 4
* Atum Template - Back End Template for Joomla 4
* HTML Mail Templates
* What's changed in Joomla 4? (vs backwards compatibility)
* Custom Admin User Dashboards
* Plugin: System - Additional Accessibility Features
* Upgrading Joomla 4: Pre Update Check
* Making a language pack for Joomla 4 ([[J3.x:Making a Language Pack for Joomla|J3 version]])
</div>
<div class="large-12 column">{{section portal heading|icon=plus|title=Join This JDOC Project}}{{JDOC:Beginners_Tutorial_Project/Get Involved/en}}
</div>
<div class="large-6 column">
{{section portal heading|icon=question|title=FAQ}}{{JDOC:Developer_Tutorials_Project/FAQs/en}}
</div>
<div class="large-6 column">
{{section portal heading|icon=group|title=Members of this Project}}
==Members==
*[[User:Sandra97|Sandra Decoux]]
*[[User:Hutchy68|Tom Hutchison]]
*[[User:MartijnM|Martijn Maandag]]
*[[User:M-b-o|Mike Brandner, Teamlead JDocs]]
*[[User:Wilsonge|George Wilson, Joomla 4 Release Lead]]
*[[User:Partic|Patrick Jackson]]
{{section portal heading|icon=book|title=News}}
The JDOC Joomla 4 Tutorials Project was started on Sat, 08 Dec 2018 in an effort to benefit the users of the Joomla! Documentation Wiki.
</div>

__NOTOC__
<noinclude>
[[Category:JDOC Projects{{#translation:}}]]
[[Category:Joomla!_4.x{{#translation:}}]]
</noinclude>
__NOEDITSECTION__

2021-11-17T14:35:29Z

Языковые пакеты - это расширения, которые обеспечивают перевод для Joomla!. Joomla! 1.5 и выше поддерживает полный перевод сайта и интерфейса администратора. Из-за этого существует два основных типа языковых пакетов: для сайта и для администратора, с Joomla! 1.5.4 и выше поддерживаются языковые пакеты для сайта и администратора в одном пакете

Language/ru

2021-11-17T14:31:47Z

Dzandut: Created page with "Язык"

<noinclude><languages /></noinclude>
{{Chunk:Language/en}}

Language packs are extensions that provide translations for the Joomla! system. Joomla! 1.5 and higher supports a full translateable site and administrator interface. Because of this there are two major types of language packs, ones for the site and ones for the administrator, with Joomla! 1.5.4 and higher supporting language packs with both the site and administrator in the one pack <ref name="154langinstaller">[http://www.joomla.org/content/view/5180/1/1/1/#Language_Installation_Improvemen Joomla! 1.5.4 release announcement]</ref>.
<noinclude>== References ==
<references/>
[[Category:Extensions| Language]]
[[Category:Landing Pages]]
[[Category:Glossary]]
</noinclude>

Translations:Language/Page display title/ru

2021-11-17T14:31:46Z

Dzandut: Created page with "Язык"

Язык

J4.x:Creating a Simple Module/ru

2021-11-17T14:28:57Z

Dzandut: Created page with "Более подробную информацию о языковых файлах можно найти here."

<noinclude><languages /></noinclude>
{{Joomla version|version=4.x|comment=>Tutorial}}
{{-}}
{{Top portal heading|color=white-bkgd|icon=file-code-o|icon-color=#5091cd|size=5x|text-color=#333|title=Creating a Simple Module for Joomla 4.x}}
{{-}}

This is a tutorial on how to Create a simple module for Joomla Version 4x.
== Introduction ==
Joomlaǃ 4 provides five types of extensionsː
* '''[[S:MyLanguage/Component|Components]]'''<br />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.
* '''[[S:MyLanguage/Module|Modules]]''' <br />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.
* '''[[S:MyLanguage/Plugin|Plugins]]'''<br />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.
* '''[[S:MyLanguage/Languages|Languages]]'''<br />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.
* '''[[S:MyLanguage/Templates|Templates]]'''<br />A template is basically the design of your Joomla! powered website.

Joomla! 4 is constructed using five different applications:
* 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);
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''.

=== Requirements ===
You need Joomla! 4.x installation available to use for this tutorial ([https://github.com/joomla/joomla-cms/releases Download latest release here])

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.

== Creating a simple module/Developing a Basic Module - Part 1 ==
You can see many examples of modules in the standard Joomla! install. For example:
* Menus
* Latest News
* Login form
* and many more.

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.

=== File Structure ===
There are a few basic files that are used in the standard pattern of module development:
* <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.
* <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.
* <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.
* <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.

=== Creating mod_foo.php ===
The <tt>mod_foo.php</tt> file will perform following tasks:
* Import the class <tt>ModuleHelper</tt> to the current scope. We need it later for displaying the output.
* Include the template to display the output.

The helper class is imported to our current scope at the begin of the file.

<source lang="php">use Joomla\CMS\Helper\ModuleHelper;</source>

Last we include the template to display the output via

<source lang="php">require ModuleHelper::getLayoutPath('mod_foo', $params->get('layout', 'default'));</source>

==== Completed mod_foo.php file ====
The complete <tt>mod_foo.php</tt> file is as follows:

<source 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'));

</source>

''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.

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.

=== Creating tmpl/default.php ===
The <tt>default.php</tt> file is the template which displays the module output.

==== Completed tmpl/default.php file ====
The code for the tmpl/default.php file is as follows:

<source 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]';

</source>

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.

=== Creating mod_foo.xml ===
The <tt>mod_foo.xml</tt> file is the installation file. Most entries are self-explanatory.

==== Completed mod_foo.xml file ====
The code for the <tt>mod_foo.xml</tt> file is as follows:

<source 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>

</source>

=== Создание языковых файлов ===
Файлы <tt>language/en-GB/mod_foo.ini</tt> и <tt>language/en-GB/mod_foo.sys.ini</tt> используются для перевода текста на сайте и панели администратора. Обратите внимание, что структура языкового файла была обновлена в Joomla 4, и языковые префиксы для отдельных файлов в языковой папке больше не требуются.

Код для <tt>language/en-GB/mod_foo.sys.ini</tt> выглядит следующим образом:

<source lang="xml">

MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"

</source>

Код для <tt>language/en-GB/mod_foo.ini</tt> выглядит следующим образом:

<source lang="xml">

MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"

</source>

Файл <tt>.sys.ini</tt> используется для перевода описания расширения при установке, тогда как файл <tt>.ini</tt> используется для перевода оставшихся строк и описания при просмотре вашего расширения.

Более подробную информацию о языковых файлах можно найти [[S:MyLanguage/Specification_of_language_files|here]].

== Test your module ==
Now you can zip all files and install them via the Joomla Extension Manager.<br />
After that you can choose your module in the module manager, when you create a new site module.
{{-}}
[[File:moduletutorial1-en.png|700px|center]]
{{-}}
[[File:moduletutorial2-en.png|700px|center]]

In the frontend, you will see your module like displayed in the next image.
{{-}}
[[File:moduletutorial3-en.png|700px|center]]

== Conclusion ==
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.

You can find boilerplates hereː
* https://github.com/joomla-extensions/boilerplate/tree/master/module
The sample files for this Tutorial can be found hereː
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

== Add a helper class using namespaces - Part 2==

=== Requirements ===
You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)

== Namespaces ==
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.

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.

Let's take a look how to use them in Joomla 4. We use the helper file for this.

=== File Structure ===
We will create/change the following files:
* <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.

=== Creating Helper/FooHelper.php ===
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.

<source lang="php">namespace Joomla\Module\Foo\Site\Helper;</source>

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.

==== Completed Helper/FooHelper.php ====
The complete <tt>FooHelper.php</tt> file is as follows:

<source 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';
}
}

</source>

=== Editing mod_foo.php ===
Our new helper class is imported to our current scope at the beginning of the file.

<source lang="php">use Joomla\Module\Foo\Site\Helper\FooHelper;</source>

Last use the helper file for testing if it is loaded correctlyː

<source lang="php">$test = FooHelper::getText($params, $app);</source>

==== Completed mod_foo.php file ====
The complete <tt>mod_foo.php</tt> file is as follows:

<source 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'));

</source>

=== Editing tmpl/default.php ===
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.

<source lang="php">echo '[PROJECT_NAME]' . $test;</source>

==== Completed tmpl/default.php ====
The complete <tt>tmpl/default.php</tt> file is as follows:

<source 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;

</source>

=== Editing mod_foo.xml ===
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>.

<source lang="xml"><namespace>Joomla\Module\Foo</namespace></source>

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.

<source lang="xml"><folder>Helper</folder></source>

==== Completed mod_foo.xml ====
The complete <tt>mod_foo.xml</tt> file is as follows:

<source 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>

</source>

== Test your module ==
Now you can zip all files and install them via the Joomla Extension Manager.
After that you can choose your module in the module manager, when you create a new site module.

In the frontend you will see your module like displayed in the next image. The text from your helper file is displayed.
{{-}}
[[File:moduletutorial23-en.png|700px|center]]

== Conclusion ==
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.

You can find boilerplates hereː
* https://github.com/joomla-extensions/boilerplate/tree/master/module
The sample files for this Tutorial can be found hereː
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

== Customizationː Add parameters via form fields - Part 3 ==

=== Requirements ===
You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)

== Customization with form fields and parameters ==
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.

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.

After that, we insert parameters that allow to use standard functionality of Joomla.

Let's take a look on how to use them in Joomla 4.

=== File Structure ===
We will change the following files:
* <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.

=== Editing mod_foo.xml ===
First we set a custom parameter.

<source lang="xml">

<field
name="domain"
type="url"
label="MOD_FOO_FIELD_URL_LABEL"
filter="url"
/>

</source>

Then we insert Joomla default fields, so that we can use cache, moduleclass-suffix and layouts.

<source 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>

</source>

==== Completed mod_foo.xml ====
The complete <tt>mod_foo.xml</tt> file is as follows:

<source 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>

</source>

=== Editing tmpl/default.php ===
We can use the value of the parameter for creating a hyperlink in the frontend. We can access the value via the variable $params.

<source lang="php">$domain = $params->get('domain', 'https://www.joomla.org');</source>

Later we set use this value for creating the hyperlink.

<source lang="php">

<a href="<?php echo $domain; ?>">
<?php echo '[PROJECT_NAME]' . $test; ?>
</a>

</source>

==== Completed tmpl/default.php file ====
The complete <tt>tmpl/default.php</tt> file is as follows:

<source 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>

</source>

=== Editing language/en-GB/en-GB.mod_foo.ini ===
Here we can specify the text for the English version of the field label.

<source lang="php">MOD_FOO_FIELD_URL_LABEL="Url"</source>

==== Completed language/en-GB/en-GB.mod_foo.ini ====
The complete <tt>language/en-GB/en-GB.mod_foo.ini</tt> file is as follows:

<source lang="php">

MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"
MOD_FOO_FIELD_URL_LABEL="Url"

</source>

== Test your module ==
Now you can zip all files and install them via the Joomla Extension Manager.
After that you can choose your module in the module manager, when you create a new site module.

In the backend, you will see your module like displayed in the next image.

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.
{{-}}
[[File:moduletutorial31-en.png|700px|center]]

In the advanced tab, you will see all default options except the cache mode because of this is a hidden field.
{{-}}
[[File:moduletutorial32-en.png|700px|center]]

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.
{{-}}
[[File:moduletutorial33-en.png|700px|center]]

== Conclusion ==
Form fields give the user an easy way to customize the module to their sites settings. This allows the modules scope to be increased.

You can find boilerplates hereː
* https://github.com/joomla-extensions/boilerplate/tree/master/module
The sample files for this Tutorial can be found hereː
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules
See this issue for possible future changes:
* https://github.com/joomla/joomla-cms/pull/23553

== Use Install, Update and Uninstall script - Part 4 ==

=== Requirements ===
You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)

=== Scripts ===
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:
* preflight which is executed before install and update
* install
* update
* uninstall
* postflight which is executed after install and update

Let's take a look how to use them in Joomla 4. We use the helper file for this.

=== File Structure ===
We will create/change the following files:
* <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.

=== Creating script.php ===
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.

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.

==== Completed script.php ====
The complete <tt>script.php</tt> file is as follows:

<source 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;
}
}

</source>

=== Editing language/en-GB/en-GB.mod_foo.sys.ini ===
There is not much to explain here. Write the text for the translation into this file.

==== Completed language/en-GB/en-GB.mod_foo.sys.ini file ====
The complete <tt>language/en-GB/en-GB.mod_foo.sys.ini</tt> file is as follows:

<source 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>"

</source>

=== Editing mod_foo.xml ===
You have to add a line, so that the script is called automatically in Joomla.

<source lang="xml"><scriptfile>script.php</scriptfile></source>

==== Completed mod_foo.xml ====
The complete <tt>mod_foo.xml</tt> file is as follows:

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

== Test your module ==
Now you can zip all files and install them via the Joomla Extension Manager.
Immediately after the installation, you will see the following information. This you had entered in the script so.
{{-}}
[[File:moduletutorial14-en.png|700px|center]]

== Conclusion ==
As you can see, Joomla offers you a lot to make your extension easy to use - right from the start.

You can find boilerplates hereː
* https://github.com/joomla-extensions/boilerplate/tree/master/module
The sample files for this Tutorial can be found hereː
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

== Use Joomla Updaterː Adding Auto Update - Part 5 ==

=== Requirements ===
You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)

=== Joomla Updater ===
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.

=== File Structure ===
We will create/change the following files:
* <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.
* <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.

==== Editing mod_foo.xml ====
To add our update server, we need to insert the following lines in your XML-Fileː

<source lang="php">

<updateservers>
<server type="extension" priority="1" name="[PROJECT_NAME]">https://www.example.com/mod_foo.xml</server>
</updateservers>

</source>

==== Completed mod_foo.xml ====
The complete <tt>mod_foo.xml</tt> file is as follows:

<source 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>

</source>

So now that Joomlaǃ is searching for updates to our extension - let's create one to test out our process. But 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.

=== Creating foo_update.xml ===
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.

==== Completed foo_update.xml ====
The complete <tt>foo_update.xml</tt> file is as follows:

<source 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>

</source>

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.

=== Test your module update ===
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.

=== Commercial Modules ===
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 .

=== Conclusion ===
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.

Each extension should use an update server. Especially for security reasons.

You can find boilerplates hereː
* https://github.com/joomla-extensions/boilerplate/tree/master/module
The sample files for this Tutorial can be found hereː
* 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>

Translations:J4.x:Creating a Simple Module/54/ru

2021-11-17T14:28:52Z

Dzandut: Created page with "Более подробную информацию о языковых файлах можно найти here."

Более подробную информацию о языковых файлах можно найти [[S:MyLanguage/Specification_of_language_files|here]].

J4.x:Creating a Simple Module/ru

2021-11-17T14:28:13Z

Dzandut:

<noinclude><languages /></noinclude>
{{Joomla version|version=4.x|comment=>Tutorial}}
{{-}}
{{Top portal heading|color=white-bkgd|icon=file-code-o|icon-color=#5091cd|size=5x|text-color=#333|title=Creating a Simple Module for Joomla 4.x}}
{{-}}

This is a tutorial on how to Create a simple module for Joomla Version 4x.
== Introduction ==
Joomlaǃ 4 provides five types of extensionsː
* '''[[S:MyLanguage/Component|Components]]'''<br />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.
* '''[[S:MyLanguage/Module|Modules]]''' <br />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.
* '''[[S:MyLanguage/Plugin|Plugins]]'''<br />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.
* '''[[S:MyLanguage/Languages|Languages]]'''<br />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.
* '''[[S:MyLanguage/Templates|Templates]]'''<br />A template is basically the design of your Joomla! powered website.

Joomla! 4 is constructed using five different applications:
* 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);
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''.

=== Requirements ===
You need Joomla! 4.x installation available to use for this tutorial ([https://github.com/joomla/joomla-cms/releases Download latest release here])

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.

== Creating a simple module/Developing a Basic Module - Part 1 ==
You can see many examples of modules in the standard Joomla! install. For example:
* Menus
* Latest News
* Login form
* and many more.

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.

=== File Structure ===
There are a few basic files that are used in the standard pattern of module development:
* <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.
* <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.
* <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.
* <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.

=== Creating mod_foo.php ===
The <tt>mod_foo.php</tt> file will perform following tasks:
* Import the class <tt>ModuleHelper</tt> to the current scope. We need it later for displaying the output.
* Include the template to display the output.

The helper class is imported to our current scope at the begin of the file.

<source lang="php">use Joomla\CMS\Helper\ModuleHelper;</source>

Last we include the template to display the output via

<source lang="php">require ModuleHelper::getLayoutPath('mod_foo', $params->get('layout', 'default'));</source>

==== Completed mod_foo.php file ====
The complete <tt>mod_foo.php</tt> file is as follows:

<source 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'));

</source>

''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.

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.

=== Creating tmpl/default.php ===
The <tt>default.php</tt> file is the template which displays the module output.

==== Completed tmpl/default.php file ====
The code for the tmpl/default.php file is as follows:

<source 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]';

</source>

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.

=== Creating mod_foo.xml ===
The <tt>mod_foo.xml</tt> file is the installation file. Most entries are self-explanatory.

==== Completed mod_foo.xml file ====
The code for the <tt>mod_foo.xml</tt> file is as follows:

<source 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>

</source>

=== Создание языковых файлов ===
Файлы <tt>language/en-GB/mod_foo.ini</tt> и <tt>language/en-GB/mod_foo.sys.ini</tt> используются для перевода текста на сайте и панели администратора. Обратите внимание, что структура языкового файла была обновлена в Joomla 4, и языковые префиксы для отдельных файлов в языковой папке больше не требуются.

Код для <tt>language/en-GB/mod_foo.sys.ini</tt> выглядит следующим образом:

<source lang="xml">

MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"

</source>

Код для <tt>language/en-GB/mod_foo.ini</tt> выглядит следующим образом:

<source lang="xml">

MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"

</source>

Файл <tt>.sys.ini</tt> используется для перевода описания расширения при установке, тогда как файл <tt>.ini</tt> используется для перевода оставшихся строк и описания при просмотре вашего расширения.

More information about language files can be found [[S:MyLanguage/Specification_of_language_files|here]].

== Test your module ==
Now you can zip all files and install them via the Joomla Extension Manager.<br />
After that you can choose your module in the module manager, when you create a new site module.
{{-}}
[[File:moduletutorial1-en.png|700px|center]]
{{-}}
[[File:moduletutorial2-en.png|700px|center]]

In the frontend, you will see your module like displayed in the next image.
{{-}}
[[File:moduletutorial3-en.png|700px|center]]

== Conclusion ==
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.

You can find boilerplates hereː
* https://github.com/joomla-extensions/boilerplate/tree/master/module
The sample files for this Tutorial can be found hereː
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

== Add a helper class using namespaces - Part 2==

=== Requirements ===
You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)

== Namespaces ==
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.

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.

Let's take a look how to use them in Joomla 4. We use the helper file for this.

=== File Structure ===
We will create/change the following files:
* <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.

=== Creating Helper/FooHelper.php ===
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.

<source lang="php">namespace Joomla\Module\Foo\Site\Helper;</source>

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.

==== Completed Helper/FooHelper.php ====
The complete <tt>FooHelper.php</tt> file is as follows:

<source 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';
}
}

</source>

=== Editing mod_foo.php ===
Our new helper class is imported to our current scope at the beginning of the file.

<source lang="php">use Joomla\Module\Foo\Site\Helper\FooHelper;</source>

Last use the helper file for testing if it is loaded correctlyː

<source lang="php">$test = FooHelper::getText($params, $app);</source>

==== Completed mod_foo.php file ====
The complete <tt>mod_foo.php</tt> file is as follows:

<source 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'));

</source>

=== Editing tmpl/default.php ===
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.

<source lang="php">echo '[PROJECT_NAME]' . $test;</source>

==== Completed tmpl/default.php ====
The complete <tt>tmpl/default.php</tt> file is as follows:

<source 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;

</source>

=== Editing mod_foo.xml ===
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>.

<source lang="xml"><namespace>Joomla\Module\Foo</namespace></source>

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.

<source lang="xml"><folder>Helper</folder></source>

==== Completed mod_foo.xml ====
The complete <tt>mod_foo.xml</tt> file is as follows:

<source 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>

</source>

== Test your module ==
Now you can zip all files and install them via the Joomla Extension Manager.
After that you can choose your module in the module manager, when you create a new site module.

In the frontend you will see your module like displayed in the next image. The text from your helper file is displayed.
{{-}}
[[File:moduletutorial23-en.png|700px|center]]

== Conclusion ==
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.

You can find boilerplates hereː
* https://github.com/joomla-extensions/boilerplate/tree/master/module
The sample files for this Tutorial can be found hereː
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

== Customizationː Add parameters via form fields - Part 3 ==

=== Requirements ===
You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)

== Customization with form fields and parameters ==
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.

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.

After that, we insert parameters that allow to use standard functionality of Joomla.

Let's take a look on how to use them in Joomla 4.

=== File Structure ===
We will change the following files:
* <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.

=== Editing mod_foo.xml ===
First we set a custom parameter.

<source lang="xml">

<field
name="domain"
type="url"
label="MOD_FOO_FIELD_URL_LABEL"
filter="url"
/>

</source>

Then we insert Joomla default fields, so that we can use cache, moduleclass-suffix and layouts.

<source 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>

</source>

==== Completed mod_foo.xml ====
The complete <tt>mod_foo.xml</tt> file is as follows:

<source 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>

</source>

=== Editing tmpl/default.php ===
We can use the value of the parameter for creating a hyperlink in the frontend. We can access the value via the variable $params.

<source lang="php">$domain = $params->get('domain', 'https://www.joomla.org');</source>

Later we set use this value for creating the hyperlink.

<source lang="php">

<a href="<?php echo $domain; ?>">
<?php echo '[PROJECT_NAME]' . $test; ?>
</a>

</source>

==== Completed tmpl/default.php file ====
The complete <tt>tmpl/default.php</tt> file is as follows:

<source 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>

</source>

=== Editing language/en-GB/en-GB.mod_foo.ini ===
Here we can specify the text for the English version of the field label.

<source lang="php">MOD_FOO_FIELD_URL_LABEL="Url"</source>

==== Completed language/en-GB/en-GB.mod_foo.ini ====
The complete <tt>language/en-GB/en-GB.mod_foo.ini</tt> file is as follows:

<source lang="php">

MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"
MOD_FOO_FIELD_URL_LABEL="Url"

</source>

== Test your module ==
Now you can zip all files and install them via the Joomla Extension Manager.
After that you can choose your module in the module manager, when you create a new site module.

In the backend, you will see your module like displayed in the next image.

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.
{{-}}
[[File:moduletutorial31-en.png|700px|center]]

In the advanced tab, you will see all default options except the cache mode because of this is a hidden field.
{{-}}
[[File:moduletutorial32-en.png|700px|center]]

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.
{{-}}
[[File:moduletutorial33-en.png|700px|center]]

== Conclusion ==
Form fields give the user an easy way to customize the module to their sites settings. This allows the modules scope to be increased.

You can find boilerplates hereː
* https://github.com/joomla-extensions/boilerplate/tree/master/module
The sample files for this Tutorial can be found hereː
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules
See this issue for possible future changes:
* https://github.com/joomla/joomla-cms/pull/23553

== Use Install, Update and Uninstall script - Part 4 ==

=== Requirements ===
You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)

=== Scripts ===
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:
* preflight which is executed before install and update
* install
* update
* uninstall
* postflight which is executed after install and update

Let's take a look how to use them in Joomla 4. We use the helper file for this.

=== File Structure ===
We will create/change the following files:
* <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.

=== Creating script.php ===
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.

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.

==== Completed script.php ====
The complete <tt>script.php</tt> file is as follows:

<source 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;
}
}

</source>

=== Editing language/en-GB/en-GB.mod_foo.sys.ini ===
There is not much to explain here. Write the text for the translation into this file.

==== Completed language/en-GB/en-GB.mod_foo.sys.ini file ====
The complete <tt>language/en-GB/en-GB.mod_foo.sys.ini</tt> file is as follows:

<source 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>"

</source>

=== Editing mod_foo.xml ===
You have to add a line, so that the script is called automatically in Joomla.

<source lang="xml"><scriptfile>script.php</scriptfile></source>

==== Completed mod_foo.xml ====
The complete <tt>mod_foo.xml</tt> file is as follows:

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

== Test your module ==
Now you can zip all files and install them via the Joomla Extension Manager.
Immediately after the installation, you will see the following information. This you had entered in the script so.
{{-}}
[[File:moduletutorial14-en.png|700px|center]]

== Conclusion ==
As you can see, Joomla offers you a lot to make your extension easy to use - right from the start.

You can find boilerplates hereː
* https://github.com/joomla-extensions/boilerplate/tree/master/module
The sample files for this Tutorial can be found hereː
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

== Use Joomla Updaterː Adding Auto Update - Part 5 ==

=== Requirements ===
You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)

=== Joomla Updater ===
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.

=== File Structure ===
We will create/change the following files:
* <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.
* <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.

==== Editing mod_foo.xml ====
To add our update server, we need to insert the following lines in your XML-Fileː

<source lang="php">

<updateservers>
<server type="extension" priority="1" name="[PROJECT_NAME]">https://www.example.com/mod_foo.xml</server>
</updateservers>

</source>

==== Completed mod_foo.xml ====
The complete <tt>mod_foo.xml</tt> file is as follows:

<source 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>

</source>

So now that Joomlaǃ is searching for updates to our extension - let's create one to test out our process. But 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.

=== Creating foo_update.xml ===
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.

==== Completed foo_update.xml ====
The complete <tt>foo_update.xml</tt> file is as follows:

<source 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>

</source>

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.

=== Test your module update ===
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.

=== Commercial Modules ===
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 .

=== Conclusion ===
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.

Each extension should use an update server. Especially for security reasons.

You can find boilerplates hereː
* https://github.com/joomla-extensions/boilerplate/tree/master/module
The sample files for this Tutorial can be found hereː
* 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>

Translations:J4.x:Creating a Simple Module/51/ru

2021-11-17T14:28:08Z

Dzandut:

Файлы <tt>language/en-GB/mod_foo.ini</tt> и <tt>language/en-GB/mod_foo.sys.ini</tt> используются для перевода текста на сайте и панели администратора. Обратите внимание, что структура языкового файла была обновлена в Joomla 4, и языковые префиксы для отдельных файлов в языковой папке больше не требуются.

J4.x:Creating a Simple Module/ru

2021-11-17T14:27:59Z

Dzandut: Created page with "Файл <tt>.sys.ini</tt> используется для перевода описания расширения при установке, тогда как файл <tt>.in..."

<noinclude><languages /></noinclude>
{{Joomla version|version=4.x|comment=>Tutorial}}
{{-}}
{{Top portal heading|color=white-bkgd|icon=file-code-o|icon-color=#5091cd|size=5x|text-color=#333|title=Creating a Simple Module for Joomla 4.x}}
{{-}}

This is a tutorial on how to Create a simple module for Joomla Version 4x.
== Introduction ==
Joomlaǃ 4 provides five types of extensionsː
* '''[[S:MyLanguage/Component|Components]]'''<br />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.
* '''[[S:MyLanguage/Module|Modules]]''' <br />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.
* '''[[S:MyLanguage/Plugin|Plugins]]'''<br />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.
* '''[[S:MyLanguage/Languages|Languages]]'''<br />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.
* '''[[S:MyLanguage/Templates|Templates]]'''<br />A template is basically the design of your Joomla! powered website.

Joomla! 4 is constructed using five different applications:
* 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);
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''.

=== Requirements ===
You need Joomla! 4.x installation available to use for this tutorial ([https://github.com/joomla/joomla-cms/releases Download latest release here])

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.

== Creating a simple module/Developing a Basic Module - Part 1 ==
You can see many examples of modules in the standard Joomla! install. For example:
* Menus
* Latest News
* Login form
* and many more.

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.

=== File Structure ===
There are a few basic files that are used in the standard pattern of module development:
* <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.
* <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.
* <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.
* <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.

=== Creating mod_foo.php ===
The <tt>mod_foo.php</tt> file will perform following tasks:
* Import the class <tt>ModuleHelper</tt> to the current scope. We need it later for displaying the output.
* Include the template to display the output.

The helper class is imported to our current scope at the begin of the file.

<source lang="php">use Joomla\CMS\Helper\ModuleHelper;</source>

Last we include the template to display the output via

<source lang="php">require ModuleHelper::getLayoutPath('mod_foo', $params->get('layout', 'default'));</source>

==== Completed mod_foo.php file ====
The complete <tt>mod_foo.php</tt> file is as follows:

<source 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'));

</source>

''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.

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.

=== Creating tmpl/default.php ===
The <tt>default.php</tt> file is the template which displays the module output.

==== Completed tmpl/default.php file ====
The code for the tmpl/default.php file is as follows:

<source 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]';

</source>

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.

=== Creating mod_foo.xml ===
The <tt>mod_foo.xml</tt> file is the installation file. Most entries are self-explanatory.

==== Completed mod_foo.xml file ====
The code for the <tt>mod_foo.xml</tt> file is as follows:

<source 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>

</source>

=== Создание языковых файлов ===
Файлы <tt>language/en-GB/mod_foo.ini</tt> и <tt>language/en-GB/mod_foo.sys.ini</tt> используются для перевода текста на сайте и панели администратора соответственно. Обратите внимание, что структура языкового файла была обновлена в Joomla 4, и языковые префиксы для отдельных файлов в языковой папке больше не требуются.

Код для <tt>language/en-GB/mod_foo.sys.ini</tt> выглядит следующим образом:

<source lang="xml">

MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"

</source>

Код для <tt>language/en-GB/mod_foo.ini</tt> выглядит следующим образом:

<source lang="xml">

MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"

</source>

Файл <tt>.sys.ini</tt> используется для перевода описания расширения при установке, тогда как файл <tt>.ini</tt> используется для перевода оставшихся строк и описания при просмотре вашего расширения.

More information about language files can be found [[S:MyLanguage/Specification_of_language_files|here]].

== Test your module ==
Now you can zip all files and install them via the Joomla Extension Manager.<br />
After that you can choose your module in the module manager, when you create a new site module.
{{-}}
[[File:moduletutorial1-en.png|700px|center]]
{{-}}
[[File:moduletutorial2-en.png|700px|center]]

In the frontend, you will see your module like displayed in the next image.
{{-}}
[[File:moduletutorial3-en.png|700px|center]]

== Conclusion ==
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.

You can find boilerplates hereː
* https://github.com/joomla-extensions/boilerplate/tree/master/module
The sample files for this Tutorial can be found hereː
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

== Add a helper class using namespaces - Part 2==

=== Requirements ===
You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)

== Namespaces ==
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.

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.

Let's take a look how to use them in Joomla 4. We use the helper file for this.

=== File Structure ===
We will create/change the following files:
* <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.

=== Creating Helper/FooHelper.php ===
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.

<source lang="php">namespace Joomla\Module\Foo\Site\Helper;</source>

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.

==== Completed Helper/FooHelper.php ====
The complete <tt>FooHelper.php</tt> file is as follows:

<source 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';
}
}

</source>

=== Editing mod_foo.php ===
Our new helper class is imported to our current scope at the beginning of the file.

<source lang="php">use Joomla\Module\Foo\Site\Helper\FooHelper;</source>

Last use the helper file for testing if it is loaded correctlyː

<source lang="php">$test = FooHelper::getText($params, $app);</source>

==== Completed mod_foo.php file ====
The complete <tt>mod_foo.php</tt> file is as follows:

<source 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'));

</source>

=== Editing tmpl/default.php ===
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.

<source lang="php">echo '[PROJECT_NAME]' . $test;</source>

==== Completed tmpl/default.php ====
The complete <tt>tmpl/default.php</tt> file is as follows:

<source 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;

</source>

=== Editing mod_foo.xml ===
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>.

<source lang="xml"><namespace>Joomla\Module\Foo</namespace></source>

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.

<source lang="xml"><folder>Helper</folder></source>

==== Completed mod_foo.xml ====
The complete <tt>mod_foo.xml</tt> file is as follows:

<source 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>

</source>

== Test your module ==
Now you can zip all files and install them via the Joomla Extension Manager.
After that you can choose your module in the module manager, when you create a new site module.

In the frontend you will see your module like displayed in the next image. The text from your helper file is displayed.
{{-}}
[[File:moduletutorial23-en.png|700px|center]]

== Conclusion ==
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.

You can find boilerplates hereː
* https://github.com/joomla-extensions/boilerplate/tree/master/module
The sample files for this Tutorial can be found hereː
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

== Customizationː Add parameters via form fields - Part 3 ==

=== Requirements ===
You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)

== Customization with form fields and parameters ==
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.

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.

After that, we insert parameters that allow to use standard functionality of Joomla.

Let's take a look on how to use them in Joomla 4.

=== File Structure ===
We will change the following files:
* <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.

=== Editing mod_foo.xml ===
First we set a custom parameter.

<source lang="xml">

<field
name="domain"
type="url"
label="MOD_FOO_FIELD_URL_LABEL"
filter="url"
/>

</source>

Then we insert Joomla default fields, so that we can use cache, moduleclass-suffix and layouts.

<source 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>

</source>

==== Completed mod_foo.xml ====
The complete <tt>mod_foo.xml</tt> file is as follows:

<source 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>

</source>

=== Editing tmpl/default.php ===
We can use the value of the parameter for creating a hyperlink in the frontend. We can access the value via the variable $params.

<source lang="php">$domain = $params->get('domain', 'https://www.joomla.org');</source>

Later we set use this value for creating the hyperlink.

<source lang="php">

<a href="<?php echo $domain; ?>">
<?php echo '[PROJECT_NAME]' . $test; ?>
</a>

</source>

==== Completed tmpl/default.php file ====
The complete <tt>tmpl/default.php</tt> file is as follows:

<source 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>

</source>

=== Editing language/en-GB/en-GB.mod_foo.ini ===
Here we can specify the text for the English version of the field label.

<source lang="php">MOD_FOO_FIELD_URL_LABEL="Url"</source>

==== Completed language/en-GB/en-GB.mod_foo.ini ====
The complete <tt>language/en-GB/en-GB.mod_foo.ini</tt> file is as follows:

<source lang="php">

MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"
MOD_FOO_FIELD_URL_LABEL="Url"

</source>

== Test your module ==
Now you can zip all files and install them via the Joomla Extension Manager.
After that you can choose your module in the module manager, when you create a new site module.

In the backend, you will see your module like displayed in the next image.

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.
{{-}}
[[File:moduletutorial31-en.png|700px|center]]

In the advanced tab, you will see all default options except the cache mode because of this is a hidden field.
{{-}}
[[File:moduletutorial32-en.png|700px|center]]

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.
{{-}}
[[File:moduletutorial33-en.png|700px|center]]

== Conclusion ==
Form fields give the user an easy way to customize the module to their sites settings. This allows the modules scope to be increased.

You can find boilerplates hereː
* https://github.com/joomla-extensions/boilerplate/tree/master/module
The sample files for this Tutorial can be found hereː
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules
See this issue for possible future changes:
* https://github.com/joomla/joomla-cms/pull/23553

== Use Install, Update and Uninstall script - Part 4 ==

=== Requirements ===
You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)

=== Scripts ===
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:
* preflight which is executed before install and update
* install
* update
* uninstall
* postflight which is executed after install and update

Let's take a look how to use them in Joomla 4. We use the helper file for this.

=== File Structure ===
We will create/change the following files:
* <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.

=== Creating script.php ===
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.

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.

==== Completed script.php ====
The complete <tt>script.php</tt> file is as follows:

<source 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;
}
}

</source>

=== Editing language/en-GB/en-GB.mod_foo.sys.ini ===
There is not much to explain here. Write the text for the translation into this file.

==== Completed language/en-GB/en-GB.mod_foo.sys.ini file ====
The complete <tt>language/en-GB/en-GB.mod_foo.sys.ini</tt> file is as follows:

<source 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>"

</source>

=== Editing mod_foo.xml ===
You have to add a line, so that the script is called automatically in Joomla.

<source lang="xml"><scriptfile>script.php</scriptfile></source>

==== Completed mod_foo.xml ====
The complete <tt>mod_foo.xml</tt> file is as follows:

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

== Test your module ==
Now you can zip all files and install them via the Joomla Extension Manager.
Immediately after the installation, you will see the following information. This you had entered in the script so.
{{-}}
[[File:moduletutorial14-en.png|700px|center]]

== Conclusion ==
As you can see, Joomla offers you a lot to make your extension easy to use - right from the start.

You can find boilerplates hereː
* https://github.com/joomla-extensions/boilerplate/tree/master/module
The sample files for this Tutorial can be found hereː
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

== Use Joomla Updaterː Adding Auto Update - Part 5 ==

=== Requirements ===
You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)

=== Joomla Updater ===
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.

=== File Structure ===
We will create/change the following files:
* <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.
* <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.

==== Editing mod_foo.xml ====
To add our update server, we need to insert the following lines in your XML-Fileː

<source lang="php">

<updateservers>
<server type="extension" priority="1" name="[PROJECT_NAME]">https://www.example.com/mod_foo.xml</server>
</updateservers>

</source>

==== Completed mod_foo.xml ====
The complete <tt>mod_foo.xml</tt> file is as follows:

<source 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>

</source>

So now that Joomlaǃ is searching for updates to our extension - let's create one to test out our process. But 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.

=== Creating foo_update.xml ===
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.

==== Completed foo_update.xml ====
The complete <tt>foo_update.xml</tt> file is as follows:

<source 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>

</source>

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.

=== Test your module update ===
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.

=== Commercial Modules ===
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 .

=== Conclusion ===
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.

Each extension should use an update server. Especially for security reasons.

You can find boilerplates hereː
* https://github.com/joomla-extensions/boilerplate/tree/master/module
The sample files for this Tutorial can be found hereː
* 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>

Translations:J4.x:Creating a Simple Module/53/ru

2021-11-17T14:27:54Z

Файл <tt>.sys.ini</tt> используется для перевода описания расширения при установке, тогда как файл <tt>.ini</tt> используется для перевода оставшихся строк и описания при просмотре вашего расширения.

J4.x:Creating a Simple Module/ru

2021-11-17T14:25:54Z

Dzandut: Created page with "Код для <tt>language/en-GB/mod_foo.ini</tt> выглядит следующим образом:"

<noinclude><languages /></noinclude>
{{Joomla version|version=4.x|comment=>Tutorial}}
{{-}}
{{Top portal heading|color=white-bkgd|icon=file-code-o|icon-color=#5091cd|size=5x|text-color=#333|title=Creating a Simple Module for Joomla 4.x}}
{{-}}

This is a tutorial on how to Create a simple module for Joomla Version 4x.
== Introduction ==
Joomlaǃ 4 provides five types of extensionsː
* '''[[S:MyLanguage/Component|Components]]'''<br />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.
* '''[[S:MyLanguage/Module|Modules]]''' <br />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.
* '''[[S:MyLanguage/Plugin|Plugins]]'''<br />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.
* '''[[S:MyLanguage/Languages|Languages]]'''<br />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.
* '''[[S:MyLanguage/Templates|Templates]]'''<br />A template is basically the design of your Joomla! powered website.

Joomla! 4 is constructed using five different applications:
* 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);
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''.

=== Requirements ===
You need Joomla! 4.x installation available to use for this tutorial ([https://github.com/joomla/joomla-cms/releases Download latest release here])

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.

== Creating a simple module/Developing a Basic Module - Part 1 ==
You can see many examples of modules in the standard Joomla! install. For example:
* Menus
* Latest News
* Login form
* and many more.

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.

=== File Structure ===
There are a few basic files that are used in the standard pattern of module development:
* <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.
* <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.
* <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.
* <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.

=== Creating mod_foo.php ===
The <tt>mod_foo.php</tt> file will perform following tasks:
* Import the class <tt>ModuleHelper</tt> to the current scope. We need it later for displaying the output.
* Include the template to display the output.

The helper class is imported to our current scope at the begin of the file.

<source lang="php">use Joomla\CMS\Helper\ModuleHelper;</source>

Last we include the template to display the output via

<source lang="php">require ModuleHelper::getLayoutPath('mod_foo', $params->get('layout', 'default'));</source>

==== Completed mod_foo.php file ====
The complete <tt>mod_foo.php</tt> file is as follows:

<source 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'));

</source>

''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.

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.

=== Creating tmpl/default.php ===
The <tt>default.php</tt> file is the template which displays the module output.

==== Completed tmpl/default.php file ====
The code for the tmpl/default.php file is as follows:

<source 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]';

</source>

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.

=== Creating mod_foo.xml ===
The <tt>mod_foo.xml</tt> file is the installation file. Most entries are self-explanatory.

==== Completed mod_foo.xml file ====
The code for the <tt>mod_foo.xml</tt> file is as follows:

<source 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>

</source>

=== Создание языковых файлов ===
Файлы <tt>language/en-GB/mod_foo.ini</tt> и <tt>language/en-GB/mod_foo.sys.ini</tt> используются для перевода текста на сайте и панели администратора соответственно. Обратите внимание, что структура языкового файла была обновлена в Joomla 4, и языковые префиксы для отдельных файлов в языковой папке больше не требуются.

Код для <tt>language/en-GB/mod_foo.sys.ini</tt> выглядит следующим образом:

<source lang="xml">

MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"

</source>

Код для <tt>language/en-GB/mod_foo.ini</tt> выглядит следующим образом:

<source lang="xml">

MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"

</source>

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.

More information about language files can be found [[S:MyLanguage/Specification_of_language_files|here]].

== Test your module ==
Now you can zip all files and install them via the Joomla Extension Manager.<br />
After that you can choose your module in the module manager, when you create a new site module.
{{-}}
[[File:moduletutorial1-en.png|700px|center]]
{{-}}
[[File:moduletutorial2-en.png|700px|center]]

In the frontend, you will see your module like displayed in the next image.
{{-}}
[[File:moduletutorial3-en.png|700px|center]]

== Conclusion ==
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.

You can find boilerplates hereː
* https://github.com/joomla-extensions/boilerplate/tree/master/module
The sample files for this Tutorial can be found hereː
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

== Add a helper class using namespaces - Part 2==

=== Requirements ===
You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)

== Namespaces ==
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.

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.

Let's take a look how to use them in Joomla 4. We use the helper file for this.

=== File Structure ===
We will create/change the following files:
* <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.

=== Creating Helper/FooHelper.php ===
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.

<source lang="php">namespace Joomla\Module\Foo\Site\Helper;</source>

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.

==== Completed Helper/FooHelper.php ====
The complete <tt>FooHelper.php</tt> file is as follows:

<source 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';
}
}

</source>

=== Editing mod_foo.php ===
Our new helper class is imported to our current scope at the beginning of the file.

<source lang="php">use Joomla\Module\Foo\Site\Helper\FooHelper;</source>

Last use the helper file for testing if it is loaded correctlyː

<source lang="php">$test = FooHelper::getText($params, $app);</source>

==== Completed mod_foo.php file ====
The complete <tt>mod_foo.php</tt> file is as follows:

<source 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'));

</source>

=== Editing tmpl/default.php ===
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.

<source lang="php">echo '[PROJECT_NAME]' . $test;</source>

==== Completed tmpl/default.php ====
The complete <tt>tmpl/default.php</tt> file is as follows:

<source 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;

</source>

=== Editing mod_foo.xml ===
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>.

<source lang="xml"><namespace>Joomla\Module\Foo</namespace></source>

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.

<source lang="xml"><folder>Helper</folder></source>

==== Completed mod_foo.xml ====
The complete <tt>mod_foo.xml</tt> file is as follows:

<source 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>

</source>

== Test your module ==
Now you can zip all files and install them via the Joomla Extension Manager.
After that you can choose your module in the module manager, when you create a new site module.

In the frontend you will see your module like displayed in the next image. The text from your helper file is displayed.
{{-}}
[[File:moduletutorial23-en.png|700px|center]]

== Conclusion ==
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.

You can find boilerplates hereː
* https://github.com/joomla-extensions/boilerplate/tree/master/module
The sample files for this Tutorial can be found hereː
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

== Customizationː Add parameters via form fields - Part 3 ==

=== Requirements ===
You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)

== Customization with form fields and parameters ==
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.

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.

After that, we insert parameters that allow to use standard functionality of Joomla.

Let's take a look on how to use them in Joomla 4.

=== File Structure ===
We will change the following files:
* <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.

=== Editing mod_foo.xml ===
First we set a custom parameter.

<source lang="xml">

<field
name="domain"
type="url"
label="MOD_FOO_FIELD_URL_LABEL"
filter="url"
/>

</source>

Then we insert Joomla default fields, so that we can use cache, moduleclass-suffix and layouts.

<source 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>

</source>

==== Completed mod_foo.xml ====
The complete <tt>mod_foo.xml</tt> file is as follows:

<source 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>

</source>

=== Editing tmpl/default.php ===
We can use the value of the parameter for creating a hyperlink in the frontend. We can access the value via the variable $params.

<source lang="php">$domain = $params->get('domain', 'https://www.joomla.org');</source>

Later we set use this value for creating the hyperlink.

<source lang="php">

<a href="<?php echo $domain; ?>">
<?php echo '[PROJECT_NAME]' . $test; ?>
</a>

</source>

==== Completed tmpl/default.php file ====
The complete <tt>tmpl/default.php</tt> file is as follows:

<source 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>

</source>

=== Editing language/en-GB/en-GB.mod_foo.ini ===
Here we can specify the text for the English version of the field label.

<source lang="php">MOD_FOO_FIELD_URL_LABEL="Url"</source>

==== Completed language/en-GB/en-GB.mod_foo.ini ====
The complete <tt>language/en-GB/en-GB.mod_foo.ini</tt> file is as follows:

<source lang="php">

MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"
MOD_FOO_FIELD_URL_LABEL="Url"

</source>

== Test your module ==
Now you can zip all files and install them via the Joomla Extension Manager.
After that you can choose your module in the module manager, when you create a new site module.

In the backend, you will see your module like displayed in the next image.

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.
{{-}}
[[File:moduletutorial31-en.png|700px|center]]

In the advanced tab, you will see all default options except the cache mode because of this is a hidden field.
{{-}}
[[File:moduletutorial32-en.png|700px|center]]

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.
{{-}}
[[File:moduletutorial33-en.png|700px|center]]

== Conclusion ==
Form fields give the user an easy way to customize the module to their sites settings. This allows the modules scope to be increased.

You can find boilerplates hereː
* https://github.com/joomla-extensions/boilerplate/tree/master/module
The sample files for this Tutorial can be found hereː
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules
See this issue for possible future changes:
* https://github.com/joomla/joomla-cms/pull/23553

== Use Install, Update and Uninstall script - Part 4 ==

=== Requirements ===
You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)

=== Scripts ===
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:
* preflight which is executed before install and update
* install
* update
* uninstall
* postflight which is executed after install and update

Let's take a look how to use them in Joomla 4. We use the helper file for this.

=== File Structure ===
We will create/change the following files:
* <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.

=== Creating script.php ===
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.

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.

==== Completed script.php ====
The complete <tt>script.php</tt> file is as follows:

<source 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;
}
}

</source>

=== Editing language/en-GB/en-GB.mod_foo.sys.ini ===
There is not much to explain here. Write the text for the translation into this file.

==== Completed language/en-GB/en-GB.mod_foo.sys.ini file ====
The complete <tt>language/en-GB/en-GB.mod_foo.sys.ini</tt> file is as follows:

<source 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>"

</source>

=== Editing mod_foo.xml ===
You have to add a line, so that the script is called automatically in Joomla.

<source lang="xml"><scriptfile>script.php</scriptfile></source>

==== Completed mod_foo.xml ====
The complete <tt>mod_foo.xml</tt> file is as follows:

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

== Test your module ==
Now you can zip all files and install them via the Joomla Extension Manager.
Immediately after the installation, you will see the following information. This you had entered in the script so.
{{-}}
[[File:moduletutorial14-en.png|700px|center]]

== Conclusion ==
As you can see, Joomla offers you a lot to make your extension easy to use - right from the start.

You can find boilerplates hereː
* https://github.com/joomla-extensions/boilerplate/tree/master/module
The sample files for this Tutorial can be found hereː
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

== Use Joomla Updaterː Adding Auto Update - Part 5 ==

=== Requirements ===
You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)

=== Joomla Updater ===
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.

=== File Structure ===
We will create/change the following files:
* <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.
* <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.

==== Editing mod_foo.xml ====
To add our update server, we need to insert the following lines in your XML-Fileː

<source lang="php">

<updateservers>
<server type="extension" priority="1" name="[PROJECT_NAME]">https://www.example.com/mod_foo.xml</server>
</updateservers>

</source>

==== Completed mod_foo.xml ====
The complete <tt>mod_foo.xml</tt> file is as follows:

<source 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>

</source>

So now that Joomlaǃ is searching for updates to our extension - let's create one to test out our process. But 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.

=== Creating foo_update.xml ===
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.

==== Completed foo_update.xml ====
The complete <tt>foo_update.xml</tt> file is as follows:

<source 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>

</source>

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.

=== Test your module update ===
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.

=== Commercial Modules ===
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 .

=== Conclusion ===
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.

Each extension should use an update server. Especially for security reasons.

You can find boilerplates hereː
* https://github.com/joomla-extensions/boilerplate/tree/master/module
The sample files for this Tutorial can be found hereː
* 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>

Translations:J4.x:Creating a Simple Module/204/ru

2021-11-17T14:25:49Z

Dzandut: Created page with "Код для <tt>language/en-GB/mod_foo.ini</tt> выглядит следующим образом:"

Код для <tt>language/en-GB/mod_foo.ini</tt> выглядит следующим образом:

J4.x:Creating a Simple Module/ru

2021-11-17T14:24:50Z

Dzandut: Created page with "Код для <tt>language/en-GB/mod_foo.sys.ini</tt> выглядит следующим образом:"

<noinclude><languages /></noinclude>
{{Joomla version|version=4.x|comment=>Tutorial}}
{{-}}
{{Top portal heading|color=white-bkgd|icon=file-code-o|icon-color=#5091cd|size=5x|text-color=#333|title=Creating a Simple Module for Joomla 4.x}}
{{-}}

This is a tutorial on how to Create a simple module for Joomla Version 4x.
== Introduction ==
Joomlaǃ 4 provides five types of extensionsː
* '''[[S:MyLanguage/Component|Components]]'''<br />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.
* '''[[S:MyLanguage/Module|Modules]]''' <br />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.
* '''[[S:MyLanguage/Plugin|Plugins]]'''<br />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.
* '''[[S:MyLanguage/Languages|Languages]]'''<br />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.
* '''[[S:MyLanguage/Templates|Templates]]'''<br />A template is basically the design of your Joomla! powered website.

Joomla! 4 is constructed using five different applications:
* 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);
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''.

=== Requirements ===
You need Joomla! 4.x installation available to use for this tutorial ([https://github.com/joomla/joomla-cms/releases Download latest release here])

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.

== Creating a simple module/Developing a Basic Module - Part 1 ==
You can see many examples of modules in the standard Joomla! install. For example:
* Menus
* Latest News
* Login form
* and many more.

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.

=== File Structure ===
There are a few basic files that are used in the standard pattern of module development:
* <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.
* <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.
* <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.
* <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.

=== Creating mod_foo.php ===
The <tt>mod_foo.php</tt> file will perform following tasks:
* Import the class <tt>ModuleHelper</tt> to the current scope. We need it later for displaying the output.
* Include the template to display the output.

The helper class is imported to our current scope at the begin of the file.

<source lang="php">use Joomla\CMS\Helper\ModuleHelper;</source>

Last we include the template to display the output via

<source lang="php">require ModuleHelper::getLayoutPath('mod_foo', $params->get('layout', 'default'));</source>

==== Completed mod_foo.php file ====
The complete <tt>mod_foo.php</tt> file is as follows:

<source 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'));

</source>

''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.

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.

=== Creating tmpl/default.php ===
The <tt>default.php</tt> file is the template which displays the module output.

==== Completed tmpl/default.php file ====
The code for the tmpl/default.php file is as follows:

<source 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]';

</source>

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.

=== Creating mod_foo.xml ===
The <tt>mod_foo.xml</tt> file is the installation file. Most entries are self-explanatory.

==== Completed mod_foo.xml file ====
The code for the <tt>mod_foo.xml</tt> file is as follows:

<source 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>

</source>

=== Создание языковых файлов ===
Файлы <tt>language/en-GB/mod_foo.ini</tt> и <tt>language/en-GB/mod_foo.sys.ini</tt> используются для перевода текста на сайте и панели администратора соответственно. Обратите внимание, что структура языкового файла была обновлена в Joomla 4, и языковые префиксы для отдельных файлов в языковой папке больше не требуются.

Код для <tt>language/en-GB/mod_foo.sys.ini</tt> выглядит следующим образом:

<source lang="xml">

MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"

</source>

The code for <tt>language/en-GB/mod_foo.ini</tt> is as follows:

<source lang="xml">

MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"

</source>

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.

More information about language files can be found [[S:MyLanguage/Specification_of_language_files|here]].

== Test your module ==
Now you can zip all files and install them via the Joomla Extension Manager.<br />
After that you can choose your module in the module manager, when you create a new site module.
{{-}}
[[File:moduletutorial1-en.png|700px|center]]
{{-}}
[[File:moduletutorial2-en.png|700px|center]]

In the frontend, you will see your module like displayed in the next image.
{{-}}
[[File:moduletutorial3-en.png|700px|center]]

== Conclusion ==
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.

You can find boilerplates hereː
* https://github.com/joomla-extensions/boilerplate/tree/master/module
The sample files for this Tutorial can be found hereː
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

== Add a helper class using namespaces - Part 2==

=== Requirements ===
You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)

== Namespaces ==
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.

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.

Let's take a look how to use them in Joomla 4. We use the helper file for this.

=== File Structure ===
We will create/change the following files:
* <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.

=== Creating Helper/FooHelper.php ===
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.

<source lang="php">namespace Joomla\Module\Foo\Site\Helper;</source>

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.

==== Completed Helper/FooHelper.php ====
The complete <tt>FooHelper.php</tt> file is as follows:

<source 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';
}
}

</source>

=== Editing mod_foo.php ===
Our new helper class is imported to our current scope at the beginning of the file.

<source lang="php">use Joomla\Module\Foo\Site\Helper\FooHelper;</source>

Last use the helper file for testing if it is loaded correctlyː

<source lang="php">$test = FooHelper::getText($params, $app);</source>

==== Completed mod_foo.php file ====
The complete <tt>mod_foo.php</tt> file is as follows:

<source 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'));

</source>

=== Editing tmpl/default.php ===
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.

<source lang="php">echo '[PROJECT_NAME]' . $test;</source>

==== Completed tmpl/default.php ====
The complete <tt>tmpl/default.php</tt> file is as follows:

<source 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;

</source>

=== Editing mod_foo.xml ===
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>.

<source lang="xml"><namespace>Joomla\Module\Foo</namespace></source>

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.

<source lang="xml"><folder>Helper</folder></source>

==== Completed mod_foo.xml ====
The complete <tt>mod_foo.xml</tt> file is as follows:

<source 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>

</source>

== Test your module ==
Now you can zip all files and install them via the Joomla Extension Manager.
After that you can choose your module in the module manager, when you create a new site module.

In the frontend you will see your module like displayed in the next image. The text from your helper file is displayed.
{{-}}
[[File:moduletutorial23-en.png|700px|center]]

== Conclusion ==
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.

You can find boilerplates hereː
* https://github.com/joomla-extensions/boilerplate/tree/master/module
The sample files for this Tutorial can be found hereː
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

== Customizationː Add parameters via form fields - Part 3 ==

=== Requirements ===
You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)

== Customization with form fields and parameters ==
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.

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.

After that, we insert parameters that allow to use standard functionality of Joomla.

Let's take a look on how to use them in Joomla 4.

=== File Structure ===
We will change the following files:
* <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.

=== Editing mod_foo.xml ===
First we set a custom parameter.

<source lang="xml">

<field
name="domain"
type="url"
label="MOD_FOO_FIELD_URL_LABEL"
filter="url"
/>

</source>

Then we insert Joomla default fields, so that we can use cache, moduleclass-suffix and layouts.

<source 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>

</source>

==== Completed mod_foo.xml ====
The complete <tt>mod_foo.xml</tt> file is as follows:

<source 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>

</source>

=== Editing tmpl/default.php ===
We can use the value of the parameter for creating a hyperlink in the frontend. We can access the value via the variable $params.

<source lang="php">$domain = $params->get('domain', 'https://www.joomla.org');</source>

Later we set use this value for creating the hyperlink.

<source lang="php">

<a href="<?php echo $domain; ?>">
<?php echo '[PROJECT_NAME]' . $test; ?>
</a>

</source>

==== Completed tmpl/default.php file ====
The complete <tt>tmpl/default.php</tt> file is as follows:

<source 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>

</source>

=== Editing language/en-GB/en-GB.mod_foo.ini ===
Here we can specify the text for the English version of the field label.

<source lang="php">MOD_FOO_FIELD_URL_LABEL="Url"</source>

==== Completed language/en-GB/en-GB.mod_foo.ini ====
The complete <tt>language/en-GB/en-GB.mod_foo.ini</tt> file is as follows:

<source lang="php">

MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"
MOD_FOO_FIELD_URL_LABEL="Url"

</source>

== Test your module ==
Now you can zip all files and install them via the Joomla Extension Manager.
After that you can choose your module in the module manager, when you create a new site module.

In the backend, you will see your module like displayed in the next image.

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.
{{-}}
[[File:moduletutorial31-en.png|700px|center]]

In the advanced tab, you will see all default options except the cache mode because of this is a hidden field.
{{-}}
[[File:moduletutorial32-en.png|700px|center]]

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.
{{-}}
[[File:moduletutorial33-en.png|700px|center]]

== Conclusion ==
Form fields give the user an easy way to customize the module to their sites settings. This allows the modules scope to be increased.

You can find boilerplates hereː
* https://github.com/joomla-extensions/boilerplate/tree/master/module
The sample files for this Tutorial can be found hereː
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules
See this issue for possible future changes:
* https://github.com/joomla/joomla-cms/pull/23553

== Use Install, Update and Uninstall script - Part 4 ==

=== Requirements ===
You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)

=== Scripts ===
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:
* preflight which is executed before install and update
* install
* update
* uninstall
* postflight which is executed after install and update

Let's take a look how to use them in Joomla 4. We use the helper file for this.

=== File Structure ===
We will create/change the following files:
* <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.

=== Creating script.php ===
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.

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.

==== Completed script.php ====
The complete <tt>script.php</tt> file is as follows:

<source 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;
}
}

</source>

=== Editing language/en-GB/en-GB.mod_foo.sys.ini ===
There is not much to explain here. Write the text for the translation into this file.

==== Completed language/en-GB/en-GB.mod_foo.sys.ini file ====
The complete <tt>language/en-GB/en-GB.mod_foo.sys.ini</tt> file is as follows:

<source 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>"

</source>

=== Editing mod_foo.xml ===
You have to add a line, so that the script is called automatically in Joomla.

<source lang="xml"><scriptfile>script.php</scriptfile></source>

==== Completed mod_foo.xml ====
The complete <tt>mod_foo.xml</tt> file is as follows:

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

== Test your module ==
Now you can zip all files and install them via the Joomla Extension Manager.
Immediately after the installation, you will see the following information. This you had entered in the script so.
{{-}}
[[File:moduletutorial14-en.png|700px|center]]

== Conclusion ==
As you can see, Joomla offers you a lot to make your extension easy to use - right from the start.

You can find boilerplates hereː
* https://github.com/joomla-extensions/boilerplate/tree/master/module
The sample files for this Tutorial can be found hereː
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

== Use Joomla Updaterː Adding Auto Update - Part 5 ==

=== Requirements ===
You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)

=== Joomla Updater ===
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.

=== File Structure ===
We will create/change the following files:
* <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.
* <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.

==== Editing mod_foo.xml ====
To add our update server, we need to insert the following lines in your XML-Fileː

<source lang="php">

<updateservers>
<server type="extension" priority="1" name="[PROJECT_NAME]">https://www.example.com/mod_foo.xml</server>
</updateservers>

</source>

==== Completed mod_foo.xml ====
The complete <tt>mod_foo.xml</tt> file is as follows:

<source 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>

</source>

So now that Joomlaǃ is searching for updates to our extension - let's create one to test out our process. But 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.

=== Creating foo_update.xml ===
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.

==== Completed foo_update.xml ====
The complete <tt>foo_update.xml</tt> file is as follows:

<source 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>

</source>

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.

=== Test your module update ===
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.

=== Commercial Modules ===
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 .

=== Conclusion ===
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.

Each extension should use an update server. Especially for security reasons.

You can find boilerplates hereː
* https://github.com/joomla-extensions/boilerplate/tree/master/module
The sample files for this Tutorial can be found hereː
* 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>

Translations:J4.x:Creating a Simple Module/52/ru

2021-11-17T14:24:45Z

Dzandut: Created page with "Код для <tt>language/en-GB/mod_foo.sys.ini</tt> выглядит следующим образом:"

Код для <tt>language/en-GB/mod_foo.sys.ini</tt> выглядит следующим образом: