Extension Types - akeeba/onthos GitHub Wiki

There are six extension types in Joomla!, each one with different uses and purpose.

Components

Components are the basic building blocks of Joomla. Conceptually, if Joomla was your smartphone then Components would be its applications.

Components render the main page content, and handle JSON API calls.

Components are internally named as com_something. The name always starts with com_ (which stands for Component) and a component-specific identifier.

A component com_something installs its files in the following subdirectories:

  • administrator/components/com_something for the mandatory backend (administrator) part of the component. The component's XML manifest and installation script (if any) is always stored in here as well. The component's XML manifest SHOULD be called something.xml, but this is currently not enforced; support for names other than something.xml is currently deprecated and might be removed in a future version of Joomla.
  • components/com_something for the optional public frontend (site) part of the component.
  • api/components/com_something for the optional Joomla! JSON API application part of the component.
  • media/com_something for the optional media files (CSS, JS, images, fonts, …) of the component.

Its language files are as follows for the default en-GB English (United Kingdom) language:

  • administrator/language/en-GB/com_something.sys.ini Mandatory. Used to display information about the component, and display its Options page.
  • administrator/language/en-GB/com_something.ini Optional. Used in the backend (administrator) part of the component.
  • language/en-GB/com_something.ini Optional. Used in the frontend (site) part of the component.
  • api/language/en-GB/com_something.ini Optional. Used in the JSON API application part of the component.

It is possible that these files are not present in those folders, but inside the component's folders themselves. However, this method of providing language files is considered deprecated and will be removed in a future version of Joomla.

ℹ️ Having language files inside the component's folder was introduced in Joomla! 1.6 and became deprecated in 3.0. The original concept was to eventually make components self-contained, and perhaps allow them to be packaged as PHAR files. This was problematic for many reasons, which is why it was deprecated less than three years since its inception.

It is possible for an extension to use language files from any of these folders. For example, it may use backend language files from the frontend. It's also possible for plugins related to the component, e.g. scheduled tasks, console (CLI) plugins etc, to use any of these translation files as they see fit.

Plugins

Unlike components, plugins are not applications in the strict sens of the word. They are “listeners”; they listen for and respond to events raised by other extensions.

Plugins are the most important extension type. They handle CAPTCHA, render the visual content editor you use to edit content, handle media files, provide links between different translations of the same content, handle custom fields, implement custom field types, handle the Joomla JSON API routing, provide CLI commands for the Joomla! CLI application, implement the scheduled tasks, provide additional login buttons, handle content tags and versions, manage the security of your site and so much more.

Plugins may not be visible –they rarely render any output on the page– but they are mighty. They are what makes Joomla truly awesome – in all senses of the word.

Plugins are internally named as plg_folder_something where folder is the plugin type (e.g. system, content, etc) and something is a unique identifier for this plugin within the specific plugin type.

A plugin plg_system_something installs its files in the following subdirectories:

  • plugins/system/something Mandatory. The main files of the plugin. The plugin's XML manifest and installation script (if any) is always stored in here as well. The component's XML manifest SHOULD be called something.xml, but this is currently not enforced; support for names other than something.xml is currently deprecated and might be removed in a future version of Joomla.
  • media/plg_system_something Optional. The optional media files (CSS, JS, images, fonts, …) of the plugin.

Its language files are as follows for the default en-GB English (United Kingdom) language:

  • administrator/language/en-GB/plg_system_something.sys.ini Mandatory. Used to display information about the plugin, and display its edit (options) page.
  • administrator/language/en-GB/plg_system_something.ini Optional. Any other language strings the plugin may need at runtime.

⚠️ Plugin language files are ALWAYS stored in the administrator language folder even if the plugin only runs in the frontend of the site.

It is possible that these files are not present in those folders, but inside the plugin's main folder. However, this method of providing language files is considered deprecated and will be removed in a future version of Joomla.

Modules

Modules are used to render small snippets of information on the page. Conceptually, if Joomla was your smartphone then Modules would be the widgets you put on the home screen.

Modules are used in places where you might not expect them, too! They are used to render the front- and backend menus, breadcrumbs, and all the backend control panels.

There are two types of modules: frontend (site) and backend (administrator). Each type of module can only be displayed in its corresponding part of your site, i.e. a site module will only appear in the public frontend of your site.

Modules are internally named as mod_something wheresomething is a unique identifier for this module within the specific part of your site (site or administrator).

