Anatomy of TYPO3 Extension

Exclusive offer: get 50% off this eBook here
TYPO3 Extension Development

TYPO3 Extension Development — Save 50%

Developer's guide to creating feature rich extensions using the TYPO3 API

$26.99    $13.50
by Dmitry Dulepov | May 2009 | Content Management Open Source PHP

This article by Dmitry Dulepov describes TYPO3 extensions from the developer's point of view. After reading this article, the reader will have basic knowledge of extension structure, files, and how extensions interact with TYPO3. This knowledge is necessary for extension planning and implementation.

TYPO3 Extension Categories

All TYPO3 extensions are classified into several predefined categories. These categories do not actually differentiate the extensions. They are more like hints for users about extension functionality. Often, it is difficult for the developer to decide which category an extension should belong to. The same extension can provide PHP code that fits into many categories. An extension can contain Frontend (FE) plugins, Backend (BE) modules, static data, and services, all at once. While it is not always the best solution to make such a monster extension, sometimes it is necessary. In this case, the extension author should choose the category that best fits the extension's purpose. For example, if an extension provides a reservation system for website visitors, it is probably FE related, even if it includes a BE module for viewing registrations. If an extension provides a service to log in users, it is most likely a service extension, even if it logs in FE users. It will be easier to decide where the extension fits after we review all the extension categories in this article.

Choosing a category for an extension is mandatory. While the TYPO3 Extension Manager can still display extensions without a proper category, this may change and such extensions may be removed from TER (TYPO3 Extension Repository) in the future.

The extension category is visible in several places. Firstly, extensions are sorted and grouped by category in the Extension Manager. Secondly, when an extension is clicked in the Extension Manager, its category is displayed in the extension details.

If an extension's category is changed from one to another, it does not affect extension functionality. The Extension Manager will show the extension in a different category. So, categories are truly just hints for the user. They do not have any significant meaning in TYPO3.

So, why do we care and talk about them? We do so because it is one of those things that make a good extension. If an extension developer starts making a new extension, they should do it properly from the very beginning. And one of the first things to do properly is to decide where an extension belongs.

So, let's look into the various extension categories in more detail.

Category: Frontend

Extensions that belong to the Frontend category provide functionality related to the FE. It does not mean that they generate website output. Typically, extensions from the FE category extend FE functionality in other ways. For example, they can transform links from standard /index.php?id=12345 to /news/new-typo3-bookis-out.htm. Or, they can filter output and clean it up, compress, add or remove HTML comments, and so on. Often, these extensions use one or more hooks in the FE classes. For example, TSFE has hooks to process submitted data, or to post‑filter content (and many others).

Examples of FE extensions are source_optimization and realurl.

Category: Frontend plugins

Frontend plugins is possibly the most popular extension category. Extensions from this category typically generate content for the website. They provide new content objects, or extend existing types of content objects.

Typical examples of extensions from the Frontend plugins category are tt_news, comments, ratings, etc.

Category: Backend

Extensions from the Backend category provide additional functionality for TYPO3 Backend. Often, they are not seen inside TYPO3 BE, but they still do some work. Examples of such extensions are various debugging extensions (such as rlmp_ filedevlog) and extensions that add or change the pop-up menu in the BE (such as extra_page_cm_options system extension). This category is rarely used because extensions belonging to it are very special.

Category: Backend module

Extensions from this category provide additional modules for TYPO3 BE. Typical examples are system extensions such as beuser (provides Tools | Users module) or tstemplate (provides Web | Template module).

Category: Services

Services extend core TYPO3 functionality. Most known and most popular service extensions are authentication services. TYPO3 Extension Repository contains extensions to authenticate TYPO3 users over phpBB, vBulletine, or LDAP user databases.

Services are somewhat special and will not be covered in this article. Extension developers who are interested in the development of services should consult appropriate documentation on the typo3.org website.

Category: Examples

Extensions from this category provide examples. There are not many, and are typically meant for beginners or for those who want to learn a specific feature of TYPO3, or features that another TYPO3 extension provides.

Category: Templates

Extensions from this category provide templates. Most often, they have preformatted HTML and CSS files in order to use them with the templateautoparser extension or map with TemplaVoila. Sometimes, they also contain TypoScript templates, for example, tmpl_andreas01 and tmpl_andreas09 extensions. Once installed, they provide pre‑mapped TemplaVoila templates for any website, making it easy to have a website up and running within minutes.

Category: Documentation

Documentation extensions provide TYPO3 documentation. Normally, TYPO3 extensions contain documentation within themselves, though sometimes, a document is too big to be shipped with extensions. In such cases, it is stored separately. There is an unofficial convention to start an extension key for such extensions with the doc_ prefix (that is, doc_indexed_search).

