====== Package Specification ======

**Change log**

^ Date       ^ By         ^ Description         ^
| 2008-04-23 | Acenes     | Initial Draft       |
| 2008-04-24 | Acenes     | Changed extension.id attribute to alphanumeric extension.name |
| 2008-04-25 | Acenes     | Make classification.demo a attribute of its own instead of another type. |
| 2008-05-04 | Acenes     | Added teaser. |
| 2008-05-10 | Acenes     | - Removed file list from package (automatic detection)\\ - Changed ''forumnick'' to ''user'' \\ - Removed licensefile attribute (all files viewable)\\ - Added version encoding  |
| 2008-05-11 | Acenes     | Added ''build'' numbers |
| 2008-05-12 | Acenes     | Moved all language dependent elements into ''language'' element. |
| 2008-05-15 | Acenes     | Added package upload notes. |
| 2008-05-19 | Acenes     | Changed the directory structure adding distinct folders for TL_ROOT, TL_FILES and INSTALL as suggested by Andreas. |
| 2008-05-19 | Acenes     | Removed email adresses (prevent spammers). |
| 2008-07-09 | Acenes     | Reworded version number explanations. |
| 2010-03-31 | Acenes     | Removed soapwsdl and demo attributes.  |






===== Package File =====

Package files will be used to upload a new version of an extension by the package manager, as well as to install a package from file instead online from the SOAP services. 

  * The package file itself is a ZIP file with at least one file named ''package.xml'' in the root. 

  * Additionally there may be another file named ''package.jpg'' in the root holding a picture of size w x h = 800 x 600. This image will show up as thumbnail in the repository overviews, and can be clicked on to be shown in full size.

  * Files that shall get copied relative to the TYPOlight root shall go into the directory TL_ROOT.

  * Files that shall get copied into the files folder shall go into the directory TL_FILES.
 
  * SQL scripts that shall be executed at installation and uninstallation shall be INSTALL/install.sql and INSTALL/uninstall.sql respectively.

  * SQL scripts that shall be executed at updates shall be in INSTALL/[9-digit version].sql, where each file contains the delta that must be executed when updating from the previous version. Depending on the currently installed version on the users server, the necessary scripts will be run in ascending order by the package installer.

Below is the content of a package ZIP-file for a fictional hotel room reservation extension:

<file>
INSTALL/install.sql
INSTALL/uninstall.sql
INSTALL/010010009.sql
INSTALL/010010019.sql
INSTALL/010020009.sql
TL_FILES/hotelres/floorplan.jpg
TL_ROOT/system/modules/hotelres/LICENSE.txt
TL_ROOT/system/modules/hotelres/HotelController.php
TL_ROOT/system/modules/hotelres/HotelInstaller.php
TL_ROOT/system/modules/hotelres/config/config.php
TL_ROOT/system/modules/hotelres/config/database.sql
TL_ROOT/system/modules/hotelres/dca/hotel.php
TL_ROOT/system/modules/hotelres/languages/en/hotel.php
TL_ROOT/system/modules/hotelres/languages/de/hotel.php
TL_ROOT/templates/hotelres_fe.tpl
package.xml
package.jpg
</file>

The archive naming scheme as TYPOlight_//package//_//version//_//build//.zip, for the example application this could therefore be ''TYPOlight_hotel_10000129_102.zip''


===== Uploading to Repository =====


==== Author ====

  * The extension must exist in the repository, and belong to the author uploading the package.
  * When the package contains a new version number, a new release will be created starting with build index 0.
  * When the package contains a existing version number, the build index will be incremented. Files not changed can be omitted from the package in this case.
  * Removing a file from the release is therefore not possible by uploading a package. Use the author front end of the repository to remove files.





==== Translator ====

  * Translators can only upload packages for existing releases of extensions. 
  * The build index will be incremented.
  * Only the meta data and files of languages assigned to the uploading translator will get processed. All other files and most other meta data may be omitted, the extension name and version number are required however.
  * Translation files must go into directory TL_ROOT/system/modules///name///languages///code//, where //name// is the extension name and //code// is the 2 character ISO code of the language. 
  * Only translation files that already exist in the repository will get updated, it is not possible for a translator to upload new files.






===== XML File Specification =====










==== Text encoding ====

All texts are encoded in UTF-8. The following characters must be converted to the respective HTML entities:

^ Character ^ HTML Entity ^
|  &        |  &amp;      |
|  "        |  &quot;     |
|  '        |  &#039;     |
|  <        |  &lt;       |
|  >        |  &gt;       |

In PHP the encoding is best done by ''htmlspecialchars($text,ENT_QUOTES,'UTF-8')''

==== Date encoding ====

Dates are in format YYYYMMDD.











==== Version encoding ====

Version numbers of the extensions in the repository are made up by 4 parts:

  - A **major number** from 0...99.\\ The major number is changed when backward compatibility to former versions is dropped or a complete rework/redesign has taken place. The users will normally need to do some migration steps when upgrading to a new major number.
  - A **minor number** from 0...999.\\ The minor number is changed when new features are added which do not break backward compatibility for users. Database layout or documented interfaces/hooks may change, so custom add-ons and other dependent extensions may need to be adjusted.
  - A **micro number** from 0...999.\\ The micro number is changed for enhancements or bug fixes which do not break backward compatibility. Not database changes are involved, and all documented interfaces/hooks stay upward compatible, so custom add-ons and dependent extensions need no adjustments as long as they only use database fields or documented interfaces.
  - A **status** from 0...9 translating as:\\ 0 = ''alpha1''\\ 1 = ''alpha2''\\ 2 = ''alpha3''\\ 3 = ''beta1''\\ 4 = ''beta2''\\ 5 = ''beta3''\\ 6 = ''rc1''\\ 7 = ''rc2''\\ 8 = ''rc3''\\ 9 = ''stable''.\\ Alpha versions are experimental and serve to enable public participation in development stage.\\ Beta versions are mostly feature complete, but not completely field tested.\\ RC (release candidate) versions are basically ready for production, but not widely field tested.\\ Stable versions are thoroughly field tested and approved by the author for production use.

The version is encoded to 9 digit number as [major:2][minor:3][micro:3][status:1], for example version 1.2.3 rc2 will be 10020037, or 0.0.1 alpha1 is 10. The value 0 is reserved for invalid/no version, so there exists no such version as 0.0.0 alpha1.

<note>It is the author's own decision to define versions. It is however in his own interest to follow the suggested version numbering policies. For example if an extension is declared //stable// before it tested in the field and bugs are ironed out, it is likely that it will receive bad ratings and reviews. If it on the other hand never gets promoted to //stable// even after it is well proved, people with increased safety awareness may never install it.</note>




==== Build numbers ====

Build numbers start at 0 for a new version, and get incremented automatically whenever something is changed on an existing release. That could be when translations are added or changed, files are modified, bugs are fixed or meta data is edited. When creating a new release it is likely that several changes are made such as uploading new files or changing meta data, so when finally publishing the new release the build will hardly ever be 0. 

Build numbers can not be set directly, so also the build number in a package uploaded by an author is ignored.









==== Example File ====

This is the package.xml file to the hotel reservation example:

<code>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE typolightpackage>
<extension name="hotelres" date="20080422">
  <author user="jmill" name="John Miller" />
  <copyright>&copy; 2008, 2009 by John Miller Web Services</copyright>
  <license>GNU Lesser Public License (LGPL) Version 3</license>
  <classification type="commercial" category="application" />
  <release version="10000129" build="102" date="20080421" />
  <typolight minversion="20040059" maxversion="20040079" />
  <script class="HotelInstaller" />
  <requiredextension name="bbcode" minversion="80059" maxversion="10000029" />
  <requiredextension name="creditcard" minversion="10050058" maxversion="10090039" />
  <language code="en">
    <translator user="jmill" name="John Miller" />
    <searchtags>hotel,reservation,room,rent</searchtags>
    <title>Hotel Reservations</title>
    <teaser>Reservation and booking of hotel rooms</teaser>
    <description>
      Allow guests to book hotel room reservations.&lt;br/&gt;
      Online feedback about success, plus email confirmation.&lt;br/&gt;
      Optional commission payment by credit card.
    </description>
    <releasenotes>
      This is just a small update:&lt;br/&gt;
      &lt;ul&gt;
      &lt;li&gt;Added field for customers skype address.&lt;/li&gt;
      &lt;li&gt;Fixed bug in credit card verification.&lt;/li&gt;
      &lt;/ul&gt;
    </releasenotes>
    <manual link="http://www.jmillers.com/hotel/manual.html" />
    <forum link="http://www.typolight.org/forum/viewforum.php?id=24" />
    <shop link="http://www.jmillers.com/shop/article/hotel.html" />
  </language>
  <language code="de">
    <translator user="heugen" name="Horst-Eugen Leicht" />
    <searchtags>Hotel,Reservation,Zimmer,Vermietung</searchtags>
    <title>Hotel Reservationen</title>
    <teaser>Reservation und Buchung von Hotelzimmern</teaser>
    <description>
      Ermöglicht Gästen, selber eine Hotelzimmer Reservation vorzunehmen.&lt;br/&gt;
      Online Rückmeldung über den Erfolg der Buchung, sowie Bestätigung per EMail.&lt;br/&gt;
      Optionale Anzahlung per Kreditkarte.
    </description>
    <releasenotes>
      Dies is nur eine kleine Anpassung:&lt;br/&gt;
      &lt;ul&gt;
      &lt;li&gt;Neues Eingabefeld für die Skype Adresse des Kunden.&lt;/li&gt;
      &lt;li&gt;Fehler in der Überprufung von Kreditkarten behoben.&lt;/li&gt;
      &lt;/ul&gt;
    </releasenotes>
    <manual link="http://www.jmillers.com/hotel/manual.de.html" />
    <forum link="http://www.typolight.org/forum/viewtopic.php?id=5492" />
    <shop link="http://www.jmillers.com/shop/article/hotel.de.html" />
  </language>
 </extension>
</code>







==== XML File Explanation ====

<code>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE typolightpackage>
</code>

**Description**

  * Header lines.
  * Mandatory.
  * Once at file begin.

\\ \\
<code>
<extension name="hotelres" date="20080422">
</extension>
</code>

**Description**

  * Encloses the extension block. 
  * Mandatory.

**Attributes**

  * name (optional):\\ The name (extension id) is available after creating a new extension in the repository. If no name is available (for example private package), you may ommit this attribute. However without a valid extension name, the live update feature will not be available.

  * date (optional):\\ The package creation date in format YYYYMMDD. It might be different from the release date (see release tag), for example when downloading from the repository the package is created on the fly and the package creation date is the current date.

\\ \\
<code>
  <author user="jmill" name="John Miller" />
</code>

**Description**

  * Author information.
  * Mandatory.

**Attributes**

  * user (mandatory, 32 chars):\\ The TYPOlight username in tl_member.
  * name (mandatory, 32 chars):\\ The real name of the author or package manager.

\\ \\
<code>
  <copyright>&copy; 2008, 2009 by John Miller Web Services</copyright>
</code>

**Description**

  * The copyright notice to display.
  * Optional.

**Text**

  * HTML Entities allowed, but no HTML tags.
  * 128 chars max.

\\ \\
<code>
  <license>GNU Lesser Public License (LGPL) Version 3</license>
</code>

**Description**
 
  * The license information.
  * Optional.

**Text**

  * HTML tags allowed: none.
  * 64 chars max.

\\ \\
<code>
  <classification type="commercial" category="application" />
</code>

**Description**
 
  * Classify the extension.
  * Mandatory.

**Attributes**

  * type (mandatory). Must be one of:
    * ''free'': Available for free.
    * ''private'': Not visible in regular listings. A key is required for installation.
    * ''commercial'': A installation key must be purchased at the vendors shop.

  * category (mandatory). Must be one of:
    * ''application'': The package forms a complete application of its own.
    * ''utility'': A utility, typically for the backend only.
    * ''template'': A template made up by a set of tpl files and/or style sheets.
    * ''widget'': A form widget. 
    * ''plugin'': A php5 or Javascript library.
    * ''other'': Anything not fitting into the categories above.


\\ \\
<code>
  <release version="10000127" build="103" date="20080421" />
</code>

**Description**

  * The release version number and status. 
  * Mandatory.

