### Install Dependencies and Start Development Server Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/get-started/git/github-manual.md Installs project dependencies using npm and then starts the Docusaurus development server to view the local copy of the documentation. ```bash npm install npm run start ``` -------------------------------- ### Clone Manual Examples Repository Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/building-extensions/components/component-examples/index.md Use this command to clone the manual-examples repository to your local development machine for inspection or installation. ```sh git clone https://github.com/joomla/manual-examples.git ``` -------------------------------- ### Updater: Get and Set Adapter Example Source: https://github.com/joomla/manual/blob/main/updates/54-60/new-features.md Demonstrates how to retrieve an adapter instance and how to register a new adapter type in the updater. This is relevant for developers who might have extended or interacted with the updater's adapter system. ```php $adapter = $updater->getAdapter('extension'); $updater->setAdapter('mytype', MyAdapter::class); ``` -------------------------------- ### Hook into Installer Before Update Site Download Source: https://github.com/joomla/manual/blob/main/updates/52-53/new-features.md Example of an installer plugin method that intercepts the download process before the update site URL is fetched. It allows modification of the URL, such as appending authentication parameters. ```php public function onInstallerBeforeUpdateSiteDownload(\Joomla\CMS\Event\Installer\BeforeUpdateSiteDownloadEvent $event): void { $event->updateUrl($event->getUrl() . '?auth=foo'); } ``` -------------------------------- ### onInstallerBeforeInstallation Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/building-extensions/plugins/plugin-events/installer.md This event is triggered at the beginning of an installation operation. It can be used to control the installation process by returning true or false. ```APIDOC ## onInstallerBeforeInstallation ### Description This event is triggered at the beginning of an installation operation. ### Event Arguments The event class `\Joomla\CMS\Event\Installer\BeforeInstallationEvent` has the following arguments: - **`model`** - The instance of the install model class (\Joomla\Component\Installer\Administrator\Model\InstallModel) (This is actually the 'subject' element in the array returned by `$event->getArguments()`.) - **`package`** - This is null. ### Return Value A return value of true will cause the Joomla installer to exit with true (indicating that the extension was installed). A return value of false will cause the Joomla installer to exit with false (indicating that the extension installation failed). If you don't set a return value then the installation will continue as normal. You can also set the package as described for the event onInstallerBeforeInstaller below. ``` -------------------------------- ### Module Manifest File Example Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/building-extensions/install-update/installation/manifest.md Example of the section in a module's manifest file when using a services folder. ```xml services ... ``` -------------------------------- ### Module Manifest File Example (PHP file) Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/building-extensions/install-update/installation/manifest.md Example of the section in a module's manifest file when using a main PHP file. ```xml mod_example.php ... ``` -------------------------------- ### Configure Install SQL File Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/building-extensions/install-update/installation/manifest.md Specify the SQL file to be used for the initial installation of your extension's database schema. ```xml sql/example.install.sql ``` -------------------------------- ### Plugin Manifest File Example Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/building-extensions/install-update/installation/manifest.md Example of the section in a plugin's manifest file when using a services folder. ```xml services ... ``` -------------------------------- ### onInstallerBeforeInstaller Event Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/building-extensions/plugins/plugin-events/installer.md This event is triggered before the extension installation begins. It allows you to modify the package to be installed or to influence the installation process by returning true or false. ```APIDOC ## onInstallerBeforeInstaller ### Description This event is triggered before the extension installation begins. You can return true to indicate success, false to indicate failure, or a modified package to override the administrator's selection. ### Method `public function onInstallerBeforeInstaller( Joomla\CMS\Event\Installer\BeforeInstallerEvent $event ): void` ### Parameters This method does not directly accept parameters, but it operates on the `$event` object. ### Request Body N/A ### Request Example ```php public function onInstallerBeforeInstaller( Joomla\CMS\Event\Installer\BeforeInstallerEvent $event ): void { // Example: Override the package to be installed $newpkg = array("dir" => $pathToExtensionDirectory, "type" => "plugin", "extractdir" => null, "packagefile" => null); $event->updatePackage($newpkg); } ``` ### Response #### Success Response (true) Returns `true` to indicate successful installation and cause the Joomla installer to exit. #### Failure Response (false) Returns `false` to indicate a failed installation and cause the Joomla installer to exit. #### Default Behavior If no return value is set, the installation continues normally. #### Response Example N/A (Return values influence installer exit status) ``` -------------------------------- ### Plugin Manifest File Example (PHP file) Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/building-extensions/install-update/installation/manifest.md Example of the section in a plugin's manifest file when using a main PHP file. ```xml example.php ... ``` -------------------------------- ### onInstallerBeforeInstaller Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/building-extensions/plugins/plugin-events/installer.md This event is triggered after the extension code has been obtained and extracted, but before Joomla starts processing the extension's installation files. It provides access to extracted files and directories. ```APIDOC ## onInstallerBeforeInstaller ### Description This event is triggered after the extension code has been obtained, and any extraction of zip files performed, but before Joomla has started to process the extension's installation files. ### Event Arguments The event class `\Joomla\CMS\Event\Installer\BeforeInstallerEvent` has the following arguments: - **`model`** - The instance of the install model class (\Joomla\Component\Installer\Administrator\Model\InstallModel) (This is actually the 'subject' element in the array returned by `$event->getArguments()`.) - **`package`** - This is an array of 4 elements, which in the case of uploading a zip file will contain: - extractdir - the directory into which the zip file has been extracted - packagefile - the location of the zip file - dir - the directory containing the extension manifest file, and the other installation files - type - the type of extension (eg "plugin") The array elements vary depending upon how the installation code is selected. For example, for "Install from Folder" the extractdir and packagefile elements will be null. ``` -------------------------------- ### SQL File Example Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/building-extensions/plugins/plugin-examples/console-plugin-sqlfile.md Example SQL statements for creating and inserting data into a temporary table. The `#__` prefix will be automatically replaced with the Joomla table prefix. ```sql CREATE TABLE IF NOT EXISTS `#__temp_table` ( `s` VARCHAR(255) NOT NULL DEFAULT '', `i` INT NOT NULL DEFAULT 1, PRIMARY KEY (`i`) ); INSERT INTO `#__temp_table` (`s`, `i`) VALUES ('Hello', 22),('there', 23); ``` -------------------------------- ### Example Query Parameters Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/general-concepts/routing/build.md An example of the associative array of query parameters passed to the build method, with the menuitem Itemid set. ```php $query = array('Itemid' => '13', 'view' => 'article', 'id' => '21', catid => '50', ...) ``` -------------------------------- ### Example: Render Joomla Image Layout Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/general-concepts/layouts.md An example demonstrating how to render the 'joomla.html.image' layout to output an element with provided source and alt text. ```php use Joomla\CMS\Layout\LayoutHelper; $imageData = ['src' => 'images/joomla_black.png', 'alt' => 'Joomla logo']; echo LayoutHelper::render('joomla.html.image', $imageData); ``` -------------------------------- ### onInstallerAfterInstaller Event Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/building-extensions/plugins/plugin-events/installer.md This event is triggered after the extension has been installed. It allows you to set the installer result and message, though modifying the result at this stage has limited impact. ```APIDOC ## onInstallerAfterInstaller ### Description This event is triggered after an extension has been installed. You can use it to set a custom installer result and message. ### Method `public function onInstallerAfterInstaller( Joomla\CMS\Event\Installer\AfterInstallerEvent $event ): void` ### Event Arguments - **`model`** (`Joomla\Component\Installer\Administrator\Model\InstallModel`): The instance of the install model class. - **`package`** (array): The package that was installed. - **`installer`** (`Joomla\CMS\Installer\Installer`): The instance of the installer class. - **`installerResult`** (boolean): `true` if the package was successfully installed, `false` otherwise. - **`message`** (string): The message output to the administrator. ### Return Value You can set the installer result and message using the event object. ### Request Body N/A ### Request Example ```php public function onInstallerAfterInstaller( Joomla\CMS\Event\Installer\AfterInstallerEvent $event ): void { // Example: Set a custom failure message $event->updateInstallerResult(false); $event->updateMessage("Some failure message"); } ``` ### Response #### Success Response N/A (This event does not return a value directly, but can influence the installer's final message and status). #### Response Example N/A ``` -------------------------------- ### Install Dependencies with npm Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/get-started/git/github-joomla-cms.md Run this command in your terminal to install project dependencies. This is crucial for local testing, especially when changes involve javascript or css files. ```bash npm ci ``` -------------------------------- ### Install Dependencies Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/get-started/git/github-joomla-cms.md Install project dependencies using Composer and npm. This step is crucial for building a working Joomla! site from the development branch. ```bash composer install npm ci ``` -------------------------------- ### Start Docusaurus Development Server Source: https://github.com/joomla/manual/blob/main/about/contributing.md Starts a local development server for Docusaurus. Changes are usually reflected live without a server restart. ```bash npm run start ``` -------------------------------- ### Return HTML for an Additional Installation Tab in PHP Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/building-extensions/plugins/plugin-events/installer.md Use this to return the HTML content for an additional tab in the administrator Install / Extensions page. The `addResult` method is used to pass the tab's content. ```php $event->addResult($tabHTML); ``` -------------------------------- ### Get Menu Items by Menu Type and Level Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/general-concepts/menus-menuitems.md Retrieves menu items filtered by both menu type and specific levels. This example gets items from the 'mainmenu' that are either at the top level (1) or the first submenu level (2). ```php $mainmenuItems = $sitemenu->getItems(array('menutype','level'), array('mainmenu',array("1","2"))); ``` -------------------------------- ### Complete Menu Entry with Dashboard and Quicktasks Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/building-extensions/components/additional-topics/quicktasklink.md An example demonstrating a full menu entry including a dashboard link, submenu items, and quicktask configurations, one with a Font Awesome icon. ```xml COM_EXAMPLE example COM_EXAMPLE_MENU COM_EXAMPLE_MENU_QUICKTASK_TITLE index.php?option=com_example&view=example&layout=edit COM_EXAMPLE_MENU_CATEGORIES COM_EXAMPLE_MENU_CATEGORIES fas fa-person-hiking index.php?option=com_categories&view=category&layout=edit&extension=com_example COM_EXAMPLE_MENU_FIELDS COM_EXAMPLE_MENU_FIELDS_GROUP ``` -------------------------------- ### Update Package in onInstallerBeforeInstaller Event Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/building-extensions/plugins/methods-and-arguments.md This example illustrates how to update the package details within the onInstallerBeforeInstaller event, allowing modification of the extension being installed. ```php public function onInstallerBeforeInstaller(\Joomla\CMS\Event\Installer\BeforeInstallerEvent $event): void { $newpkg = array("dir" => $pathToExtensionDirectory, "type" => "plugin", "extractdir" => null, "packagefile" => null); $event->updatePackage($newpkg); } ``` -------------------------------- ### Display help for the hello:world CLI command Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/building-extensions/plugins/plugin-examples/basic-console-plugin-helloworld.md Use this command to view the help text for the 'hello:world' CLI command, including its description and usage instructions. ```bash php cli/joomla.php hello:world -h ``` -------------------------------- ### Get UTC Offset for Time Zone Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/general-concepts/classes/date.md Set a specific time zone for the Date object and retrieve its UTC offset in seconds. The example uses 'Europe/Berlin'. ```php use Joomla\CMS\Factory; $date = Factory::getDate(); $date->setTimezone(new DateTimeZone('Europe/Berlin')); echo $date->getOffset(); // 3600 ``` -------------------------------- ### Load Row List Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/general-concepts/database/query-results.md Use loadRowList() to get an indexed array of indexed arrays, representing table records. Array indices are numeric, starting from zero. ```php . . . $db->setQuery($query); $row = $db->loadRowList(); print_r($row); ``` ```php $row['index'] // e.g. $row['2'] ``` ```php $row['index']['index'] // e.g. $row['2']['3'] ``` -------------------------------- ### GET /api/v1/content/articles with modified date filters Source: https://github.com/joomla/manual/blob/main/updates/54-60/new-features.md This endpoint allows filtering articles based on their modification start and end dates. It is useful for implementing delta sync functionalities in APIs. ```APIDOC ## GET /api/v1/content/articles ### Description Retrieves a list of articles, with the ability to filter by modification date range. ### Method GET ### Endpoint /api/v1/content/articles ### Parameters #### Query Parameters - **filter[modified_start]** (string) - Optional - The start date for filtering articles by modification date (YYYY-MM-DD). - **filter[modified_end]** (string) - Optional - The end date for filtering articles by modification date (YYYY-MM-DD). ### Request Example ```bash GET /api/v1/content/articles?filter[modified_start]=2025-02-01&filter[modified_end]=2025-02-28 ``` ### Response #### Success Response (200) - **articles** (array) - A list of article objects matching the filter criteria. #### Response Example ```json { "articles": [ { "id": 1, "title": "Example Article", "modified": "2025-02-15T10:00:00+00:00" } ] } ``` ``` -------------------------------- ### Execute 'Hello World' command Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/building-extensions/plugins/plugin-examples/basic-console-plugin-helloworld.md Run this command after creating the 'hello:world' console plugin to see the 'Hello World' output. ```bash php cli/joomla.php hello:world ``` -------------------------------- ### Retrieving All Event Arguments as an Associative Array Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/building-extensions/plugins/methods-and-arguments.md This example shows how to get all event arguments as an associative array using the getArguments() method. This is useful when a specific getter function is not available for a particular argument. ```php $args = $event->getArguments(); ``` -------------------------------- ### Initialize a Git Repository Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/get-started/git/git-basics.md Use this command to create a new, empty Git repository in the current directory. This sets up the necessary .git folder to start tracking changes. ```bash git init . ``` -------------------------------- ### Implement InstallerScriptTrait for Installer Scripts Source: https://github.com/joomla/manual/blob/main/updates/54-60/new-features.md Use the InstallerScriptTrait to reduce boilerplate code in your installer scripts. This trait provides common functionality for installer scripts. ```php use Joomla\CMS\Installer\InstallerScriptTrait; class com_exampleInstallerScript implements InstallerScriptInterface { use InstallerScriptTrait; } ``` -------------------------------- ### Initialize FTP Adapter Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/building-extensions/plugins/plugin-examples/filesystem-plugin-ftp.md Constructs the FtpAdapter, establishing an FTP connection and logging in. Throws an exception if connection or login fails. Ensure FTP server details are correctly provided. ```php 'video/avi', '.bmp' => 'image/bmp', '.gif' => 'image/gif', '.jpeg' => 'image/jpeg', '.jpg' => 'image/jpeg', '.mp3' => 'audio/mpeg', '.mp4' => 'video/mp4', '.mpeg' => 'video/mpeg', '.pdf' => 'application/pdf', '.png' => 'image/png', ); // Configuration from the plugin parameters private $ftp_server = ""; private $ftp_username = ""; private $ftp_password = ""; private $ftp_root = ""; private $url_root = ""; // ftp connection private $ftp_connection = null; public function __construct(string $ftp_server, string $ftp_username, string $ftp_password, string $ftp_root, string $url_root) { $this->ftp_server = $ftp_server; $this->ftp_username = $ftp_username; $this->ftp_password = $ftp_password; $this->ftp_root = $ftp_root; $this->url_root = $url_root; if (!$this->ftp_connection = @ftp_connect($this->ftp_server)) { $message = error_get_last() !== null && error_get_last() !== [] ? error_get_last()['message'] : 'Error'; Log::add("FTP can't connect: {$message}", Log::ERROR, 'ftp'); throw new \Exception($message); } if (!@ftp_login($this->ftp_connection, $this->ftp_username, $this->ftp_password)) { $message = error_get_last() !== null && error_get_last() !== [] ? error_get_last()['message'] : 'Error'; Log::add("FTP can't login: {$message}", Log::ERROR, 'ftp'); @ftp_close($this->ftp_connection); $this->ftp_connection = null; throw new \Exception($message); } } public function __destruct() { if ($this->ftp_connection) { @ftp_close($this->ftp_connection); } } /** * This is the comment from the LocalAdapter interface - but it's not complete! * * Returns the requested file or folder. The returned object * has the following properties available: * - type: The type can be file or dir * - name: The name of the file * - path: The relative path to the root * - extension: The file extension * - size: The size of the file * - create_date: The date created * - modified_date: The date modified * - mime_type: The mime type * - width: The width, when available * - height: The height, when available * * If the path doesn't exist a FileNotFoundException is thrown. * * @param string $path The path to the file or folder * * @return \stdClass * * @since 4.0.0 * @throws \Exception */ public function getFile(string $path = '/'): \stdClass { if (!$this->ftp_connection) { throw new \Exception("No FTP connection available"); } // To get the file details we need to run mlsd on the directory $slash = strrpos($path, '/'); if ($slash === false) { Log::add("FTP unexpectedly no slash in path {$path}", Log::ERROR, 'ftp'); return []; } if ($slash) { $directory = substr($path, 0, $slash); $filename = substr($path, $slash + 1); } else { // it's the top level directory $directory = ""; $filename = substr($path, 1); } if (!$files = ftp_mlsd($this->ftp_connection, $this->ftp_root . $directory)) { throw new FileNotFoundException(); } foreach ($files as $file) { if ($file['name'] == $filename) { $obj = new \stdClass(); $obj->type = $file['type']; $obj->name = $file['name']; $obj->path = $path; $obj->extension = $file['type'] == 'file' ? File::getExt($obj->name) : ''; $obj->size = $file['type'] == 'file' ? intval($file['size']) : ''; $obj->create_date = $this->convertDate($file['modify']); $obj->create_date_formatted = $obj->create_date; ``` -------------------------------- ### HTML for Release Notes and Help Step Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/general-concepts/guided-tours/create-whatsnewtour.md This HTML snippet is used for a step in the 'What's New' tour, providing a link to full release notes and additional help resources. Ensure the URL is correct. ```html

