Joomla! Documentation™

Joomla! 

4.x

Joomla! 

3.x

Joomla! 

2.5

Di Joomla, terdapat file-file manifes untuk semua ekstensi. File-file ini termasuk informasi umum pemasangan serta parameter untuk mengonfigurasikan ekstensi itu sendiri. Sejak Joomla! 2.5, ada sedikit perbedaan antara format file manifes untuk setiap jenis ekstensi, yang memungkinkan setiap jenisnya untuk dapat mengakses pemasang Joomla sepenuhnya.

Ketentuan penamaan

File harus dinamakan manifest.xml atau <nama_ekstensi>.xml dan ditempatkan di direktori root dari paket pemasangan.

Joomla 4.x: Automatic namespace mapping will fail if a manifest file named manifest.xml is used. See: https://github.com/joomla/joomla-cms/issues/37750

Sintak

Elemen root

General Information

Tag utama dari file pemasangan adalah:

<extension></extension>

Tag pembuka dan penutup ini sama untuk semua ekstensi. Atribut-atribut berikut ini dibolehkan di dalam tag:

Atribut	Nilai	Diterapkan ke	Keterangan
type	component file language library module package plugin template element	Semua ekstensi	Atribut ini menjelaskan jenis ekstensi untuk pemasang. Berdasarkan jenis ini, persyaratan lebih lanjut diterapkan untuk sub-tag.
version	2.5 3.0	Semua ekstensi	String yang mengenali versi Joomla dari ekstensi yang dikembangkan. Ini tidak dipakai di dan telah dibuang dari dan versi yang berikutnya.
method	install upgrade	Semua ekstensi	Nilai standar install juga akan dipakai apabila metode atribut tidak digunakan. Nilai install berarti pemasang akan berhenti menemukan file/folder ekstensi yang baru secara baik.
client	site administrator	Modul	Atribut klien yang menentukan untuk ke aplikasi klien mana modul baru tersebut disediakan.
group	string	Plugin	Nama grup yang menentukan untuk ke grup mana plugin baru tersebut disediakan. Grup yang ada sekarang merupakan nama foldernya yang ada di dalam direktori /plugins. Pemasang akan membuat nama folder baru jika nama grup belum ada.

Metadata

Elemen berikut ini dapat digunakan untuk menyisipkan metadata. Tak satu pun dari elemen-elemen ini yang wajib dipakai; tapi kalau dipakai, harus diletakkan tepat di bawah elemen root.

<name> – raw component name (e.g. com_banners). 
<author> – author's name (e.g. Joomla! Project)
<creationDate> – date of creation or release (e.g. April 2006)
<copyright> – a copyright statement (e.g. (C) 2005 - 2011 Open Source Matters. All rights reserved.)
<license> – a license statement (e.g. NU General Public License version 2 or later; see LICENSE.txt)
<authorEmail> – author's email address (e.g. admin@joomla.org)
<authorUrl> – URL to the author's website (e.g. www.joomla.org)
<version> – the version number of the extension (e.g. 1.6.0)
<description> – the description of the component. This is a translatable field. (e.g. COM_BANNERS_XML_DESCRIPTION)
<element> – the internal name of the component. If omitted, name will be cleaned and used

Catatan: Tag <name> dan <description> merupakan bidang yang dapat diterjemahkan, jadi nama dan keterangan ekstensi dapat ditampilkan ke dalam bahasa yang digunakan pengguna.

File frontend

	<files folder="from-folder">
		<filename>example.php</filename>
		<folder>examples</folder>
	</files>

File-file yang disalin ke direktori frontend harus ditempatkan di dalam elemen <files>. Anda dapat menggunakan atribut folder bila diperlukan untuk menentukan sebuah direktori di dalam paket ZIP tempat dari mana file itu berasal. Setiap salinan file harus merupakan satu elemen <filename>. Kalau anda ingin menyalin keseluruhan folder sekaligus, anda bisa menentukannya sebagai <folder>.

