Package Specification

Change log

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:

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

The archive naming scheme as TYPOlight_package_version_build.zip, for the example application this could therefore be TYPOlight_hotel_10000129_102.zip

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

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

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

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

Dates are in format YYYYMMDD.

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

1. 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.
2. 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.
3. 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.
4. 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.

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. For commercial extensions where the files and package are hosted on the vendors site, the repository can not detect file changes and automatically increment the build. The author can however make some small change to the meta data (for example to the release notes) to enforce a new build number after changing files.

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

<?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" demo="yes" category="application" />
  <release version="10000129" build="102" date="20080421" />
  <typolight minversion="20040059" maxversion="20040079" />
  <files soapwsdl="http://www.jmillers.com/services/typolight.wsdl" />
  <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>

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

Description

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

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

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.

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

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.

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

Description

• The copyright notice to display.
• Optional.

Text

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

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

Description

• The license information.
• Optional.

Text

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

  <classification type="commercial" demo="yes" category="application" />

Description

• Classify the extension.
• Mandatory.

Attributes

• type (mandatory). Must be one of:
  • free: Available for free.
  • commercial: A download token must be purchased at the vendors shop.

• demo (optional):
  When “yes” a restricted demo version can be installed without a download token.

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

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

Description

• The release version number and status.
• Mandatory.

Attributes

• version (mandatory):
  The encoded version number.

• build (mandatory):
  The 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.

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

Description

• Compatibility information to the TYPOlight core.
• Mandatory.

Attributes

• minversion (mandatory):
  The oldest 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 version this release of the extension is compatible to.
  If no such core version was found, the repository will display “unknown”.

  <files soapwsdl="http://www.jmillers.com/services/typolight.wsdl" />

Description

• File container.
• Optional (used for commercial extensions).

Attributes

• soapwsdl (optional, 255 chars):
  The custom SOAP service WSDL file, where files are fetched from.
  Used for commercial extensions not having the files in the package.

  <script class="HotelInstaller" />

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.

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

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 version this release of the extension is compatible to.
• maxversion (mandatory):
  The newest version this release of the extension is compatible to.

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

Description

• Translation container.
• One element at least.

Attributes

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

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

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)

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

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

  <title>Hotel Reservations</title>

Description

• The title to display.
• Mandatory.

Text

• HTML tags allowed: none.
• 64 chars

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

Description

• Short description to display.
• Optional.

Text

• HTML tags allowed: none.
• 128 chars

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

Description

• Full description to display.
• Optional.

Text

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

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

Description

• The release notes and change log for this current release.
• Optional.

Text

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

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

Description

• Link to the manual.
• Optional.

Attributes

• link (255 chars):
  URL of the manual.

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

Description

• Link to the forum.
• Optional.

Attributes

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

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

Description

• Vendor shop link for commercial, donation link for free extensions.
• Optional.

Attributes

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