A site module mod_something installs its files in the following subdirectories:

  • modules/mod_something. Mandatory. The main files of the module. The module's XML manifest and installation script (if any) is always stored in here as well. The modules's XML manifest SHOULD be called something.xml, but this is currently not enforced; support for names other than something.xml is currently deprecated and might be removed in a future version of Joomla.
  • media/mod_something. Optional. The optional media files (CSS, JS, images, fonts, …) of the module.

Its language files are as follows for the default en-GB English (United Kingdom) language:

  • language/en-GB/mod_something.sys.ini. Mandatory. Used to display information about the module, and display its edit (options) page.
  • language/en-GB/mod_something.ini. Optional. Any other language strings the module may need at runtime.

An administrator module mod_something installs its files in the following subdirectories:

  • administrator/modules/mod_something. Mandatory. The main files of the module. The module's XML manifest and installation script (if any) is always stored in here as well. The modules's XML manifest SHOULD be called something.xml, but this is currently not enforced; support for names other than something.xml is currently deprecated and might be removed in a future version of Joomla.
  • media/mod_something. Optional. The optional media files (CSS, JS, images, fonts, …) of the module.

⚠️ There is a naming collision for a same-named site and administrator module when it comes to media files. It is, therefore, customary for developers who would end up in this situation to name one of the modules, usually the administrator module, differently, e.g. mod_something and mod_admin_something, or mod_site_something and mod_admin_something, or something to that vein.

Its language files are as follows for the default en-GB English (United Kingdom) language:

  • administrator/language/en-GB/mod_something.sys.ini. Mandatory. Used to display information about the module, and display its edit (options) page.
  • administrator/language/en-GB/mod_something.ini. Optional. Any other language strings the module may need at runtime.

It is possible that these files are not present in those folders, but inside the module's main folder. However, this method of providing language files is considered deprecated and will be removed in a future version of Joomla.

Templates

Templates change the look and feel of your site.

Beyond being mere “themes”, Joomla templates can also override the output of components, modules, plugins (if they have customisable output), and layouts (small building blocks used throughout Joomla, or a specific extension). As such, they can modify the way your site operates, not just how it looks.

There are two types of templates: frontend (site) and backend (administrator). Each type of template can only be used in its corresponding part of your site, i.e. a site template will only work in the public frontend of your site.

Templates are internally named as tpl_something wheresomething is a unique identifier for this template within the specific part of your site (site or administrator).

A site template tpl_something installs its files in the following subdirectories:

  • templates/tpl_something Mandatory. The main files of the template. The template's XML manifest and installation script (if any) is always stored in here as well. The XML manifest MUST be called templateDetails.xml. This is completely different than any other extension type!
  • media/templates/site/tpl_something. Since Joomla! 4.2. The optional media files of the template. Before Joomla! 4.2, and for legacy templates, media files are stored under the template's main directory. However, legacy templates CANNOT have child templates.

Its language files are as follows for the default en-GB English (United Kingdom) language:

  • language/en-GB/tpl_something.sys.ini Mandatory. Used to display information about the template, and display its edit (options) page.
  • language/en-GB/tpl_something.ini Optional. Any other language strings the template may need at runtime.

An administrator template tpl_something installs its files in the following subdirectories:

  • administrator/templates/tpl_something Mandatory. The main files of the template. The template's XML manifest and installation script (if any) is always stored in here as well. The XML manifest MUST be called templateDetails.xml. This is completely different than any other extension type!
  • media/templates/administrator/tpl_something. Since Joomla! 4.2. The optional media files of the template. Before Joomla! 4.2, and for legacy templates, media files are stored under the template's main directory. However, legacy templates CANNOT have child templates.

Its language files are as follows for the default en-GB English (United Kingdom) language:

  • administrator/language/en-GB/tpl_something.sys.ini Mandatory. Used to display information about the template, and display its edit (options) page.
  • administrator/language/en-GB/tpl_something.ini Optional. Any other language strings the template may need at runtime.

Libraries

Libraries are collections of common code which can be used across multiple extensions. They are conceptually the same as drivers and DLL files on Windows.

For example, a third party developer may put all the code which is common across their extensions into a library package. Major developers like Regular Labs do that. We used to do that, too, when we were using our FOF framework for our extensions.