Untuk plugin, nama bebas dari plugin tersebut harus berada di dalam atribut plugin di elemen <filename> yang mengarah ke file berisi kelas plugin. Contohnya, di plugin sistem yang bernama "example" (nama lengkapnya plg_system_example), gunakan <filename plugin="example">example.php</filename>.

File media

	<media folder="media" destination="com_example">
		<filename>com_example_logo.png</filename>
		<folder>css</folder>
		<folder>js</folder>
	</media>

Contoh ini akan menyalin file (/media/com_example_logo.png) dan folder (/media/css/ dan /media/js/) ke /media/com_example/, membuat folder com_example jika diperlukan. Anda bisa membuat atribut folder bila perlu untuk menentukan sebuah direktori di dalam paket ZIP tempat dari mana file itu berasal (dalam contoh ini misalnya, media).

Ekstensi harus menyimpan aset terakses yang dibutuhkan (JS, CSS, gambar, dll) di dalam media. Diantara hal-hal lain mengapa fitur ini ditambahkan adalah untuk perkembangan selanjutnya ke dukungan multi-website dan pengembangan kode (PHP) yang mungkin terjadi di luar area website terakses yang ada di server. Catatan: media untuk ekstensi berjenis 'paket' tidak di-parsing.

Ref:

• Google Groups - joomla-dev-cms thread
• Google Groups - joomla-dev-cms thread

Bagian administrasi

	<administration>
		<!-- various elements -->
	</administration>

Bagian administrasi ditentukan di dalam <administration>. Disebabkan komponen diterapkan ke website dan administrator, hanya manifes komponen yang bisa disertakan di elemen ini.

File backend

File-file yang akan disalin ke direktori backend harus diletakkan di dalam bagian <files> di <administration>. Anda dapat menggunakan atribut opsional folder untuk menentukan dari direktori paket ZIP mana salinan itu akan diambil. Lihat File frontend untuk aturan-aturan selanjutnya.

Tautan menu dan submenu

Catatan versi: Sebelum Joomla 3.4, tidak menggunakan tag <menu> di file XML manifes masih membuat butir menu. Bug ini telah diperbaiki di Joomla 3.4, jadi apabila tidak ada tag <menu> di file manifes anda, tidak akan ada butir menu admin yang dibuat untuk komponen tersebut.

	<menu>COM_EXAMPLE</menu>
	<submenu>
		<!--
			Note that all & must be escaped to &amp; for the file to be valid
			XML and be parsed by the installer
		-->
		<menu link="anoption=avalue&amp;anoption1=avalue1">COM_EXAMPLE_SUBMENU_ANOPTION</menu>
		<menu view="viewname">COM_EXAMPLE_SUBMENU_VIEWNAME</menu>
	</submenu>

Teks untuk butir menu utama komponen ditentukan di <menu>, turunan dari <administration>. Juga, <submenu> boleh ada di sini (di turunan <administration>), yang mengandung lebih banyak butir menu dari <menu>.

Tambahan, setiap <menu> dapat menentukan atribut-atribut berikut ini:

Atribut	Keterangan
link	Tautan yang akan mengirim pengguna ketika butir menu tersebut diklik. Anda juga bisa menggunakan "view".
img	Jalur (relatif) ke gambar (16x16 piksel) yang muncul di samping butir menu tersebut. Harus url yang sesuai untuk nama file juga (misal, tanpa spasi)!
alt
view	Parameter URL yang ditambahkan ke tautan. Contoh, <menu view="cpanel">COM_EXAMPLE</menu> di manifes XML com_example akan menghasilkan URL butir menu index.php?option=com_example&view=cpanel. Anda juga bisa menggunakan "link".

