Manifest bestanden

From Joomla! Documentation

Revision as of 05:24, 20 July 2015 by MartijnM (talk | contribs) (Created page with "Het Joomla test-proces gebruikt verschillende extensies om te testen of de installer juist werkt. De nieuwste versies van de manifest-bestanden van deze extensies zijn:")
Other languages:
Bahasa Indonesia • ‎Deutsch • ‎English • ‎Nederlands • ‎español • ‎français • ‎italiano • ‎中文(台灣)‎
Joomla! 
3.x
Joomla! 
≥ 2.5

Binnen Joomla zijn manifest bestanden voor alle extensies. Deze bestanden bevatten zowel de algemene installatie informatie als parameters voor de configuratie van de extensie zelf. Sinds Joomla! 2.5, zijn weinig verschillen tussen de manifest bestand formaten voor de verschillende types extensies, waardoor elk type toegang krijgt tot de volledige kracht van de Joomla! installer.

Naamgeving

Het bestand moet heten manifest.xml of <extension_name>.xml en staan in de root map van het installatie pakket.

Syntaxis

Root element

De primaire tag van het installatie bestand is:

<extension></extension>

Deze begin en sluit tags zijn nu geldig voor alle extensies. De nieuwe tag <extension> vervangt de oude <install></install> uit Joomla Joomla 1.5. De volgende attributen zijn toegestaan binnen de tag:

Attribuut Waarden Van toepassing op Beschrijving
type component
file
language
library
module
package
plugin
template
Alle extensies Dit attribuut beschrijft het type extensie voor de installer. Gebaseerd op dit type zijn er verdere eisen aan de sub-tags van toepassing.
version 2.5
3.0
Alle extensies String die de versie van Joomla aangeeft waarvoor deze extensie ontwikkeld is.
method install
upgrade
Alle extensies De standaard waarde install zal ook gebruikt worden als het method attribuut niet gebruikt wordt. De install waarde betekent dat de installer netjes zal stoppen als het een bestaand bestand/map vindt van de nieuwe extensie.
client site
administrator
Modules Het client attribuut geeft u de mogelijkheid aan te geven voor welke client toepassing (website of beheergedeelte) de nieuwe module beschikbaar is.
group string Plugins De group naam geeft aan voor welke groep plugins de nieuwe plugin beschikbaar is. De bestaande groepen zijn de mapnamen binnen de map /plugins. De installer zal nieuwe mappen aanmaken voor groepsnamen die nog niet bestaan.


Metadata

De volgende elementen kunnen gebruikt worden om metadata in te voegen. Geen van deze elementen zijn verplicht; indien ze aanwezig zijn, moeten ze afstammen van het root element.

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

Opmerking: De <name> en <description> tags zijn ook te vertalen velden zodat de naam en beschrijving van de extensie aan de gebruiker getoond kan worden in hun eigen taal.

Website bestanden

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

Bestanden die gekopieerd moeten worden naar de website map moeten geplaatst worden binnen het <files> element. U kunt het optionele folder attribuut gebruiken om een map in het ZIP pakket op te geven om vanaf te kopiëren. Ieder bestand dat gekopieerd moet worden moet vertegenwoordigd zijn door het <filename> element. Indien u een volledige map in één keer wilt kopiëren, dan kunt u het als <folder> definiëren.

Mediabestanden

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

Dit voorbeeld kopieert de bestand(en) (/media/com_example_logo.png) en de opgenomen mappen ( /media/css/ en /media/js/ ) naar /media/com_example/, waarbij de com_example map, indien noodzakelijk, aangemaakt wordt. U kunt het optionele folder attribuut gebruiken om een map op te geven in het ZIP pakket om vanaf te kopiëren (in dit geval, media).

Extensies zouden middelen die ze nodig hebben om web-toegankelijk te zijn (JS, CSS, images etc) moeten opslaan in media. Deze functie was onder andere toegevoegd als stap in de ontwikkeling naar multi-site ondersteuning en de eventuele stap van code bestanden (PHP) buiten de vanuit het web toegankelijke gebieden van de server.

Ref:

Administratie sectie

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

De administratie sectie wordt gedefinieerd in het <administration> element. Aangezien alleen componenten van toepassing zijn op zowel de site als de administrator, kunnen alleen component manifest-bestanden dit element bevatten.

Back-end-bestanden