Category: Miscellaneous

Everything else that does not fit into any other category goes here; typical examples are skins. But do not put your extension here if you just cannot decide where it fits. In all probability, it should go into one of the other categories, not into Miscellaneous.

Extension Files

TYPO3 extensions consist of several files. Some of these files have predefined names, and serve a predefined purpose. Others provide code or data but also follow certain naming conventions. We will review all the predefined files in this article and see what purpose they serve. We will look into the files according to their logical grouping.

While reading this section, you can take any extension from the typo3conf/ext/ directory at your TYPO3 installation and check the contents of each discussed file. Some files may be missing if the extension does not use them. There is only one file which is mandatory for any TYPO3 extension, ext_emconf.php. We will start examining files starting from this one.

Common Files

All files from this group have predefined names, and TYPO3 expects to find certain information in them. Hacking these files to serve another purpose or to have a different format usually results in incompatibility with other extensions or TYPO3 itself. While it may work in one installation, it may fail in others. So, avoid doing anything non-standard with these files.

ext_emconf.php

This is the only required file for any TYPO3 extension. And this is the only file that should be modified with great care. If it is corrupt, TYPO3 will not load any extension.

This file contains information on the TYPO3 Extension Manager. This information tells the Extension Manager what the extension does, provides, requires, and conflicts with. It also contains a checksum for each file in the extension. This checksum is updated automatically when the extension is sent to TER (TYPO3 Extension Repository). The server administrator can easily check if anyone has hijacked the extension files by looking into the extension details in the Extension Manager. The modified files are shown in red. Here is a tip. If you (as an extension developer) send your own extension directly to the customer (bypassing TER upload), or plan to use it on your own server, always update the ext_emconf.php file using the Backup/Delete function of the Extension Manager. This will ensure that TYPO3 shows up-to-date data in the Extension Manager.

Here is an example of a ext_emconf.php file from the smoothuploader extension:

<?php
#############################################################
# Extension Manager/Repository config file for ext: ↵ # "smoothuploader"
# Auto generated 29-02-2008 12:36
# Manual updates:
# Only the data in the array - anything else is removed by ↵ # next write.
# "version" and "dependencies" must not be touched!
#############################################################
$EM_CONF[$_EXTKEY] = array(
'title' => 'SmoothGallery Uploader',
'description' => 'Uploads images to SmoothGallery',
'category' => 'plugin',
'author' => 'Dmitry Dulepov [Netcreators]',
'author_email' => 'dmitry@typo3.org',
'shy' => '',
'dependencies' => 'rgsmoothgallery',
'conflicts' => '',
'priority' => '',
'module' => '',
'state' => 'beta',
'internal' => '',
'uploadfolder' => 0,
'createDirs' => '',
'modify_tables' => 'tx_rgsmoothgallery_image',
'clearCacheOnLoad' => 0,
'lockType' => '',
'author_company' => 'Netcreators BV',
'version' => '0.3.0',
'constraints' => array(
'depends' => array(
'rgsmoothgallery' => '1.1.1-',
),
'conflicts' => array(
),
'suggests' => array(
),
),
'_md5_values_when_last_written' => 'a:12:{s:9:...;}',
'suggests' => array(
),
);
?>

The variable _md5_values_when_last_written is shortened in the listing above.

TYPO3 Extension Development Developer's guide to creating feature rich extensions using the TYPO3 API
Published: September 2008
eBook Price: $26.99
Book Price: $44.99
See more
Select your format and quantity:

The following fields are used in the $EM_CONF array:

Field name

Field description

title

Extension title. This is visible in the Extension Manager and TYPO3 Extension Repository.

description

Description of the extension.

category

Category to which the extension belongs

author

Extension author's name.

author_email

Extension author's e-mail.

author_company

Extension author's company.

shy

If set to 1, the extension will be hidden if Display shy extensions is not checked in the Extension Manager. There are no valid reasons to make extensions shy. This flag is usually set for system extensions that appear in every TYPO3 installation. It just makes the Extension Manager less crowded.

dependencies

Obsolete; should not be used.

conflicts

Obsolete; should not be used.

priority

This field is used for prioritizing extensions in certain cases. Leave it untouched.

module

Lists extension's Backend modules. Left menu uses this field to find information about modules.

state

Can be one of the following values:

  • alpha

           Initial development, not ready for release,
           some functions may work, has bugs.          

  • beta

          Ready for testing, may have bugs.

  • stable

          Extension is mature, can be used in production.

  • experimental

          Extension may change TYPO3 behavior in an
          unusual way or may do something unusual.