Nilai di dalam tag adalah label menu. Tak sama dengan Joomla! 1.5, anda tidak bisa menggunakan string bahasa asli. Contoh, jika anda memasukkan "Example Component", dan bukannya COM_EXAMPLE, maka ini akan menghasilkan example-component di menu dan anda tak dapat menyediakan fitur penerjemahan untuknya. Untuk dapat menyediakan fitur penerjemahan, anda harus membuat file yang dinamakan en-GB.com_example.sys.ini di dalam folder administrator/languages/en-GB (anda bisa gunakan tag manifes <languages> untuk menyalinnya pada saat pemasangan) atau di administrator/components/com_example/language/en-GB. Berikutnya, jangan menyertakan file penerjemahan di tag <languages>. Selagi anda meletakkan direktori bahasa di tag <files>, ini akan langsung disalin pada saat komponen tersebut dipasang.

Isi dari file tersebut haruslah:

COM_EXAMPLE="Example Component"
COM_EXAMPLE_SUBMENU_ANOPTION="Another Option"
COM_EXAMPLE_SUBMENU_VIEWNAME="Another View"

Please note that the language string must be enclosed in double quotes, as per Joomla!'s translation standards.

Joomla! 1.6 and later sorts the Component menu items based on the actual translation of the key you supply in your XML manifest. This means that the sorting order is correct no matter what you call your translation key and no matter which language the site is being displayed in. Essentially, Joomla! 1.6 fixed the wrong sorting of the Components menu experienced under Joomla! 1.5 for the majority (non-English speaking!) of Joomla! users.

Dashboards

General Information

Specifies the details for displaying a dashboard for the component in the Administrator area for the site.

• It will make a dashboard icon appear next to the administrator menu item for the component
• The dashboard icon will click through to display modules assigned to the cpanel-example administrator module position
• The title and icon defined in the XML file will be used as the header and icon at the top of the component's dashboard page.

	<dashboards>
		<dashboard title="COM_EXAMPLE_DASHBOARD_TITLE" icon="icon-lock">example</dashboard>
	</dashboards>

Konfigurasi

Warning!

Bagian <config>, turunan dari root, menjelaskan opsi konfigurasi ekstensi. Jika diterapkan, opsi akan muncul di menu Pengelolaan (Pengelolaan Plugin, Pengelolaan Modul, atau Pengelolaan Templat). Opsi konfigurasi Komponen ditentukan di file terpisah yang bernama config.xml. Bagian root-nya harus <config>, plugin dan modul menggunakan <config> di file manifes ekstensi.

Setiap fieldset harus mengandung satu atau lebih elemen <field>, masing-masing mewakili satu bidang formulir beserta label. Lihat Jenis bidang formulir standar untuk melihat daftar jenis bidang formulir yang diperbolehkan dan contoh definisi XML bidang formulir

Namespace

General Information

Specify the namespace to be used for autoloading the plugin. The given namespace will autoload to the root directory of your extension by default however you can optionally add a "path" attribute to the namespace element to specify a subpath within your extensions root directory.

SQL

    <install>
        <sql>
            <file driver="mysql" charset="utf8">sql/example.install.sql</file>
        </sql>
    </install>
    <uninstall>
        <sql>
            <file driver="mysql" charset="utf8">sql/example.uninstall.sql</file>
        </sql>
    </uninstall>

Dalam contoh di atas, kita meletakkan file-file SQL di dalam folder admin/sql di paket pemasangan. Anda harus menyertakan folder sql di file administrasi (seperti dijelaskan di File backend).

You can execute SQL during the installation and/or uninstallation using the <install> and <uninstall> elements, respectively. A <sql> element should appear as a child of these elements. <sql> can contain any number of <file> elements, each defining a single SQL file to execute. Their database driver types are described by the driver attribute, their character sets by the charset attribute.

Update of the SQL Schema

Since 1.6, there is also an <update> tag, which allows you to provide a series of SQL files to update the current schema.

	<update>
		<schemas>
			<schemapath type="mysql">sql/updates/mysql</schemapath>
			<schemapath type="sqlsrv">sql/updates/sqlsrv</schemapath>
		</schemas>
	</update>