Bestanden die gekopieerd moeten worden naar de back-end map moeten geplaatst worden binnen het <files> element onder <administration>. U kunt het optionele folder attribuut gebruiken om een map op te geven in het ZIP pakket om vanuit te kopiëren. Zie Front-end bestanden voor meer regels.

Menu-links en sub-menu's

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

De tekst voor het hoofd menu-item voor de component is gedefinieerd in het <menu> item, een onderdeel van <administration>. Een <submenu> element kan ook aanwezig zijn (ook onderdeel van <administration>), welke meer menu-items kan bevatten, gedefinieerd door <menu>.

Bovendien kan elk <menu> item de volgende attributen definiëren:

Attribuut Beschrijving
link Een link waarnaar de gebruiker gestuurd wordt als op het menu-item geklikt wordt
img Het (relatieve) pad naar een afbeelding (16x16 pixels) om naast het menu-item te verschijnen.

Moet URL compatibel zijn als bestandsverwijzing (bijvoorbeeld geen spaties) !

alt
string Een URL parameter toe te voegen aan de link. Bijvoorbeeld, <menu view="cpanel">COM_EXAMPLE</menu> in com_example's XML manifest zou zorgen dat de URL van het menu-item zou zijn index.php?option=com_example&view=cpanel.

De waarde binnen de tag is het label van het menu. In tegenstelling tot Joomla! 1.5, kunt u geen natuurlijke taalstring gebruiken. Als u bijvoorbeeld "Voorbeeld component" zou opgeven in plaats van COM_EXAMPLE, dan zou het resultaat zijn dat de naam van uw component zou verschijnen als voorbeeld-component in het menu en u zou geen vertaling kunnen maken. Om een vertaling te kunnen leveren moet u een bestand genaamd en-GB.com_example.sys.ini maken in administrator/languages/en-GB (u kunt de <languages> tag van het manifest bestand tijdens de installatie kopiëren) of in administrator/components/com_example/language/en-GB. In het laatste geval, moet u het taalbestand niet opnemen in de <languages> tag. Als u de taal-map in uw <files> tag heeft opgenomen, zal het worden gekopieerd als de component wordt geïnstalleerd.

De inhoud van dat bestand moet zijn:

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

Houd er rekening mee dat de taalstring tussen dubbele aanhalingstekens moet staan, volgens de Joomla! vertaalstandaards. Belangrijk: Joomla! 1.6 en later sorteert de component menu-items gebaseerd op de daadwerkelijke vertaling van de sleutel die u geeft in uw XML manifest bestand. Dit betekent dat de sorteervolgorde juist is ongeacht hoe u uw vertaalsleutel noemt en ongeacht in welke taal de site wordt getoond. In wezen repareerde Joomla! 1.6 de verkeerde sortering van het componenten-menu tijdens Joomla! 1.5 voor de meeste (niet-Engels sprekenden!) Joomla! gebruikers.

Configuratie

Stop hand nuvola.svg.png
Warning!

Componenten ondersteunen geen configuratie definities in het manifest-bestand. Dit is in een manier geïmplementeerd in Joomla! 1.5. Ze kunnen configuratie opties voor meerdere niveaus definiëren met behulp van Component configuratie metadata.

Het <config> element, onder de root, beschrijft de configuratie opties voor de extensie. Indien van toepassing, worden de opties getoond door de juiste beheerder (Pluginbeheer, Modulebeheer of Templatebeheer). Configuratie opties kunnen ook gedefinieerd worden in een apart bestand genaamd config.xml. Het root element moet zijn <config>.

Elke fieldset moet één of meer <field> elementen bevatten, die elk één enkele form field bevatten met een label. Zie Standaard form field types voor een lijst met toegestane form field types en voorbeeld XML form field definities.

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>

In bovenstaande voorbeeld, stoppen we de SQL bestanden in de admin/sql map van het installatie pakket. U moet de sql map opnemen in de administration bestanden (zoals beschreven in Back-end bestanden).

U kunt SQL tijdens de installatie en/of deïnstallatie uitvoeren met behulp van respectievelijk de <install> en <uninstall> elementen. Een <sql> element moet verschijnen onder deze elementen. <sql> kan ieder aantal <file> elementen bevatten, welk elk één enkel SQL bestand bevatten om uit te voeren. Hun database driver types worden beschreven door het driver attribuut, hun character sets via het charset attribuut.

Bijwerken van het SQL schema

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

Sinds 1.6, is er ook een <update> tag, die u de mogelijkheid geeft een reeks SQL bestanden te leveren om het huidige schema bij te werken.