With the advent of Composer and its major improvements over the years Library packages are becoming less common. Instead of installing a library and manage its different versions and all the mess that comes from different software requiring different versions of the same library it's more practical to include the code necessary as a privately namespaced Composer dependency within each extension.

⚠️ Before Joomla! 1.6 there were no Library extensions. Developers included their library code in their extensions, or installed it to the site's libraries folder using custom code. This method was supported during Joomla! 3.x. Ever since Joomla! 3.10 this packaging method will cause problems when updating Joomla to a newer minor or major version, therefore it's considered a wrong way to package library code.

Libraries are internally named as lib_something wheresomething is a unique identifier for this library.

Libraries are always installed in a subdirectory of the site's libraries directory.

A library lib_something installs its manifests in the administrator/manifests/libraries directory. Any installation script is stored in the administrator/manifests/libraries/something directory.

Its language files are as follows for the default en-GB English (United Kingdom) language:

  • language/en-GB/lib_something.sys.ini Mandatory. Used to display information about the library.
  • language/en-GB/lib_something.sys Optional. In case the library needs to load further language strings on-demand.

File

When there are files that need to be installed in Joomla but fall into none of the previous categories we have File packages.

These days, File packages are mainly used for installable translations.

Other common uses for File packages is to install scripts which run outside of Joomla, or JavaScript / CSS libraries which are placed in a subdirectory of the site's media directory.

⚠️ Before Joomla! 1.6 there were no File extensions. Language packages were a special case, or the files had to be copied manually. These workarounds have been considered the wrong way to package languages since 2012.

File packages are internally named as file_something. In older versions of Joomla they were named files_something (note the plural). If you see something using the plural it's very likely a legacy files package from the early aughts.

The installation path of files included in the file package is entirely up to the file package itself. That's their whole point of existence, really.

A file package file_something installs its manifests in the administrator/manifests/files directory (note the plural in the directory name). Any installation script is stored in the administrator/manifests/files/file_something directory (note the singular in the prefix).

Its language files are as follows for the default en-GB English (United Kingdom) language:

  • language/en-GB/files_something.sys.ini Mandatory. Used to display information about the files package.

Note the plural in the name.

⚠️ The inconsistency between the use of file (singular) and files (plural) in the way Joomla handles file packages is infuriating, arbitrary, and the cause of many mistakes. There's a reason nobody uses them for anything other than language files anymore!

Package

Package extensions are a special extension type. They contain no code. Instead, they contain a packing list of other extensions (components, modules, plugins, templates, libraries, files) to install on your site.

Package extensions are the main way of installing non-trivial software for Joomla. Usually, they contain a component, and a number of associated module, plugins, and library files. Sometimes they may only contain closely related modules, or plugins but no component.

⚠️ Back in Joomla! 1.0 and 1.5 there were no Package extensions. Developers published a component or plugin extension with custom code to install additional extensions such as modules, plugins, etc. This packaging method became obsolete in 2012 with the release Joomla! 2.5. Using this packaging method was still possible, but strongly discouraged, during Joomla! 3.x. Ever since Joomla! 3.10 this packaging method will cause problems when updating Joomla to a newer minor or major version, therefore it's considered a wrong way to package extensions.

Package extensions are internally named as pkg_something.

Packages do not have files to install per se. For more details about what they do please consult How packages work.

A package extension pkg_something installs its manifests in the administrator/manifests/packages directory (note the plural in the directory name). Any installation script is stored in the administrator/manifests/packages/something directory.

Its language files are as follows for the default en-GB English (United Kingdom) language:

  • language/en-GB/pkg_something.sys.ini Mandatory. Used to display information about the package extension.

Language handling

While the .sys.ini files are listed are mandatory, it doesn't mean that all extensions ship with one. It is possible that some extensions, especially package extensions, don't ship with any language files if they have the name of the extension and its description hardcoded as human-readable text in the XML manifest. This is considered a bad practise, but it does happen frequently especially because product names are hardly ever translatable.

All .sys.ini files are loaded automatically as needed.

Components' .ini (not .sys.ini) files are loaded by default for the current application when the component is accessed, e.g. language/en-GB/com_something.ini is loaded automatically when the component is accessed in the frontend. This behaviour can be changed programmatically.

All other language files are loaded programmatically, hopefully only when they are likely to be needed. We say “hopefully” because that's up to the developer, and parsing language files does increase the page load time by a few tenthds of a millisecond per file.