For example, in order to go from version 1.0.0 to version 1.0.1 in a MySQL database, a 1.0.1.sql file must be created inside the sql/updates/mysql folder and the <version> tag of the manifest must be updated to

<version>1.0.1</version>

The final structure of the sql folder will look like this (assuming a MySQL database)

sql
 |-->example.install.sql
 |-->example.uninstall.sql
 |-->updates
     |-->mysql
        |-->1.0.1.sql

Similar files must be created for subsequent versions.

Language Files

Since Joomla! 1.5, extension developers had to put extension language files in the Joomla! main language folder using the <languages>...</languages> tag as shown below. This method can still be used all Joomla! versions.

<!-- Joomla! language tag -->
<languages folder="langfiles">
	<language tag="en-GB">en-GB.com_example.ini</language>
</languages>

However since Joomla! 1.6 it is recommended that you place your extension's language files in your extension folder. Joomla! will then automatically load your extension's language files.

By storing extension language files in the extension folder, you benefit by isolating and protecting your extension's language files. For example, an administrator removes a language from their Joomla! installation. Your extension's language files will not be removed. They will remain in place and will be available if the language is installed again.

The structure of the language folder for frontend and backend is the same. You put them in the language tag (e.g. en-GB ) of each language in your language folder, i.e. language/en-GB/. You have to specify those folders in the front-end and back-end files too.

In your manifest, simply include the 'language' folder in your files section. The sub-directories for each language will automatically be copied. Inside the <files> group, add a <folder> element alongside the items in the <files> group as shown in this example:

<files>
	<filename plugin="alpha">alpha.php</filename>
	<folder>sql</folder>
	<folder>language</folder>
</files>

Note that both ways can work together. Here is an example from core:

<files>
	<filename plugin="languagecode">languagecode.php</filename>
	<filename>index.html</filename>
	<folder>language</folder>
</files>
<languages>
	<language tag="en-GB">language/en-GB/en-GB.plg_system_languagecode.ini</language>
	<language tag="en-GB">language/en-GB/en-GB.plg_system_languagecode.sys.ini</language>
</languages>

The advantages of this solution are the following:

All .ini files present in the core folder have precedence over the files in the extension language/ folder. For example, a .sys.ini file will always be loaded from core folders in the back-end if it exists, except when installing an extension which contains a .sys.ini file in a language folder. In that case and only that case, the .sys.ini file in the extension folder will display its translated content at install time. This is very handy. As a developer can have two .sys.ini files with different contents.

Also, it is much easier for a user needing an .ini file for an extension that does not provide it in the language desired to add it in the main folders. There is no risk that it will be deleted in case of uninstalling the extension by mistake or any other reason.

See also:

• Making non-core language packs
• Creating language packs for extensions in Joomla 2.5

During development you can turn on language debugging in the Joomla! global configuration. You can investigate if a problem arises. As of 3.2, this is necessary to help debug as en-GB is always loaded first when not in debug mode to prevent displaying Constants.

Script file

    <scriptfile>example.script.php</scriptfile>

An optional script file (PHP code that is run before, during and/or after installation, uninstallation and upgrading) can be defined using a <scriptfile> element.

This file should contain a class named "<element_name>InstallerScript" where <element_name> is the name of your extension (e.g. com_componentname, mod_modulename, etc.). Plugins must state the group (e.g. plgsystempluginname).

In and later the structure of the class is as follows:

<?php

use Joomla\CMS\Installer\InstallerAdapter;

class com_componentnameInstallerScript
{
	/**
	 * Constructor
	 *
	 * @param   InstallerAdapter  $adapter  The object responsible for running this script
	 */
	public function __construct(InstallerAdapter $adapter)
	{
	}
	