It is important to change state appropriately during extension development. It is very common to see beta extensions that are used for years on many production sites. Unfortunately, this is typical in the open source software world; products stay beta for ages and never become ready. Do not follow this practice; set

your extension's state to stable after you fix major bugs, and get positive feedback from users. stable does not mean you have to stop developing it. It means that other people may use it in production.

internal

Set if this extension is internal for TYPO3. May not be used by any custom extension.

uploadfolder

Obsolete, but still used. This declares the name of the directory, related to TYPO3 web root, where files will be uploaded. Currently, this serves only informational purposes because actual upload directories are declared for each database table in the table configuration array ($TCA). We will talk about it when we discuss

ext_tables.php and tca.php.

createDirs

Comma delimited list of directories to be created during extension installation. Directories must be relative to TYPO3 web root directory.

modify_tables

Comma delimited list of tables modified by this extension. System tables or tables from other extensions can be modified by placing certain SQL into the ext_tables.sql file. Each table name follows certain naming conventions. If an extension modifies a table with a non matching name but does not list it in this property, the Extension Manager will show naming errors.

clearCacheOnLoad

If set, clears cache when the extension is installed. Useful only for extensions that modify website output immediately after installation (such as HTML clean-up extensions or content compressors). Do not set if not necessary.

lockType

This field allows to "lock" extensions to a certain type of

installation (global, local, or system). Generally, this field should never be modified. Modification may cause problems with the installation of the extension.

Field name

Field description

version

This indicates the extension version. Normally modified by the Extension Manager when the extension is uploaded to TER. However, if the extension is private, the version should be modified manually each time the extension leaves the developer's computer.

Version follows the PHP versioning pattern. It consists of three digits, each representing a change in one of the following things:

  • major version (also called release version)
  • minor version
  • bug fix version

The first number is updated when the extension has a major change in behavior, such as major feature added, completely rewritten code, and so on.

The second number is updated when the extension is developed, or some minor features are introduced.

The last number is updated when the new version only fixes bugs.

constraints

This element consists of three sub-elements, all having an identical structure. Each sub-element is an array, where the array key is an extension key, and its value is zero, one, or two version numbers.

A zero version number means that the constraint applies to any version of the extension while one and two numbers mean that the constraint applies to a version range. Two version numbers separated by a dash imply "from version - to version" (inclusive)

and for one number, the versions of the extension to which the constraint applies depend on the position of the version number and the dash. Examples:

  • 'extkey' => ''

           Applies to any version of the extension with an
           extension  key extkey

  • 'extkey' => '1.0.0-'

           Means that the constraint applies to the  
           extension with version number 1.0.0 and higher

  • 'extKey' => '-1.0.0'

           Means that all versions prior and including 1.0.0
           are caught by this constraint

  • 'extkey' => '0.5.0-1.0.0'

          Means that the constraint works for versions
          from 0.5.0 to 1.0.0 (both inclusive)

There are three types of constraints:

  • depends

          The Extension Manager will require listed

          extensions to be installed before the current

          extension can be installed. Generally, it means

          that the current extension uses listed extensions
          in some way.

  • conflicts

          The Extension Manager will not allow installation

          of this extension if it is installed from this
          constraint. A version check in this constraint      
          works in TYPO3 version 4.1.7 and higher.

  • suggests

          The Extension Manager will prompt for the

          installation of the extensions listed in this
          constraint, but will not insist on doing so.
          This constraint is useful when an extension     
          extends many extensions all at once. For    
          example,  the comments_ic extension extends  
          tt_news and commerce with an ability to close   
          comments individually for each item.

          It suggests these two extensions for installation.

          Notice that it gives an error if these two  
          extensions are placed into the depends
          constraint because then comments_ic may not
          be used only with tt_news (the Extension
          Manager will require commerce as well!)

suggests

Obsolete; do not use.

 

ext_conf_template.txt

This file contains the definitions of installation‑wide system settings for the extension. Each setting is a name/value combination. Names and values are separated by an "equal to" sign. The spaces in name and value are stripped. Here is how such a configuration looks in the Extension Manager:

 TYPO3 Extension Development

Each name/value pair can be prepended with a special comment. A comment defines data type, title, and description for each name/value pair. Here is an example:

# cat=basic/enable; type=string; label=Database URLconnection string:
mnoGoSearch connection URL
dbaddr = mysql://user:pass@host/dbname?dbmode=blob&LiveUpdates=yes