Taal-bestanden

In Joomla! 1.5, moesten extensie ontwikkelaars extensie taalbestanden in het Joomla! hoofd taalbestand opnemen, via de <languages>..</languages> tag zoals hieronder getoond. Deze methode kan nog steeds gebruikt worden in 2.5  3.x.

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

Sinds Joomla! 1.6 wordt aanbevolen uw extensie taalbestanden in uw extensie mappen te plaatsen. Joomla! zal dan automatisch uw extensie taalbestanden laden.

Door het opslaan van extensie taalbestanden in de extensie map, heeft u voordeel van het isoleren en beschermen van uw extensie taalbestanden. Een beheerder verwijdert bijvoorbeeld een taal uit uit de Joomla! installatie. Uw extensie taalbestanden worden niet verwijderd. Ze blijven op hun plaats en zijn beschikbaar als de taal opnieuw geïnstalleerd wordt.

De structuur van de taalmap voor website en beheergedeelte is hetzelfde. U plaats ze in de taal tag (bijvoorbeeld en-GB ) van iedere taal in uw taalmap bijvoorbeeld language/en-GB/. U moet deze mappen in de website- en beheer-bestanden ook opnemen.

In uw manifest bestand neemt u eenvoudig de 'language' map in uw files sectie op, de sub-mappen voor iedere taal worden dan automatisch gekopieerd. Binnen de <files> groep voegt u eenvoudig een <folder> element toe naast de items in de <files> groep zoals in dit voorbeeld getoond wordt:

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

Merk op dat beide manieren kunnen samenwerken. Hier is een voorbeeld uit de 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>

De voordelen van deze oplossing zijn de volgende:

Alle ini bestanden aanwezig in de core map hebben voorrang op de bestanden in de extensie language/ map. Een sys.ini bestand zal bijvoorbeeld altijd geladen worden vanuit core mappen in het beheergedeelte als ze bestaan, behalve als een extensie geïnstalleerd wordt die een sys.ini bestand bevat in een taalmap. In dat geval en alleen maar in dat geval, zal het sys.ini bestand in de extensie map zijn vertaalde inhoud tonen bij het installeren. Dit is erg handig aangezien een ontwikkelaar 2 sys.ini bestanden kan hebben met verschillende inhoud. Een beschrijving van de succesvolle installatie en een handleiding in het beheergedeelte als voorbeeld.

Het maakt het ook voor een gebruiker veel makkelijker om een ini-bestand voor een extensie die dat niet in de gewenste taal verstrekt, hem in de hoofdmappen toe te voegen. Er is geen risico dat hij verwijderd wordt in het geval dat de extensie per ongeluk of om een andere reden gedeïnstalleerd wordt.

Zie ook:

Tijdens het ontwikkelen kunt u foutopsporing in de Joomla! Algemene instellingen aan zetten. Zodat u kunt onderzoeken of er problemen optreden. Vanaf 3.2, is dit noodzakelijk om te debuggen aangezien en-GB altijd eerst wordt geladen als u niet in foutopsporingsmodus bent om te voorkomen dat constanten getoond worden.

Script bestand

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

Een optioneel scriptbestand (PHP code die voor, tijdens en/of na installatie, deïnstallatie en upgrade uitgevoerd wordt) kan gedefinieerd worden door middel van een <scriptfile> element. Dit bestand moet een class genaamd "<element_name>InstallerScript" bevatten waarbij <element_name> de naam van uw extensie is (bijvoorbeeld com_componentnaam, mod_modulenaam, etc.). Plugins vereisen dat de groep wordt opgegeven (bijvoorbeeld plgsystempluginnaam). Library-pakketten ondersteunen geen scriptbestanden. De structuur van de class is als volgt:

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

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 kunnen worden gedefinieerd in het <updateservers> element, onder de root. Dit element kan een of meer <server> element bevatten, welke ieder een locatie beschrijven om updates vanaf te halen. Elk <server> item kan de volgende attributen bevatten:

Attribuut Waarden Beschrijving
type extension
collection
Het update-server type
priority integer De prioriteit van de update-server
name string De naam van de update-server

Meer informatie:

Voorbeelden

Zie, voor een echt voorbeeld het manifest bestand van het Banner-component in de nieuwste versie van Joomla! 2.5.

Het Joomla test-proces gebruikt verschillende extensies om te testen of de installer juist werkt. De nieuwste versies van de manifest-bestanden van deze extensies zijn:

Contributors