	/**
	 * Called before any type of action
	 *
	 * @param   string  $route  Which action is happening (install|uninstall|discover_install|update)
	 * @param   InstallerAdapter  $adapter  The object responsible for running this script
	 *
	 * @return  boolean  True on success
	 */
	public function preflight($route, InstallerAdapter $adapter)
	{
		return true;
	}
	
	/**
	 * Called after any type of action
	 *
	 * @param   string  $route  Which action is happening (install|uninstall|discover_install|update)
	 * @param   InstallerAdapter  $adapter  The object responsible for running this script
	 *
	 * @return  boolean  True on success
	 */
	public function postflight($route, $adapter)
	{
		return true;
	}
	
	/**
	 * Called on installation
	 *
	 * @param   InstallerAdapter  $adapter  The object responsible for running this script
	 *
	 * @return  boolean  True on success
	 */
	public function install(InstallerAdapter $adapter)
	{
		return true;
	}
	
	/**
	 * Called on update
	 *
	 * @param   InstallerAdapter  $adapter  The object responsible for running this script
	 *
	 * @return  boolean  True on success
	 */
	public function update(InstallerAdapter $adapter)
	{
		return true;
	}
	
	/**
	 * Called on uninstallation
	 *
	 * @param   InstallerAdapter  $adapter  The object responsible for running this script
	 */
	public function uninstall(InstallerAdapter $adapter)
	{
		return true;
	}
}

?>

Note that since Joomla 3.6 Joomla has shipped a basic script that you can use instead of shipping your own from scratch JInstallerScript which contains various helper methods commonly used through the community.

Library Manifests

General Information

A simple library manifest might look like this:

<?xml version="1.0" encoding="utf-8"?>
<extension type="library" method="upgrade" version="4.0">
    <name>My Test library.</name>
    <libraryname>mytest</libraryname>
    <files>
        <folder>Classes</folder>
        <folder>language</folder>
        <filename>mytest.php</filename>
    </files>
</extension>

This will install the library into the JPATH_SITE/libraries/mytest folder.

What if your company has several libraries and you want to group them together under folder JPATH_SITE/libraries/mycompany?

Simple - include your company name in the libraryname property of each library like this:

    <libraryname>mycompany/mylibrary1</libraryname>

    <libraryname>mycompany/mylibrary2</libraryname>

These libraries will then be installed in the JPATH_SITE/libraries/mycompany/mylibrary1 and JPATH_SITE/libraries/mycompany/mylibrary2 folders.

Uninstalling mylibrary1 will still leave mylibrary2 installed on your site.

When using script files with such company libraries the installer class name should look like this:

class mycompanymylibrary1InstallerScript

class mycompanymylibrary2InstallerScript

Update Servers

    <updateservers>
        <server type="extension" priority="1" name="Extension Update Site">http://example.com/extension.xml</server>
        <server type="collection" priority="2" name="Collection Update Site">http://example.com/collection.xml</server>
    </updateservers>

Update servers can be defined in the <updateservers> element, a child of the root. This element may contain one or more <server> element, each describing the location from which to download updates. Each <server> item can define the following attributes:

Attribute	Values	Description
type	extension collection	The update server type
priority	integer	The priority of the update server
name	string	The name of the update server

More info:

• Building a Joomla! Extension - Adding an update server
• Managing Component Updates in Joomla 2.5

Supporting Download Keys

As of Joomla 4.0.0 users can enter their download keys in the Update Sites list. This gives them a single place to manage the download keys. 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:

<dlid prefix="dlid=" suffix="&amp;dummy=my.zip"/>

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.

Examples

For a real-life example, see the manifest of the Banner component in the latest version of Joomla! 3.9.16.

Some more examples can be found in the standalone weblinks repo:

• com_weblinks manifest
• mod_weblinks manifest
• plg_search_weblinks manifest
• tpl_protostar manifest (3.9.16)
• en-GB manifest (3.9.16)