The first line is a special comment. It also consists of name/value pairs, separated by a semicolon. The value from this file serves as a default value. The same syntax is used for TypoScript constants.

Name

Value

cat

Format is "category/subcategory: title" (title is usually omitted). This field is used to group settings. It is possible to have, for example, database settings separate from rendering settings. Valid values for categories are:

  • basic

          Any general options, most likely to be changed.
          Mandatory database configuration is an 
          example.

  • menu

          Configuration for menu. This is rarely used for
          extension installation, but sometimes used for
          TypoScript constants.

  • page

Page-related options. Also, typically used for constants, not for extension installation.

  • advanced

          Advanced options go here.

Categories may have subcategories. Available subcategories are:

  • enable

          Used for options that enable or disable primary
          functions of a template.

  • dims

          Dimensions of all kinds; pixels, widths, heights
          of images, frames, cells, and so on.

  • file

           Files such as background images, fonts, and so
           on.

  • typo

          Typography and related constants (rarely used).

  • color

          Color setup (rarely used).

  • links

          Usually used for link targets.

  • language

          Language related settings.

type

A field will be rendered according to its type. Valid field types are:

  • string

          This is a default type. It is just a string with no
          conversion or validation.

  • int

          Integer number (or 0 if a noninteger is entered).

  • int+

          Positive integer number (or 0 if a noninteger is
          entered).

  • color

          HTML color (with color selector control).

  • file[extension-list]

          File selector, will allow selection of only the files
          with extensions from the list.

  • wrap

          HTML to wrap around content.

  • boolean

          Rendered as a checkbox, and has two state
          values.

  • options[option-list]

          A comma-delimited list (without spaces!) as

          label/value pairs.

label

Label and description, separated by a colon

These settings are saved by the Extension Manager and can be accessed programmatically:

$sysconf = unserialize($GLOBALS['TYPO3_CONF_VARS']['EXT']
['extConf']['extkey']);
if ($sysconf['enable']) {

These settings are used when they are system-wide. Anything which is site-dependent should go into the TypoScript setup for FE plugins (see the following section).

ext_tables.php

This file performs three functions:

  • Declares extension tables.
  • Declares fields for system or other extension tables extended by this extension.
  • FE plugins and BE modules are registered with TYPO3 in this file.

The table definitions look quite simple. This information adds the definition of a new table to the TYPO3 global variable named $TCA (TCA stands for "Table Configuration Array").

The variable $TCA is one of the most important variables in TYPO3. It is an array where keys are database table names, and values are arrays of certain structure that define how fields in the database should look in TYPO3 BE forms, and also which fields have special meaning.

Each table definition in $TCA consists of several sections but ext_tables.php declares only one section, named ctrl. This saves a lot of memory if the table is not being used in a particular execution because table definitions may be really huge. TYPO3 includes all ext_tables.php files from all extensions. Thus, all tables are known to TYPO3. If necessary, TYPO3 will load a full table definition using the dynamicConfigFile property from the ctrl section.

Additionally, the ctrl section contains other important fields such as table name, table icon, and a list of fields that serve a special purpose.

Here is an example of a table definition from ext_tables.php:

$TCA['tx_ratings_iplog'] = array(
'ctrl' => array (
'title' => 'LLL:EXT:ratings/locallang_db.xml:tx_ratings_
iplog',
'label' => 'reference',
'tstamp' => 'tstamp',
'crdate' => 'crdate',
'cruser_id' => 'cruser_id',
'default_sortby' => 'ORDER BY crdate DESC',
'dynamicConfigFile' => t3lib_extMgm::extPath($_EXTKEY).'tca.
php',
'iconfile' => t3lib_extMgm::extRelPath($_EXTKEY) .
'icon_tx_ratings_iplog.gif',
),
);

Information on ctrl and other sections can be found in the TYPO3 Core API document on the typo3.org website.

Tables are extended in a similar way. But instead of defining the ctrl section, new columns are defined and added to the existing tables using TYPO3 functions. We will talk more about column definition syntax in the section about tca.php. Here we will just see one example:

// New columns
$tempColumns = array(
'tx_ratings_enable' => array(
'exclude' => 1,
'label' => 'LLL:EXT:ratings/locallang_db.xml:tt_news.tx_
ratings_enable',
'config' => array(
'type' => 'check',
'items' => array(
array('', '')
),
'default' => '1'
)
),
);
t3lib_div::loadTCA('tt_news');
t3lib_extMgm::addTCAcolumns('tt_news', $tempColumns, 1);
t3lib_extMgm::addToAllTCAtypes('tt_news', ↵ 'tx_ratings_
enable;;;;1-1-1');

Here, one new column is defined for the tt_news table. The definition is set to $tempColumns. The column is set to type check, which means that an additional checkbox will be displayed in the tt_news item. All configuration options for check and other column types are explained in the TYPO3 Core API document.

The last three lines add the above definition to the TCA. The first line loads the full TCA definition for the tt_news table. This is necessary because the ext_tables.php file includes only the ctrl section for each table. The next line actually adds a new column definition to the table. The third line tells TYPO3 where to display this new column. In this particular case, it just added the new column to the end of the existing fields. It is possible to put columns before or after the existing fields too. See the documentation for t3lib_extMgm::addToAllTCAtypes in the source code for more information.

The FE plugin addition looks like this:

t3lib_extMgm::addPlugin(array(
'LLL:EXT:ratings/locallang_db.xml:tt_content.list_type_pi1',
$_EXTKEY . '_pi1'), 'list_type');

Usually, this code is generated automatically when a new extension is created. The first parameter is an array. It associates the plugin with a human‑readable name of the plugin. The second parameter tells TYPO3 about the type of the plugin. Normally, it is list_type but it can also have another value (for example, site maps).

ext_tables.sql

This file includes database table definitions written in SQL. TYPO3 extensions may define their own tables or extend existing system or other extension tables. These two cases are different and require different SQL statements.

If an extension defines its own tables, syntax of such a definition should exactly be the same as produced by the SHOW CREATE TABLE SQL statement in the MySQL console. (Even if the actual database is Oracle or MSSQL, definitions must have MySQL syntax). No additional spaces (or missing spaces) and no position change for field modifiers is allowed. This limitation exists due to the fact that TYPO3 parses SQL to see if it needs to update the table structure. The only parts that can be removed are the CHARACTER SET, ENGINE, and COLLATE directives. The following example shows a table definition from the ratings extension. It has ENGINE set to InnoDB to ensure high concurrency of data.

#
# Table structure for table 'tx_ratings_data'
#
CREATE TABLE tx_ratings_data (
uid int(11) NOT NULL auto_increment,
pid int(11) DEFAULT '0' NOT NULL,
tstamp int(11) DEFAULT '0' NOT NULL,
crdate int(11) DEFAULT '0' NOT NULL,
cruser_id int(11) DEFAULT '0' NOT NULL,
reference text NOT NULL,
rating int(11) DEFAULT '0' NOT NULL,
vote_count int(11) DEFAULT '0' NOT NULL,
PRIMARY KEY (uid),
KEY parent (pid),
KEY reference (reference(16))
) ENGINE = InnoDB;

Another case is table modification. Normally, such changes are made with ALTER TABLE SQL statements, but TYPO3 uses another way, partial table definitions. Here is an example from the same ratings extension:

#
# Table structure for table 'tt_news'
#
CREATE TABLE tt_news (
tx_ratings_enable int(1) DEFAULT '1' NOT NULL,
);

It looks like a normal CREATE TABLE statement except that it does not have all the fields required by TYPO3 (such as uid and pid) and has a comma after the definition of the tx_ratings_enable field. So technically, such SQL is neither valid nor does it represent a valid TYPO3 table. But it tells TYPO3 that the Extension Manager should merge the tt_news table definition from some other extension with this definition and update the table to show the result of the merge, if necessary.

No other SQL statements can appear in this file.

TYPO3 Extension Development Developer's guide to creating feature rich extensions using the TYPO3 API
Published: September 2008
eBook Price: $26.99
Book Price: $44.99
See more
Select your format and quantity:

ext_tables_static+adt.sql

This file is very similar to ext_tables.sql except that it has table creation statements for static tables and may have data definition statements (SQL INSERT statements).

Static tables contain information that does not change. For example, the static_info_tables extension contains static tables with language codes, taxes, currencies, country names, character sets, and so on. This information never changes while TYPO3 is running (though it may be updated if the tax rate changes). So, it is inserted statically.

The table definition statements do not differ from those in ext_tables.sql.

The data definition statements are simple SQL INSERT statements. They must insert all fields (including automatically incrementing uid field), and must not use MySQL extended INSERT syntax. The easiest way to create proper statements is to add data to the database manually and use the mysqldump program with c ‑n ‑d ‑compact‑extended‑insert=FALSE options to export data.

ext_localconf.php

This file usually contains hook definitions and registers TypoScript from the FE plugins with TYPO3. Here is an example from the irfaq extension:

// Add plugin's TypoScript
t3lib_extMgm::addPItoST43($_EXTKEY, 'pi1/class.tx_irfaq_pi1.php',
'_pi1', 'list_type', 1);
// TCEmain hooks for managing related entries
$GLOBALS ['TYPO3_CONF_VARS']['SC_OPTIONS']
['t3lib/class.t3lib_tcemain.php']
['processDatamapClass']['irfaq'] =
'EXT:irfaq/class.tx_irfaq_tcemain.php:tx_irfaq_tcemain';
$GLOBALS ['TYPO3_CONF_VARS']['SC_OPTIONS']
['t3lib/class.t3lib_tcemain.php']
['processCmdmapClass']['irfaq'] =
'EXT:irfaq/class.tx_irfaq_tcemain.php:tx_irfaq_tcemain';

Notice how TYPO3 file references are used in hook declaration.

ext_icon.gif

This is an icon to show in the Extension Manager, to the left of extension title. An icon should be a 16x16 pixels, nonanimated, transparent GIF. Many extensions use 18x16 pixels because it looks better in the Extension Manager. But the TYPO3 Extension Repository expects a 16x16 pixels image and will stretch it to this size.

tca.php

This file contains complete TCA definitions for each table. It is included when code calls the t3lib_div::loadTCA function with a table name. TYPO3 then looks in the ctrl section in $TCA for this table. It locates the dynamicConfigFile property and loads the corresponding file.

Let's see what this file looks like. We will look at the ratings extension again. The following example is long and it shows three columns with their definitions.

$TCA['tx_ratings_data'] = array(
'ctrl' => $TCA['tx_ratings_data']['ctrl'],
'columns' => array (
'reference' => array(
'exclude' => 1,
'label' => 'LLL:EXT:ratings/locallang_db.xml:tx_ratings_
data.reference',
'config' => array(
'type' => 'group',
'internal_type' => 'db',
'allowed' => '*',
'size' => 1,
'minitems' => 1,
'maxitems' => 1,
)
),
'rating' => array(
'exclude' => 1,
'label' => 'LLL:EXT:ratings/locallang_db.xml:tx_ratings_
data.rating',
'config' => array(
'type' => 'input',
'size' => '4',
'max' => '4',
'eval' => 'int',
'checkbox' => '0',
'range' => array(
'upper' => '1000',
'lower' => '10'
),
'default' => 0
)
),
'vote_count' => array(
'exclude' => 1,
'label' => 'LLL:EXT:ratings/locallang_db.xml:tx_ratings_
data.vote_count',
'config' => array (
'type' => 'input',
'size' => '4',
'max' => '4',
'eval' => 'int',
'checkbox' => '0',
'range' => array (
'upper' => '1000',
'lower' => '10'
),
'default' => 0
)
),
),
'types' => array(
'0' => array(
'showitem' => 'reference;;;;1-1-1,
rating, vote_count')
),
);

First, the original ctrl section is set to $TCA. There is no need to duplicate it from ext_tables.php. It is easier to set it to the existing value. Next is the columns section. It contains definitions for each column. Definitions are explained in the TYPO3 Core API document, and the reader is encouraged to look up what each definition in the example means. Notice that each field type has its own set of properties. For example, input type has an eval property, which may trim the field value or convert it to a date. This property does not exist for other field types. Always look for properties in the TYPO3 Core API document. Specifying a property with a hope that it will work is useless if the property is not defined in the TYPO3 Core API document.

One important feature of TCA is its record types. One field in the table can be designated as a type field. When the type field changes, the BE form for the record is reloaded, and another set of fields is shown. Type fields are defined in the ctrl section using the type property. The value of the type field (usually integer) is mapped to keys in the types section of the table definition in TCA (see previous example). If there is no type field for the table, the default value 0 is used as type. The types section in the TCA definition for the table shows which fields are available in the form, and in which order. Again, "TYPO3 Core API" describes how this section looks. In the simplest case, it just lists fields. It is very important to remember that a field will not be shown in the form if it is not included in the types definition.

Another interesting feature of TCA is the display of conditions and the requestUpdate fields.

As we saw earlier, the type field can change the look of the form. But sometimes it is not enough, and some fields can be shown or hidden depending on the value of the other fields. The displayCond property exists, and the field can be shown or hidden depending on the condition. Conditions may be set depending on the other fields in the same record, extension status (installed or not), record status (new or not). Newer TYPO3 versions may introduce other conditions.

The requestUpdate fields are similar to the type field because they cause the form to reload when the value of the field changes. They do not have anything similar to the types section in TCA, but conditions may use the value of these fields to show or hide other fields. This allows us to create truly dynamic and rich forms. There is only one thing to bear in mind: do not become obsessed with the technical possibilities and forget to think about the user who is going to work with forms! All these technical possibilities are made for better user satisfaction, but they must be used with care. It is easy to create a form that will change too often and irritate users. So, just be careful!

class.ext_update.php

If this file is present in the extension, the Extension Manager will add a new function to the list of functions available for the extension. The function is named UPDATE!. When a user chooses the function, the Extension Manager will load the file and pass control to the class. The class can propose updates to the user and perform these updates when the user confirms them. For example, this class may convert the extension's database structure from old to new, or change values of fields using complex logic. This file is so rarely used that most extension developers are completely unaware of this feature.

The class in this file must be named ext_update. It must include at least the following two public methods:

  • access
  • The Extension Manager calls this method when a user clicks on the extension title in the Extension Manager and asks for details. If the method returns true, the Extension Manager will add an additional item to the list of functions. The item will be named "UPDATE!".

     TYPO3 Extension Development

    This method is typically used to check if an update should be performed at all. The method name is historical but misleading because the Extension Manager is visible only to "admin" users, and admin users always have access to everything.

  • main
  • This method generates content. Typically, it is a list of things to update and an HTML form with a button to confirm these updates. When a user clicks the button, ext_update performs the necessary updates.

Frontend Plugin Files

FE plugins generate custom content for websites. Typical examples of FE plugins are photo galleries, guestbooks, news systems, and reports.

FE plugins in TYPO3 do not have many requirements from the TYPO3 side. Plugins must follow TYPO3 naming conventions and must return content instead of outputting it directly. The simplest FE plugin file will contain a function, whose name starts with user_. The function will accept two arguments and will return a string (generated HTML content). While it is possible to make plugins this way, plugins are typically made as classes that extend a special system class (tslib_pibase). The tslib_pibase class provides many convenient methods for FE plugins such as localization handling, parameter gathering, and link generation.

pi Files

Typically, FE plugins are located in subdirectories prefixed by pi and followed by a number inside the extension (for example, pi1, pi2, etc). The numbers are not significant and do not have to be consecutive. However, plugin class name typically reflects the directory in its name (for example, pi1/class.tx_extkey_pi1.php).

There can be other files in the pi directory. There can be additional class files, which must follow naming conventions as usual (for example, class tx_myext_myclassin class.tx_myext_myclass.php). External files can be included in the lib/ subdirectory (unofficial convention). Templates are typically included in the res/ subdirectory inside the pi directory, which is in the extension's directory.

TypoScript Templates

Often, FE plugins require certain TypoScript to be set. Such TypoScript may include references to templates or page IDs where records are stored. The TypoScript files are named constants.txt and setup.txt, and can be located either in the extension's directory, or in another subdirectory. If one of the files is empty, it is usually omitted. This saves some parsing time for TYPO3.

Files from the extension's directory are loaded by TYPO3 automatically and made available automatically everywhere in the FE. However, this slows down the FE and currently it is recommended that you put TypoScript files into a separate directory and include them manually in the main TypoScript setup of the website through the Web>Template module. Administrators will choose to edit the whole template record in that module and use Include static (from extensions) to include the extension's template in the main template.

To register an extension's TypoScript templates with TYPO3, the following code is included into the extension's ext_tables.php file:

t3lib_extMgm::addStaticFile($_EXTKEY, 'static/Ratings/',
'Ratings');

Here, the first parameter uses the variable that TYPO3 has automatically set to the value of the extension key before the inclusion of ext_tables.php. The next parameter is the relative path to the directory where constants.txt and setup.txtare located. The last parameter is the title of the template as shown in "Include static (from extensions)". This title is usually not localized (and it is in English!) because it is normally referred to by this name in the extension's manual.

Backend Module and its Files

Backend modules are usually located in the subdirectories prefixed by mod and followed by a number. A Backend module's mandatory file is named conf.php. It contains a description of the module. Here is an example of such a file:

<?php
// DO NOT REMOVE OR CHANGE THESE 3 LINES:
define('TYPO3_MOD_PATH',
'../typo3conf/ext/loginusertrack/mod1/');
$BACK_PATH = '../../../../typo3/';
$MCONF['name'] = 'web_txloginusertrackM1';

$MCONF['access'] = 'user,group';
$MCONF['script'] = 'index.php';
$MLANG['default']['tabs_images']['tab'] = 'moduleicon.gif';
$MLANG['default']['ll_ref'] =
'LLL:EXT:loginusertrack/mod1/locallang_mod.php';
?>

First, three code lines define paths to the module. They are updated by the Extension Manager when the extension is installed. The next line defines who can access the module. It can have one of the following values:

  • user
  • Access can be granted to the BE users on an individual basis.

  • group
  • Access can be granted to the BE user groups.

  • user,group
  • Access can be granted to BE users and/or groups. This is a typical setting.

  • admin
  • This indicates that the module is available only for admin users.

There is one important constraint. If the module resides in another module (for example, in User Tools or Admin Tools), and the user has no access to the parent module, then the current module will be not be accessible either. For example, if the module is placed inside the Tools module, it does not make sense to make it accessible to BE users and/or groups by mentioning user,group in the conf.php file. This is because the Tools module is accessible only to admin users.

The module name declares where the module is located. The part before the underscore is the parent's module name. For a top-level module, there is no underscore in the module name. However, introducing new top level modules should be avoided.

The line with the script property in $MCONF defines a file to be called when this module is accessed through TYPO3 module menu. Typically, it is index.php, which sometimes allows calling the module directly from the browser's address bar.

The remaining two lines define the icon and label for the module in the left module menu.

The module script defines a class that follows naming conventions. Typically, it is tx_extkey_module1. The number in the end corresponds to the number of mod directories.

Module Function Files

Some modules allow you to add functions. An example of such a module is Web>Functions or Web>Info. Functions are selected in the top selector box of the module.

Additional module functions from extensions are placed in directories prefixed with modfunc, and followed by a number. The class name follows certain naming conventions. Typically, it is named tx_extkey_modfunc1, and is located in the file, class.tx_extkey_modfunc1.php. A class must have a method named main without parameters, which returns the module function's content.

Module functions are registered with modules using code that looks similar to this code:

if (TYPO3_MODE == 'BE') {
t3lib_extMgm::insertModuleFunction(
'tools_em',
'tx_kickstarter_modfunc1',
t3lib_extMgm::extPath($_EXTKEY) .
'modfunc1/class.tx_kickstarter_modfunc1.php',
'LLL:EXT:kickstarter/locallang_db.xml:
moduleFunction.tx_kickstarter_modfunc1');
}

The first parameter of t3lib_extMgm::insertModuleFunction tells the module where to insert this new function. The next parameter is the function's class name. The third parameter is the function's file path, and the last parameter is the function's name from the module menu. All entries inside Web | Info are made from the additional functions shown in the following figure.

 TYPO3 Extension Development

Documentation Files

Normally, there is a single documentation file in an extension. It is always named manual.sxw and located in the doc/ subdirectory in the extension's directory.

Manuals must follow a certain format to be visible on the typo3.org website in the Documentation section. They must be OpenOffice 1.0 files, and must use the template available from the Documentation section of the typo3.org website under the title, Documentation template. There are instructions in this template about using styles and images. They must be followed for proper documentation.

Summary

In this article, we learned about extension files and extension classes. Now, the reader will have a basic knowledge of the extension structure and the extension components.

About the Author :


Dmitry Dulepov

Dmitry Dulepov is a TYPO3 core team member and developer of several popular extensions (such as RealURL, TemplaVoila, comments, ratings, and others). He is known by his active support of the TYPO3 community through TYPO3 mailing lists. In 2008 Dmitry won the contest to appear on the first TYPO3 playing cards. He runs a popular blog where he regularly publishes original tips and articles about various TYPO3 features. In addition to his continuous TYPO3 core and extension development, Dmitry provides support for the TYPO3 translation team on behalf of the core team.

Books From Packt

 

PHP and script.aculo.us Web 2.0 Application Interfaces
PHP and script.aculo.us Web 2.0 Application Interfaces

Magento: Beginner's Guide
Magento: Beginner's Guide

Flash with Drupal
Flash with Drupal

WordPress 2.7 Cookbook
WordPress 2.7 Cookbook

Plone 3 Theming
Plone 3 Theming

eZ Publish 4: Enterprise Web Sites Step-by-Step
eZ Publish 4: Enterprise Web Sites Step-by-Step

Building Websites with Joomla! 1.5
Building Websites with Joomla! 1.5

Mastering phpMyAdmin 3.1 for Effective MySQL Management
Mastering phpMyAdmin 3.1 for Effective MySQL Management

 

No votes yet

Post new comment

CAPTCHA
This question is for testing whether you are a human visitor and to prevent automated spam submissions.
q
s
v
r
M
4
Enter the code without spaces and pay attention to upper/lower case.
Code Download and Errata
Packt Anytime, Anywhere
Register Books
Print Upgrades
eBook Downloads
Video Support
Contact Us
Awards Voting Nominations Previous Winners
Judges Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software
Resources
Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software