diff --git a/README.md b/README.md index beac9de3..7e0e9f67 100644 --- a/README.md +++ b/README.md @@ -91,6 +91,8 @@ Don't use colons (:) in titles. Don't use `
` to force a new line (eg in table text); use `
` instead. +Don't use subdirectory names which match somewhat the parent directory name. For example, avoid `./install-update/install/`, as this can cause docusaurus to report broken links. + ### Docusaurus Additions You won't see the effect of these when you preview the Markdown text, but you will see them by previewing the Pull Request. diff --git a/docs/building-extensions/install-update/install/_assets/changelog-manage.jpg b/docs/building-extensions/install-update/installation/_assets/changelog-manage.jpg similarity index 100% rename from docs/building-extensions/install-update/install/_assets/changelog-manage.jpg rename to docs/building-extensions/install-update/installation/_assets/changelog-manage.jpg diff --git a/docs/building-extensions/install-update/install/_assets/changelog-update.jpg b/docs/building-extensions/install-update/installation/_assets/changelog-update.jpg similarity index 100% rename from docs/building-extensions/install-update/install/_assets/changelog-update.jpg rename to docs/building-extensions/install-update/installation/_assets/changelog-update.jpg diff --git a/docs/building-extensions/install-update/install/_assets/changelog.jpg b/docs/building-extensions/install-update/installation/_assets/changelog.jpg similarity index 100% rename from docs/building-extensions/install-update/install/_assets/changelog.jpg rename to docs/building-extensions/install-update/installation/_assets/changelog.jpg diff --git a/docs/building-extensions/install-update/install/change-log.md b/docs/building-extensions/install-update/installation/change-log.md similarity index 96% rename from docs/building-extensions/install-update/install/change-log.md rename to docs/building-extensions/install-update/installation/change-log.md index 3d276c3c..52383985 100644 --- a/docs/building-extensions/install-update/install/change-log.md +++ b/docs/building-extensions/install-update/installation/change-log.md @@ -1,130 +1,130 @@ ---- -sidebar_position: 3 -title: Changelogs ---- - -Changelogs -========== - -Extension developers can leverage the ability of Joomla to read a changelog file and give a visual representation of the changelog. If a given version is not found in the changelog, the changelog button will not be shown. - -The changes in a release are presented in this manner: - -![Changelog display](./_assets/changelog.jpg) - -## Displaying the Changelog - -Changelogs can be displayed in 2 places within the Joomla administrator back-end. - -1. Manage Extensions - -![Manage Extensions display](./_assets/changelog-manage.jpg) - -You can click on the version number to display the changelog. - -To enable this you must specify in the extension installation manifest file where Joomla should look to find the changelog details, for example: - -```xml -https://example.com/updates/changelog.xml -``` - -Please note: The URL in the changelogurl tag must not have any spaces or line breaks before or after it. - -2. Update Extensions - -![Update Extensions display](./_assets/changelog-update.jpg) - -To enable this you must specify in the extension[ update server](../update-server.md) file where Joomla should look to find the changelog details, for example: - -```xml -https://example.com/updates/changelog.xml -``` - -:::note[Joomla Issue] - This feature does not currently work; see [Joomla issue 43505](https://issues.joomla.org/tracker/joomla-cms/43505). -::: - -## The Changelog File - -An example of a changelog file is below: - -```xml - - - com_lists - component - 4.0.0 - - Item A - Item b - - - Item A - Item b - - - Item A - Item b - - - Item A - Item b - - - Item A - Item b - - - Item A - Item b - - - Item A - Item b - - - - com_lists - component - 0.0.2 - - Big issue - - - -``` - -You may specify multiple `` elements within the `` element, one for each version of the extension. - -Each `` element must have the following 3 nodes: -- element -- type -- version - -This information is used to identify the correct changelog for a given extension, for example: - -```xml -com_lists -component -4.0.0 -``` - -The changelog contains one or more change types. The following change types are supported: -- security: Any security issues that have been fixed -- fix: Any bugs that have been fixed -- language: This is for language changes -- addition: Any new features added -- change: Any changes -- remove: Any features removed -- note: Any extra information to inform the user - -Each node can be repeated as many times as needed. - -The format of the text can be plain text or HTML but in case of HTML, it must be enclosed in CDATA tags as in: - -```xml - - You MUST replace this file]]> - -``` - +--- +sidebar_position: 3 +title: Changelogs +--- + +Changelogs +========== + +Extension developers can leverage the ability of Joomla to read a changelog file and give a visual representation of the changelog. If a given version is not found in the changelog, the changelog button will not be shown. + +The changes in a release are presented in this manner: + +![Changelog display](./_assets/changelog.jpg) + +## Displaying the Changelog + +Changelogs can be displayed in 2 places within the Joomla administrator back-end. + +1. Manage Extensions + +![Manage Extensions display](./_assets/changelog-manage.jpg) + +You can click on the version number to display the changelog. + +To enable this you must specify in the extension installation manifest file where Joomla should look to find the changelog details, for example: + +```xml +https://example.com/updates/changelog.xml +``` + +Please note: The URL in the changelogurl tag must not have any spaces or line breaks before or after it. + +2. Update Extensions + +![Update Extensions display](./_assets/changelog-update.jpg) + +To enable this you must specify in the extension[ update server](../update-server.md) file where Joomla should look to find the changelog details, for example: + +```xml +https://example.com/updates/changelog.xml +``` + +:::note[Joomla Issue] + This feature does not currently work; see [Joomla issue 43505](https://issues.joomla.org/tracker/joomla-cms/43505). +::: + +## The Changelog File + +An example of a changelog file is below: + +```xml + + + com_lists + component + 4.0.0 + + Item A + Item b + + + Item A + Item b + + + Item A + Item b + + + Item A + Item b + + + Item A + Item b + + + Item A + Item b + + + Item A + Item b + + + + com_lists + component + 0.0.2 + + Big issue + + + +``` + +You may specify multiple `` elements within the `` element, one for each version of the extension. + +Each `` element must have the following 3 nodes: +- element +- type +- version + +This information is used to identify the correct changelog for a given extension, for example: + +```xml +com_lists +component +4.0.0 +``` + +The changelog contains one or more change types. The following change types are supported: +- security: Any security issues that have been fixed +- fix: Any bugs that have been fixed +- language: This is for language changes +- addition: Any new features added +- change: Any changes +- remove: Any features removed +- note: Any extra information to inform the user + +Each node can be repeated as many times as needed. + +The format of the text can be plain text or HTML but in case of HTML, it must be enclosed in CDATA tags as in: + +```xml + + You MUST replace this file]]> + +``` + diff --git a/versioned_docs/version-4.4/building-extensions/install-update/install/index.md b/docs/building-extensions/install-update/installation/index.md similarity index 96% rename from versioned_docs/version-4.4/building-extensions/install-update/install/index.md rename to docs/building-extensions/install-update/installation/index.md index af75f882..03c784a0 100644 --- a/versioned_docs/version-4.4/building-extensions/install-update/install/index.md +++ b/docs/building-extensions/install-update/installation/index.md @@ -1,10 +1,10 @@ ---- -sidebar_position: 1 -title: Installing Extensions ---- - -This section covers: -- how to install extensions - by means of a Manifest File -- the overall installation process, and how you can write a Script File to interact with it -- the ChangeLog File -- packages +--- +sidebar_position: 1 +title: Installing Extensions +--- + +This section covers: +- how to install extensions - by means of a Manifest File +- the overall installation process, and how you can write a Script File to interact with it +- the ChangeLog File +- packages diff --git a/versioned_docs/version-4.4/building-extensions/install-update/install/install-process.md b/docs/building-extensions/install-update/installation/install-process.md similarity index 97% rename from versioned_docs/version-4.4/building-extensions/install-update/install/install-process.md rename to docs/building-extensions/install-update/installation/install-process.md index d397248a..92f23fcd 100644 --- a/versioned_docs/version-4.4/building-extensions/install-update/install/install-process.md +++ b/docs/building-extensions/install-update/installation/install-process.md @@ -1,149 +1,149 @@ ---- -sidebar_position: 2 -title: Install Process and Script Files ---- - -Install Process and Script Files -================================ - -This section provides an overview of the extension install process, and how you can write a Script File to interact with it. - -An installation script file is a class with 5 functions: -- preflight - called at the start of the install process -- install, update, uninstall - called part way through the process: - - install is called when the operation is an initial install of an extension - - update is called when the operation is an install of an existing extensions - - uninstall is called when the operation is a removal of an extension -- postflight - called at the end of the install process - -You can also interact with the process by writing installation plugins which listen for the events described below. - -## Installation Process - -There are various methods for installing an extension in Joomla, and various types of extension, but ultimately, the installation process follows a similar pattern for all. - -When you go to install extensions and select a zip file of an extension to install then this is an overview of what happens: -(If you want to step through this process in a debugger then set a break at administrator/components/com_installer/src/Model/InstallModel.php::install) -- imports the "installer" type plugins, and triggers the 'onInstallerBeforeInstallation' event -- the zip file is stored in the Joomla /tmp folder, and then unzipped into a subfolder of /tmp -- triggers the 'onInstallerBeforeInstaller' event -- triggers the 'onExtensionBeforeInstall' event -- loads the .sys.ini language file from the new install files (or failing that, from the existing extension directory) -- reads basic information about the extension from the manifest file, for example, the type of the extension -- performs a `require_once` of the installer script file -- calls the script file `preflight` function -- copies the extension files from the /tmp folder to their place within the Joomla instance - for example, when installing a site module mod_example, the code would be copied to /modules/mod_example -- writes / updates the extension record in the database (ie this extension's record in the `#__extensions` table) -- performs any functionality specific to that extension type. For example, for new installs of modules it creates a record in the `#__modules` table -- applies any database changes required by this install. -- calls the script file `install` / `update` / `uninstall` function -- tidy-up: - - If there's a record in the `#__updates` table saying that there's a new version available for this extension then it deletes it. - - It copies the manifest file into the target extension directory (for components this will be the component directory under /administrator) -- calls the script file `postflight` function -- triggers the 'onExtensionAfterInstall' event -- triggers the 'onInstallerAfterInstaller' event -- performs some further tidy-up, eg deleting the temporary installation files - -## Example Script File - -The easiest way to write a script file is to use the \Joomla\CMS\Installer\InstallerScriptInterface definition in libraries/src/Installer/InstallerScriptInterface.php. -You simply have to return an instance of a class which implements the 5 installer functions. - -You can either -1. Return an anonymous Script File class which implements InstallerScriptInterface, or -2. Return an anonymous service provider class which puts the Script File class into the Dependency Injection Container using a key InstallerScriptInterface::class. Joomla will then `get` that Script File class from the DIC. - -The example below uses the second approach. - -For an example of the first approach see the [Module Tutorial Step 6](../../modules/module-development-tutorial/step6-script-file.md). - -```php -set( - InstallerScriptInterface::class, - new class ( - $container->get(AdministratorApplication::class), - $container->get(DatabaseInterface::class) - ) implements InstallerScriptInterface { - private AdministratorApplication $app; - private DatabaseInterface $db; - - public function __construct(AdministratorApplication $app, DatabaseInterface $db) - { - $this->app = $app; - $this->db = $db; - } - - public function install(InstallerAdapter $parent): bool - { - $this->app->enqueueMessage('Successful installed.'); - - return true; - } - - public function update(InstallerAdapter $parent): bool - { - $this->app->enqueueMessage('Successful updated.'); - - return true; - } - - public function uninstall(InstallerAdapter $parent): bool - { - $this->app->enqueueMessage('Successful uninstalled.'); - - return true; - } - - public function preflight(string $type, InstallerAdapter $parent): bool - { - return true; - } - - public function postflight(string $type, InstallerAdapter $parent): bool - { - $this->deleteUnexistingFiles(); - - return true; - } - - private function deleteUnexistingFiles() - { - $files = []; // overwrite this line with your files to delete - - if (empty($files)) { - return; - } - - foreach ($files as $file) { - try { - File::delete(JPATH_ROOT . $file); - } catch (\FilesystemException $e) { - echo Text::sprintf('FILES_JOOMLA_ERROR_FILE_FOLDER', $file) . '
'; - } - } - } - } - ); - } -}; -``` +--- +sidebar_position: 2 +title: Install Process and Script Files +--- + +Install Process and Script Files +================================ + +This section provides an overview of the extension install process, and how you can write a Script File to interact with it. + +An installation script file is a class with 5 functions: +- preflight - called at the start of the install process +- install, update, uninstall - called part way through the process: + - install is called when the operation is an initial install of an extension + - update is called when the operation is an install of an existing extensions + - uninstall is called when the operation is a removal of an extension +- postflight - called at the end of the install process + +You can also interact with the process by writing installation plugins which listen for the events described below. + +## Installation Process + +There are various methods for installing an extension in Joomla, and various types of extension, but ultimately, the installation process follows a similar pattern for all. + +When you go to install extensions and select a zip file of an extension to install then this is an overview of what happens: +(If you want to step through this process in a debugger then set a break at administrator/components/com_installer/src/Model/InstallModel.php::install) +- imports the "installer" type plugins, and triggers the 'onInstallerBeforeInstallation' event +- the zip file is stored in the Joomla /tmp folder, and then unzipped into a subfolder of /tmp +- triggers the 'onInstallerBeforeInstaller' event +- triggers the 'onExtensionBeforeInstall' event +- loads the .sys.ini language file from the new install files (or failing that, from the existing extension directory) +- reads basic information about the extension from the manifest file, for example, the type of the extension +- performs a `require_once` of the installer script file +- calls the script file `preflight` function +- copies the extension files from the /tmp folder to their place within the Joomla instance - for example, when installing a site module mod_example, the code would be copied to /modules/mod_example +- writes / updates the extension record in the database (ie this extension's record in the `#__extensions` table) +- performs any functionality specific to that extension type. For example, for new installs of modules it creates a record in the `#__modules` table +- applies any database changes required by this install. +- calls the script file `install` / `update` / `uninstall` function +- tidy-up: + - If there's a record in the `#__updates` table saying that there's a new version available for this extension then it deletes it. + - It copies the manifest file into the target extension directory (for components this will be the component directory under /administrator) +- calls the script file `postflight` function +- triggers the 'onExtensionAfterInstall' event +- triggers the 'onInstallerAfterInstaller' event +- performs some further tidy-up, eg deleting the temporary installation files + +## Example Script File + +The easiest way to write a script file is to use the \Joomla\CMS\Installer\InstallerScriptInterface definition in libraries/src/Installer/InstallerScriptInterface.php. +You simply have to return an instance of a class which implements the 5 installer functions. + +You can either +1. Return an anonymous Script File class which implements InstallerScriptInterface, or +2. Return an anonymous service provider class which puts the Script File class into the Dependency Injection Container using a key InstallerScriptInterface::class. Joomla will then `get` that Script File class from the DIC. + +The example below uses the second approach. + +For an example of the first approach see the [Module Tutorial Step 6](../../modules/module-development-tutorial/step6-script-file.md). + +```php +set( + InstallerScriptInterface::class, + new class ( + $container->get(AdministratorApplication::class), + $container->get(DatabaseInterface::class) + ) implements InstallerScriptInterface { + private AdministratorApplication $app; + private DatabaseInterface $db; + + public function __construct(AdministratorApplication $app, DatabaseInterface $db) + { + $this->app = $app; + $this->db = $db; + } + + public function install(InstallerAdapter $parent): bool + { + $this->app->enqueueMessage('Successful installed.'); + + return true; + } + + public function update(InstallerAdapter $parent): bool + { + $this->app->enqueueMessage('Successful updated.'); + + return true; + } + + public function uninstall(InstallerAdapter $parent): bool + { + $this->app->enqueueMessage('Successful uninstalled.'); + + return true; + } + + public function preflight(string $type, InstallerAdapter $parent): bool + { + return true; + } + + public function postflight(string $type, InstallerAdapter $parent): bool + { + $this->deleteUnexistingFiles(); + + return true; + } + + private function deleteUnexistingFiles() + { + $files = []; // overwrite this line with your files to delete + + if (empty($files)) { + return; + } + + foreach ($files as $file) { + try { + File::delete(JPATH_ROOT . $file); + } catch (\FilesystemException $e) { + echo Text::sprintf('FILES_JOOMLA_ERROR_FILE_FOLDER', $file) . '
'; + } + } + } + } + ); + } +}; +``` diff --git a/versioned_docs/version-4.4/building-extensions/install-update/install/manifest.md b/docs/building-extensions/install-update/installation/manifest.md similarity index 97% rename from versioned_docs/version-4.4/building-extensions/install-update/install/manifest.md rename to docs/building-extensions/install-update/installation/manifest.md index b5dc433b..5f52ce51 100644 --- a/versioned_docs/version-4.4/building-extensions/install-update/install/manifest.md +++ b/docs/building-extensions/install-update/installation/manifest.md @@ -1,512 +1,512 @@ ---- -sidebar_position: 1 -title: Manifest Files ---- - -Manifest Files -============== - -You install Joomla extensions by means of a manifest XML file, and there are many Joomla examples which you can use as a basis for your own extension: -- components - in administrator/components, eg administrator/components/com_contact/contact.xml -- modules - in modules or administrator/modules, eg modules/mod_breadcrumbs/mod_breadcrumbs.xml -- plugins - in plugins, eg plugins/system/remember/remember.xml -- templates - in templates or administrator/templates, eg administrator/templates/atum/templateDetails.xml -- languages - in language or administrator/language, eg language/en-GB/install.xml - -This section covers the detailed definition of the XML in a Manifest File. - -## File Naming Convention - -It is important that you name your manifest file correctly. Otherwise you may find that your extension installs, but that your extension's namespace isn't built correctly, and your extension doesn't run. - -Here are the naming rules for the different extension types (as listed in [Building Extensions](../../../building-extensions/index.md)): - -**Components**: for a component called com_example you can use either com_example.xml or example.xml. - -**Modules**: for a module mod_example use mod_example.xml. This must match the module name given in your manifest `` section - -```xml - - services - ... - -``` - -or if you don't yet use a services/provider.php file: - -```xml - - mod_example.php - ... - -``` - -**Plugins**: for a plugin plg_example use example.xml. This must match the plugin name given in your manifest `` section - -```xml - - services - ... - -``` - -or if you don't yet use a services/provider.php file: - -```xml - - example.php - ... - -``` - -**Templates**: your manifest file must be named templateDetails.xml - -**Language**: use install.xml - -**File**, **Library**, **Package**: you can use any name, but libraries are usually named lib_example.xml and packages pkg_example.xml. - -For components, modules and plugins the manifest file must match the 'element' field of your extension's record in the `#__extensions` table (except that for components the "com_" prefix may be omitted). -The 'element' is the internal name within Joomla of the extension. - -In priority order the 'element' database field is set -- from the `` in the manifest file, or -- from the "module=" or "plugin=" attribute in the ``, or -- from the `` (after the text is cleaned). - -## Root Element - -The primary tag of the installation file is - -```xml - -... - -``` - -This starting and closing tag is the same for all extensions. The following attributes are allowed within the tag: - -| Attribute | Values | Applicable To | Description | -| --------------------------------- | ---------------- | ---------------- | -------------------------------------------------------- | -| type | component
file
language
library
module
package
plugin
template | All extensions | | -| method | install
upgrade | All extensions | The install value (default) means the installer will gracefully stop if it finds any existing file/folder of the new extension
The upgrade value allows you to install an upgraded version on top of the existing version | -| client | site
administrator | Modules | Defines whether the module is a front-end site module or back-end administrator module | -| group | *string* | Plugins | The group name specifies for which group of plugins the new plugin is available.
The existing groups are the folder names within the directory /plugins.
The installer will create new folder names for group names that do not exist yet. | - -## Metadata - -The following elements can be used to insert metadata. Although not strictly required, you should define at least the ``, ``, `` and `` tags, all of which are used on the default administrator Manage Extensions form. - -```xml - – extension name (e.g. com_banners). - – author's name (e.g. Joomla! Project) - – date of creation or release (e.g. April 2006) - – a copyright statement (e.g. (C) 2020 - 2030 Open Source Matters. All rights reserved.) - – a license statement (e.g. GNU General Public License version 3 or later; see LICENSE.txt) - – author's email address (e.g. admin@joomla.org) - – URL to the author's website (e.g. www.joomla.org) - – the version number of the extension (e.g. 1.6.0) - – the description of the component (may be shown as a tooltip on the admin Manage Extensions page) - – the internal name of the component. If omitted, name will be cleaned and used -``` - -The `` and `` fields are translatable. If you use language strings for these elements then they should be defined in your language .sys.ini file AND your .ini file. - -## Front-end Files - -```xml - - example.php - examples - -``` - -This is used to copy files from your development "from-folder" into the front-end directory of your installed extension. -You can either identify files individually using `` or copy a complete directory using ``. - -For plugins and modules you should identify the entry point of your code. -If you are using dependency injection within your module or plugin and have a services/provider.php file then use - -```xml - services -or - services -``` - -Here "mod_example" / "example" is the internal name (aka 'element') of your module / plugin. - -If you are not using a services/provider.php file then point to the specific filename: - -```xml - mod_example.php -or - example.php -``` - -## Media Files - -This categories covers: -- your javascript files -- your css files -- any images which are inheritently part of your extension (ie not something an administrator should be able to change). - -(For an example of these sorts of images, consider the flag symbols in media/mod_languages/images/ which are used by the language switcher.) - -In your development area you should store these in separate folders: js/, css/, images/ then use - -```xml - - js - css - images - -``` - -The installer will move these folders into media/com_example/js, media/com_example/css and media/com_example/images, creating the com_example folder if required. - -This media folder is used for both the site front-end and the administrator back-end. - -## Administration section - -```xml - - - -``` - -The administration section is defined in the `` element. Since only components apply to both the site and the administrator, only component manifests can include this element. - -### Administrator Back-end Files - -Files to copy below the administrator directory should be placed in the `` element under the `` and can be used to copy individual files or complete folders, as described above for front-end files. - -### Administrator Menu Links and Submenus - -This maps to menu and submenu links for your component in the administrator sidebar menu (under Components). - -```xml - - COM_EXAMPLE - - - COM_EXAMPLE_SUBMENU_ANOPTION - COM_EXAMPLE_SUBMENU_VIEWNAME - - -``` - -Each `` item can define the following attributes: - -| Attribute | Description | -| ------------------ | ------------------------------------------------------------------------ | -| link | A link to send the user to when the menu item is clicked. You can use "view" instead. | -| view | An URL parameter to add to the link.
For example, `COM_EXAMPLE` in com_example's XML manifest would cause the URL of the menu item to be index.php?option=com_example&view=cpanel.
You can use "link" instead. | -| img | The (relative) path to an image (16x16 pixels) to appear beside the menu item.
Must be an url compatible as a file too (e.g. no spaces) ! | -| alt | alt text for the link | - -You can also create links to dashboards - see the following section for details. - -The value inside the tag is the menu's label. If you use language strings inside these elements then they should be defined in your component's .sys.ini file. - -The installer creates entries in the `#__menu` table for these menu items, and Joomla loads from the database these entries when it builds the administrator menu. - -(Administrator menu items for components such as com_content are defined in the component's preset folder, eg in administrator/components/com_content/presets/content.xml). - -## Dashboards - -You create a dashboard for your component using - -```xml - - example - -``` - -When your component is installed then you can navigate to your dashboard using - -``` -administrator/index.php?option=com_cpanel&view=cpanel&dashboard=example -``` - -This will display at the top the `title` and `icon`, but will initially be empty. -You can define items for your dashboard using a preset and / or by adding administrator modules to it using the position `cpanel-example`, as described in [Dashboard](../../../general-concepts/dashboard.md). - -To create a link to your dashboard use (in your administrator menu section): - -```xml - - COM_EXAMPLE - - example - - - -``` - -The text "example" within the `` tags must match the text within the corresponding tags in the `` element. - -## Configuration - -For modules, plugins and templates you can define configuration using a `` section. -Within the `` tags you specify the configuration fields as described in [Form Fields](../../../general-concepts/forms-fields/index.md). - -There are many examples among the Joomla extensions, see mod_breadcrumbs for example. - -The configuration is defined by navigating to the administrator Manage Modules / Manage Plugins / Template Styles functionality. - -You cannot use `` for defining configuration for components. -For details of how to provide component configuration see [Developing an MVC Component/Adding configuration](https://docs.joomla.org/J3.x:Developing_an_MVC_Component/Adding_configuration), which (though written for Joomla 3) is still applicable. - -:::note[TODO] - Update the above link when the MVC Component Tutorial is included in the manual. -::: - -## Namespace - -Define the namespace prefix for your extension using: - -```xml -Mycompany\Component\Example -``` - -See the manual [Namespace](../../../general-concepts/namespaces/index.md) section for details. - -## SQL - -The SQL section (primarily used by components) enables you to make changes to the database data owned by your extension. - -There are 3 types of changes: -1. **Install** Initial database setup for your extension, for the first version of your extension (or, at least, the first version which configures the database). -2. **Update** Database changes to be applied upgrading to this version from the previous version -3. **Uninstall** Database changes to be applied when the extension is uninstalled. - -For each type of database (eg mysql) you will have: -- 1 SQL file for the install -- 1 SQL file for the uninstall -- a folder containing several update SQL files, each enabling upgrading from the previous version to the current - -Each SQL file contains a series of SQL statements, with table names using the '#__' prefix, eg '#__categories'. - -By convention all these sql files are stored in a folder called "sql" within the administrator folder, which you must define within your administrator files section, eg - -```xml - - - sql - - -``` - -For your install file: - -```xml - - - sql/example.install.sql - - -``` - -You can have several `` elements, for different database drivers. - -For your uninstall file(s): - -```xml - - - sql/example.uninstall.sql - - -``` - -For your update files: - -```xml - - - sql/updates/mysql - - -``` - -where, for example, sql/updates/mysql contains a series of files, eg: -- 0.0.2.sql (for upgrading to v0.0.2) -- 0.0.3.sql (for upgrading from v0.0.2 to v0.0.3), etc. -- 0.0.4.sql (for upgrading from v0.0.3 to v0.0.4), etc. - -If the first version you install is eg 0.0.4 then Joomla will use the initial example.install.sql file, and then apply in order the update files to arrive at v0.0.4. - -If you install one version of the extension then skip some versions before installing the next, then Joomla applies each of the update sql files to go from your previous version to the one you're installing. - -The currently installed version is maintained in the `#__schemas` table. -You can find a worked example in [Developing an MVC Component/Using the database](https://docs.joomla.org/J3.x:Developing_an_MVC_Component/Using_the_database). - -:::note[TODO] - Update the above link when the MVC Component Tutorial is included in the manual. -::: - -## Languages - -You specify your language ini files in a structure like this: - -``` -language - ├─── en-GB - │ ├─── mod_hello.ini - │ └─── mod_hello.sys.ini - └─── fr-FR - ├─── mod_hello.ini - └─── mod_hello.sys.ini -``` - -The subfolder name (eg en-GB) must match the language code of the language your extension is supporting. -You can find the list of all languages supported by Joomla (together with their language codes) via the [Joomla Language Downloads](https://downloads.joomla.org/language-packs). - -(For historical reasons Joomla also supports the language file names being prefixed with the language code, eg en-GB.mod_hello.ini). - -There are 2 ways which you can use to install your extension's language files. - -1. Using the `` tag - -```xml - - com_example.ini - com_example.sys.ini - -``` - -Joomla will copy your language files (from the folder specified in the 'folder' attribute) into the appropriate Joomla language folder: -- under /language for the site front-end (site modules, site templates and components when the `` tag is immediately inside ``). -- under /administrator/language for the administrator back-end (plugins, administrator modules, administrator templates and components when the `` tag is inside ``). - -In your code you can then load your .ini language file using (eg for mod_example): - -```php -Factory::getApplication()->getLanguage()->load('mod_example'); -``` - -2. Copying from a language folder - -```xml - - language - -or - - - language - - -``` - -This will simply copy your 'language' folder into the target folder of your extension. -In this case, you must name your folder "language", as this is the name of the folder where Joomla will look to find your language files. - -To load your .ini language file you must pass the base path for your extension (eg for site module mod_example): - -```php -Factory::getApplication()->getLanguage()->load('mod_example', JPATH_BASE . '/modules/mod_example'); -``` - -The advantage of this second approach is that the language files continue to be closely associated with your extension. - -If an administrator uninstalls a language then -- for option 1 your extension's language files will be deleted -- for option 2 your extension's language files will remain. - -If the administrator then reinstalls the removed language then -- for option 1 your extension will need to be reinstalled to restore its language files for the reinstalled language -- for option 2 no further action is needed. - -## Script File - -```xml -script.php -``` - -This specifies the filename of a script file containing PHP code which is run during the installation process. It is described in [Install Process and Script Files](./install-process.md). - -## Library Files - -This is specific to a manifest of type "library". - -```xml -mylib -``` - -Joomla will treat libraries/mylib as the target directory, and any files and folders will be copied under it. - -If your company has several libraries and you want to group them together under the folder JPATH_SITE/libraries/mycompany then include your company name in the `` tag of each library: - -```xml -mycompany/mylib1 -``` - -```xml -mycompany/mylib2 -``` - -These libraries will then be installed in the JPATH_SITE/libraries/mycompany/mylib1 and JPATH_SITE/libraries/mycompany/mylib2 folders. -Uninstalling mylib1 will still leave mylib2 installed on your site. - -## Update Server - -```xml - - http://example.com/extension.xml - http://example.com/collection.xml - -``` - -Please see [Update Servers](../update-server.md). - -## Changelog - -Specify the URL of the changelog description for this version of your extension: - -```xml -https://example.com/updates/changelog.xml -``` - -The URL in the `` tag must not have any spaces or line breaks before or after it. - -See the section on [ChangeLogs](./change-log.md). - -## Download Keys - -Users can enter their download keys via the Update Sites list, which provides a single place to manage them. -When a user is going to update an extension, Joomla will check if there is a download key. If there is a download key, Joomla will add the download key to the update URL. - -To support download keys you must include the dlid tag in the manifest file. The dlid tag takes 2 arguments: -- prefix -- suffix - -The dlid tag will look like this in your manifest file: - -```xml - -``` - -The prefix will be added before the download key and the suffix after the download key. Using the example above the full query added to the download link will be: - -``` -dlid=KEY&dummy=my.zip -``` - -The key is added before the `onInstallerBeforePackageDownload` event is triggered, so the full URL will be passed to the event. - -## Summary - -This documents which manifest elements are supported during which installation of an extension. - -| Component | File | Language | Library | Module | Package | Plugin | Template | -| :-------: | :--: | :------: | :-----: | :----: | :-----: | :----: | :------: | -| `` | yes | yes | no | no | yes | no | yes | no | -| `` | yes | yes | no | yes | yes | yes | yes | yes | -| `` | no | no | yes | no | no | no | no | no | -| `` | yes | no | yes | yes | yes | no | yes | yes | -| `` | no | no | no | no | yes | no | yes | yes | -| `