Joomla X.Y Full Release Notes

View the full release notes on joomla.org

Help and Information

Many resources to help you can be found here together with additional links to more resources, documentation, support and how to become involved in Joomla.

``` -------------------------------- ### Add Menu Module to Dashboard via Install Script Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/general-concepts/dashboard.md Use the `addDashboardMenu` method in the install script to add your preset menu module to the component's dashboard during installation. ```php // Add menu module to dashboard $this->addDashboardMenu('example', 'example'); ``` -------------------------------- ### Define command description and help text Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/building-extensions/plugins/plugin-examples/basic-console-plugin-helloworld.md This PHP code configures the 'hello:world' command by setting its description and detailed help text, which will be displayed in the terminal. ```php protected function configure(): void { $this->setDescription('This command prints hello world'); $this->setHelp( <<<'EOF' The %command.name% command prints hello world. To use enter: php %command.full_name% EOF ); } ``` -------------------------------- ### Update Installer Result and Message in onInstallerAfterInstaller Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/building-extensions/plugins/plugin-events/installer.md This event is triggered after an extension has been installed. While setting the installer result has limited impact at this stage, you can use it to customize the message displayed to the administrator. ```php public function onInstallerAfterInstaller( Joomla\CMS\Event\Installer\AfterInstallerEvent $event ): void { $event->updateInstallerResult(false); $event->updateMessage("Some failure message"); } ``` -------------------------------- ### Boot a Joomla Module Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/general-concepts/extension-and-dispatcher/extension-dispatcher-module.md Instantiates the Extension class for a specific module. Use this to begin module execution. Requires module name and application name ('site' or 'administrator'). ```php $module = $app->bootModule($moduleName, $applicationName); ``` -------------------------------- ### Retrieving All GET Parameters Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/general-concepts/input.md Retrieve all available GET parameters as an associative array. The 'getArray()' method applies the 'STRING' filter to all values by default. This is useful for processing all incoming GET data. ```php $value = $input->get->getArray(); ``` -------------------------------- ### Retrieving a Specific GET Parameter with Custom Filter Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/general-concepts/input.md Retrieve a GET parameter by its name and specify a custom filter. The 'get()' method allows you to define the filter, such as 'int' for integer values. ```php $value = $input->get->get('p1', 0, "int"); ``` -------------------------------- ### Retrieving a Specific GET Parameter with Default Filter Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/general-concepts/input.md Retrieve a GET parameter by its name. The 'get()' method applies the 'CMD' filter by default. This is useful for retrieving single parameters with basic sanitization. ```php $value = $input->get->get('p1'); ``` -------------------------------- ### Front End Usage Example Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/accessibility/element-library/empty-template.md Sample HTML code for front-end usage, typically within the Cassiopeia template. Notes on usage should be added in the info box above. ```html ``` -------------------------------- ### Accessing GET and POST Parameters Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/general-concepts/input.md Use the 'get' and 'post' properties of the Input class to access HTTP GET and POST parameters respectively. These properties allow direct access to the parameter data. ```php $input->get // property to retrieve GET parameters $input->post // property to retrieve POST parameters ``` -------------------------------- ### Joomla Installer Script Implementation Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/building-extensions/install-update/installation/install-process.md This script implements the InstallerScriptInterface using a service provider. It leverages InstallerScriptTrait for pre-defined installer functionalities and includes custom logic for install, update, uninstall, preflight, and postflight actions. Use this approach when you need to integrate custom installer logic with Joomla's dependency injection system. ```php set( InstallerScriptInterface::class, new class ( $container->get(AdministratorApplication::class), $container->get(DatabaseInterface::class) ) implements InstallerScriptInterface { use InstallerScriptTrait { InstallerScriptTrait::preflight as iScriptTraitPre; InstallerScriptTrait::postflight as iScriptTraitPost; }; private AdministratorApplication $app; private DatabaseInterface $db; /** * Minimum PHP version required to install the extension * * @var string */ protected $minimumPhp = '8.4'; /** * Minimum Joomla! version required to install the extension * * @var string */ protected $minimumJoomla = '6.0.0'; /** * A list of files to be deleted * * @var array */ protected $deleteFiles = []; /** * A list of folders to be deleted * * @var array */ protected $deleteFolders = []; 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 { // Run trait preflight code $this->iScriptTraitPre(); // Your custom preflight code // Custom Dashboard Menu Module // $this->addDashboardMenuModule('example', 'example'); return true; } public function postflight(string $type, InstallerAdapter $parent): bool { // Run trait postflight code $this->iScriptTraitPost(); // Your custom postflight code return true; } } ); } }; ``` -------------------------------- ### Create ExampleHelper Class in PHP Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/building-extensions/modules/module-examples/basic-module.md Implement a helper class to retrieve module parameters. Ensure the correct namespace is defined for Joomla to recognize the helper. ```php * * @author | * @copyright Copyright(R) year by | * @license GNU General Public License version 2 or later; see LICENSE.txt * @link * @since 1.0.0 * */ namespace My\Module\Example\Site\Helper; defined('_JEXEC') or die; use Joomla\CMS\Language\Text; class ExampleHelper { /** * Method to get the items the helper calls the model to get the items * * @param Registry $params The module parameters * @param object $app The application object * * @return array * * @since 2.0 */ public function getMessage($params, $app) { // Get the message from the $params $message = $params->get('my-message', 'Fallback Message can be noted here'); return $message; } } ``` -------------------------------- ### Example Editor Provider Class Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/building-extensions/plugins/plugin-examples/editors-plugin.md Defines the 'ExampleEditorProvider' which extends 'AbstractEditorProvider'. It includes constructor, getName, and display methods for rendering the editor markup. Ensure Editor Buttons (XTD) are within the same container. ```php namespace JoomlaExample\Plugin\Editors\Example\Provider; use Joomla\CMS\Application\CMSApplicationInterface; use Joomla\CMS\Editor\AbstractEditorProvider; use Joomla\Event\DispatcherInterface; use Joomla\Registry\Registry; /** * Provider for Example editor */ final class ExampleEditorProvider extends AbstractEditorProvider { /** * A Registry object holding the parameters for the plugin * * @var Registry */ protected $params; /** * The application object * * @var CMSApplicationInterface */ protected $application; /** * Class constructor * * @param Registry $params * @param CMSApplicationInterface $application * @param DispatcherInterface $dispatcher */ public function __construct(Registry $params, CMSApplicationInterface $application, DispatcherInterface $dispatcher) { $this->params = $params; $this->application = $application; $this->setDispatcher($dispatcher); } /** * Return Editor name, CMD string. * * @return string */ public function getName(): string { return 'example'; } /** * Gets the editor HTML markup * * @param string $name Input name. * @param string $content The content of the field. * @param array $attributes Associative array of editor attributes. * @param array $params Associative array of editor parameters. * * @return string The HTML markup of the editor */ public function display(string $name, string $content = '', array $attributes = [], array $params = []) { // Check editor attributes and parameters $col = $attributes['col'] ?? ''; $row = $attributes['row'] ?? ''; $id = $attributes['id'] ?? ''; $buttons = $params['buttons'] ?? true; $asset = $params['asset'] ?? 0; $author = $params['author'] ?? 0; // Render the editor markup return '' . ''; . $this->displayButtons($buttons, ['asset' => $asset, 'author' => $author, 'editorId' => $id]); . '' } } ``` -------------------------------- ### Install Docusaurus Dependencies Source: https://github.com/joomla/manual/blob/main/about/contributing.md Run this command in your local git repository to install the necessary dependencies for Docusaurus. ```bash npm install ``` -------------------------------- ### Initialize Registry with Multidimensional Data Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/general-concepts/registry.md Example of creating a Registry instance with a multidimensional array, representing complex data structures like map configurations. ```php $map = ["lat" => "54.2", "long" => "-6.0", "zoom" => "12", "pins" => ["pins0" => ["pinlat" => "54.17982", "pinlong" => "-5.92094"], "pins1" => ["pinlat" => "54.17928", "pinlong" => "-5.94742"]]]; $registry = new Registry($map); ``` -------------------------------- ### Initialize Workflow with Extension, App, and DB Source: https://github.com/joomla/manual/blob/main/updates/43-44/new-deprecations.md When initializing a workflow, the extension, application, and database objects are now mandatory. Ensure these are provided during instantiation. ```php $workflow = new Workflow($extension, $app, $db); ``` -------------------------------- ### Get Input Parameter as Integer Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/general-concepts/input.md A shorthand for retrieving an integer parameter, equivalent to using `$input->get()` with the 'INT' filter. ```php $input->getInt('memberId', 0); ``` -------------------------------- ### Enable Multiple Assets and Register New Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/general-concepts/web-asset-manager.md Enable multiple script and style assets, and register and enable a new script asset with dependencies. ```php $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']); ``` -------------------------------- ### Get Input Parameter as String Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/general-concepts/input.md A shorthand for retrieving a string parameter, equivalent to using `$input->get()` with the 'STRING' filter. ```php $input->getString('name', ''); ``` -------------------------------- ### Get Registry Value with Default Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/general-concepts/registry.md Provide a default value to the get method, which is returned if the key is not present or is set to null. ```php $d = $registry->get("d", "a default string"); ``` -------------------------------- ### Running the Vendor Builder Source: https://github.com/joomla/manual/blob/main/updates/61-62/new-features.md After adding a new vendor package configuration to `settings.json`, run the `vendor` builder to copy the necessary files. This command ensures the third-party assets are correctly placed in the `media/vendor/` directory. ```bash npm run build -- -n vendor ``` -------------------------------- ### Register Multiple Update Servers with Priority Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/building-extensions/install-update/update-server.md This example demonstrates how to register multiple update servers in an extension's manifest file, including a 'collection' type server and an 'extension' type server with a specified priority. This allows control over the order in which servers are checked. ```xml https://example.com/list.xml http://example.com/extension.xml ``` -------------------------------- ### Replace `window.Calendar.setup()` with `JoomlaCalendar.init()` Source: https://github.com/joomla/manual/blob/main/updates/64-70/removed-backward-incompatibility.md In Javascript, use the `JoomlaCalendar` instance instead of `window.calendar` for calendar initializations. ```javascript // Old: window.Calendar.setup(); // New: JoomlaCalendar.init(); ``` -------------------------------- ### Contact Component Language String Example Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/general-concepts/multilingual/using-variables.md An example of a language string used in the contact component to display who checked out an item. ```ini COM_CONTACT_CHECKED_OUT_BY="Checked out by %s" ``` -------------------------------- ### Instantiate and Render with FileLayout Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/general-concepts/layouts.md Demonstrates how to use the FileLayout class directly for custom layout rendering, including adding custom include paths. This is useful when managing a library of layouts. ```php use Joomla\CMS\Layout\FileLayout; ... $layout = new FileLayout('com_example.div', $basePath, $options); $layout->addIncludePath(JPATH_ROOT . '/mycompany/layouts'); echo $layout->render($data); ``` -------------------------------- ### JavaScript Object Output Example Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/general-concepts/javascript/adding-javascript.md Example of the JavaScript Object structure logged to the console after retrieving options passed from PHP. ```json {alpha: 1, beta: "test", gamma: null} ``` -------------------------------- ### Identifying Plugin/Module Entry Points (Specific File) Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/building-extensions/install-update/installation/manifest.md If not using a services/provider.php file, point to the specific entry point filename for modules or plugins using the tag. ```xml mod_example.php ``` ```xml example.php ``` -------------------------------- ### Categories get() Method Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/general-concepts/categories/using-categories-api.md Explains how to retrieve specific category nodes using the `get()` method and discusses caching and language considerations. ```APIDOC ## Categories get() Once you have the `$categories` instance, you can retrieve `CategoryNode` instances using the `get()` method. ### Method Signature ```php $categories->get(int $id = null, bool $forceload = false): CategoryNode|CategoryNode[]|null ``` ### Description The `get()` method retrieves category data. If an `id` is provided, it returns the `CategoryNode` for that specific category. If no `id` is given, it returns the `CategoryNode` for the system `ROOT` category. This method caches category data, including ascendents and descendants, to optimize subsequent database queries. Setting the `$forceload` parameter to `true` bypasses the cache and forces a fresh database query. In a multilingual site, results are filtered by the current language or language `*` (all). Item counting is also restricted by language, assuming a `language` field in the extension table. ### Parameters - **id** (integer) - The ID of the category record to retrieve. If null, the root category is returned. - **forceload** (boolean) - If `true`, forces a database query, bypassing the cache. Defaults to `false`. ### Example ```php // Get the category node for category with id=12 $categoryNode = $categories->get(12); // Get the root category node $rootCategoryNode = $categories->get(); // Get category node with id=12, forcing a database reload $categoryNodeForced = $categories->get(12, true); ``` ``` -------------------------------- ### Install Composer Dependencies Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/testing/automated/system/setup.md Run this command in the root of your cloned Joomla CMS directory to install all necessary PHP dependencies managed by Composer. ```bash composer install ``` -------------------------------- ### Identifying Plugin/Module Entry Points (Services) Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/building-extensions/install-update/installation/manifest.md For plugins and modules using dependency injection with a services/provider.php file, specify the 'services' folder using the tag with the module or plugin name. ```xml services ``` ```xml services ``` -------------------------------- ### Get Joomla Mail Instance via MailerFactoryAwareTrait Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/general-concepts/mail.md In a component Controller or Model, use MailerFactoryAwareTrait to get the MailerFactory and create a Mail instance. ```php use Joomla\CMS\Factory; use Joomla\CMS\Mail\MailerFactoryAwareTrait; use Joomla\CMS\Mail\MailerFactoryAwareInterface; class MyController extends ... implements MailerFactoryAwareInterface { use MailerFactoryAwareTrait; public function sendMail() { $mailer = $this->getMailerFactory()->createMailer(); ... ``` -------------------------------- ### Installer Event `onInstallerBeforePackageDownload` Backward Compatibility Source: https://github.com/joomla/manual/blob/main/updates/44-50/removed-backward-incompatibility.md Update for `onInstallerBeforePackageDownload` to use `$event->getUrl()`, `$event->updateUrl($url)`, `$event->getHeaders()`, and `$event->updateHeaders($headers)` instead of direct reference modification. ```php // Old function onInstallerBeforePackageDownload(&$url, &$headers){ $url .= '&foo=bar'; } // New function onInstallerBeforePackageDownload(Joomla\CMS\Event\Installer\BeforePackageDownloadEvent $event){ $url = $event->getUrl(); $url .= '&foo=bar'; $headers = $event->getHeaders(); $headers['foo'] = 'bar'; $event->updateUrl($url); $event->updateHeaders($headers); } ``` -------------------------------- ### Select Records with Filtering and Ordering Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/general-concepts/database/select-data.md Create a database query to select records from the user profiles table, filtering by a key prefix and ordering the results. This example demonstrates using `select`, `from`, `where`, `order`, and `bind` methods. ```php use Joomla\CMS\Factory; // Get a db connection. $db = Factory::getContainer()->get(\Joomla\Database\DatabaseInterface::class); // Create a new query object. $query = $db->createQuery(); // Select all records from the user profile table where key begins with "custom.". // Order it by the ordering field. $query->select($db->quoteName(['user_id', 'profile_key', 'profile_value', 'ordering'])); $query->from($db->quoteName('#__user_profiles')); $query->where($db->quoteName('profile_key') . ' LIKE :profile_key'); $query->order($db->quoteName('ordering') . ' ASC'); // bind value for prepared statements $query->bind(':profile_key', 'custom.%'); // Reset the query using our newly populated query object. $db->setQuery($query); // Load the results as a list of stdClass objects (see later for more options on retrieving data). $results = $db->loadObjectList(); ``` -------------------------------- ### Define getMainModelForView Method Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/web-services-api/json-response-format/index.md Boots the articles model for a view and sets various states based on provided parameters. This method is crucial for configuring the articles model with specific filters and ordering. ```php /** * Boot the model and set the states * * @param \Joomla\Registry\Registry $params The module Articles - Category params * */ protected function getMainModelForView($params): \Joomla\Component\Content\Site\Model\ArticlesModel { $mvcContentFactory = $this->app->bootComponent('com_content')->getMVCFactory(); // Get an instance of the generic articles model /** @var \Joomla\Component\Content\Site\Model\ArticlesModel $articlesModel */ $articlesModel = $mvcContentFactory->createModel('Articles', 'Site', ['ignore_request' => true]); if (!$articlesModel) { throw new \RuntimeException(Text::_('JLIB_APPLICATION_ERROR_MODEL_CREATE')); } $appParams = ComponentHelper::getComponent('com_content')->getParams(); $articlesModel->setState('params', $appParams); $articlesModel->setState('filter.published', ContentComponent::CONDITION_PUBLISHED); /* * Set the filters based on the module params */ $articlesModel->setState('list.start', 0); $articlesModel->setState('list.limit', (int) $params->get('count', 0)); $catids = $params->get('catid'); $articlesModel->setState('filter.category_id', $catids); // Ordering $ordering = $params->get('article_ordering', 'a.ordering'); $articlesModel->setState('list.ordering', $ordering); $articlesModel->setState('list.direction', $params->get('article_ordering_direction', 'ASC')); $articlesModel->setState('filter.featured', $params->get('show_front', 'show')); $excluded_articles = $params->get('excluded_articles', ''); if ($excluded_articles) { $excluded_articles = explode("\r\n", $excluded_articles); $articlesModel->setState('filter.article_id', $excluded_articles); // Exclude $articlesModel->setState('filter.article_id.include', false); } return $articlesModel; } ``` -------------------------------- ### onInstallerAddInstallationTab Source: https://github.com/joomla/manual/blob/main/versioned_docs/version-6.1/building-extensions/plugins/plugin-events/installer.md This event is triggered when Joomla is building the form in the administrator Install / Extensions page. It allows plugins to add custom tabs to the installation form. ```APIDOC ## onInstallerAddInstallationTab ### Description This event is triggered when Joomla is building the form in the administrator Install / Extensions page. ### Event Arguments The event class `\Joomla\CMS\Event\Installer\AddInstallationTabEvent` has no arguments. ### Return Value Return the contents of the additional tab which you want to include in the options for install using, eg ```php $event->addResult($tabHTML); ``` ### Examples The Joomla core uses this mechanism to create the tabs "Upload Package File", "Install from Folder" etc. You should look at these install plugins and follow them as exemplars. ```