**Attributes**

  * version (mandatory):\\ The [[extensions:repository:package#Version encoding|encoded version number]].

  * build (mandatory):\\ The [[extensions:repository:package#Build numbers|release build number]].\\ The build number in the XML file is ignored when uploading a package to the repository.

  * date (mandatory):\\ The release date in format YYYYMMDD.

\\ \\
<code>
  <typolight minversion="20040059" maxversion="20040079" />
</code>

**Description**
 
  * Compatibility information to the TYPOlight core.
  * Mandatory.

**Attributes**

  * minversion (mandatory):\\ The oldest [[extensions:repository:package#Version encoding|version]] this release of the extension is compatible to.\\ If no such core version was found, the repository will display "unknown".
  * maxversion (mandatory):\\ The newest [[extensions:repository:package#Version encoding|version]] this release of the extension is compatible to.\\ If no such core version was found, the repository will display "unknown".

\\ \\
<code>
  <script class="HotelInstaller" />
</code>

**Description**
 
  * An overload of the RepositoryInstaller class, used to execute special operations upon install, upgrade and un-install. API documentation of the RepositoryInstaller class will follow.
  * Optional.

**Attributes**

  * class (64 chars): The overload class name.

\\ \\
<code>
  <requiredextension name="bbcode" minversion="80057" maxversion="10000029" />
  <requiredextension name="creditcard" minversion="10050059" maxversion="10090039" />
</code>

**Description**
 
  * Other extensions, this extension depends on.
  * Optional.
  * Arbitrary number of elements with unique names.

**Attributes**

  * name (mandatory):\\ The name (key) of the other extension.
  * minversion (mandatory):\\ The oldest [[extensions:repository:package#Version encoding|version]] this release of the extension is compatible to.
  * maxversion (mandatory):\\ The newest [[extensions:repository:package#Version encoding|version]] this release of the extension is compatible to.

 
\\ \\
<code>
  <language code="en">
  </language>
</code>

**Description**

  * Translation container.
  * One element at least.

**Attributes**

  * code (mandatory, 2 chars):\\ The language ISO code.

\\ \\
<code>
  <translator user="heugen" name="Horst-Eugen Leicht" />
</code>

**Description**

  * Translator information.
  * Mandatory

**Attributes**

  * user (mandatory, 64 chars):\\ The TYPOlight username from tl_member.
  * name (mandatory, 64 chars):\\ The real name of the translator. (Real person, not company)

\\ \\
<code>
  <searchtags>hotel,reservation,room,rent</searchtags>
</code>

**Description**
 
  * Search tags for the extension as comma separated list.
  * Optional.
 
**Text**

  * HTML tags allowed: none.
  * Min 1 tag, max 5 tags per element.
  * 128 chars

\\ \\
<code>
  <title>Hotel Reservations</title>
</code>

**Description**
 
  * The title to display.
  * Mandatory.

**Text**

  * HTML tags allowed: none.
  * 64 chars

\\ \\
<code>
    <teaser>Reservation and booking of hotel rooms</teaser>
</code>

**Description**
 
  * Short description to display.
  * Optional.

**Text**

  * HTML tags allowed: none.
  * 128 chars


\\ \\
<code>
  <description>
    Allow guests to book hotel room reservations.&lt;br/&gt;
    Online feedback about success, plus email confirmation.&lt;br/&gt;
    Optional commission payment by credit card.
  </description>
</code>

**Description**
 
  * Full description to display.
  * Optional.

**Text**

  * HTML tags allowed: br, ul, li.
  * 1024 chars


\\ \\
<code>
  <releasenotes>
    This is just a small update:&lt;br/&gt;
    &lt;ul&gt;
    &lt;li&gt;Added field for customers skype address.&lt;/li&gt;
    &lt;li&gt;Fixed bug in credit card verification.&lt;/li&gt;
    &lt;/ul&gt;
  </releasenotes>
</code>

**Description**
 
  * The release notes and change log for this current release.
  * Optional.

**Text**

  * HTML tags allowed: br, ul, li.
  * 1024 chars

\\ \\
<code>
  <manual link="http://www.jmillers.com/hotel/manual.html" />
</code>

**Description**
 
  * Link to the manual.
  * Optional.

**Attributes**

  * link (255 chars):\\ URL of the manual.

\\ \\
<code>
  <forum link="http://www.typolight.org/forum/viewforum.php?id=24" />
</code>

**Description**
 
  * Link to the forum.
  * Optional.

**Attributes**

  * link (255 chars):\\ URL of the sub-forum or topic.

\\ \\
<code>
  <shop link="http://www.jmillers.com/shop/article/hotel.html" />
</code>

**Description**
 
  * Vendor shop link for commercial, donation link for free extensions.
  * Optional.

**Attributes**

  * link (255 chars):\\ URL of the vendor shop or donation facility.