This tutorial is tailored for windows users, I’m sure that users of other operating system know how to adapt it to their needs

A few days ago I’ve released a command line script that aims to build a Contao extension starting from a language pack.

The project page is located at http://bitbucket.org/zedseries/contao_languagepack_builder/, the script can be downloaded from http://bitbucket.org/zedseries/contao_languagepack_builder/get/v1.0.1.stable.zip

Requirements

• Php executable installed on your system (The script is written in php, so you must have a php cli installation to run it)
  If you do not have a php executable installed on your system, you can download a copy for windows at http://www.php.net/get/php-5.2.14-Win32.zip/from/a/mirror)
• Some basic knowledge of the command line
• An account on Contao.org (if you are a translator you can use your translator username)

Getting started

1. Create a folder into the drive C:\ and name it contao_language_extension
2. Download the zip file containing the command line script and unzip it into the above dir
3. Download the language pack from the Contao.org website (http://www.contao.org/download.html#translations) and put it (without unzipping) into the folder created in step 1.
4. Create a folder (that will contain the extension built by the script) named out.

If you have something like this:

you can go on

Customize the extension

Create a copy of C:\contao_language_extension\contao_languagepack_builder\package\package.xml.sample and rename it to package.xml.

Edit the package.xml (will looks like this):

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE typolightpackage>
<extension name="%languagepack_name%" date="%today%">
<author user="__YOUR_ACCOUNT_NAME_AT_CONTAO" name="__YOUR_NAME__" />
<copyright>__YOUR_COPYRIGHT_NOTICE__</copyright>
<license>LGPL</license>
<classification type="free" category="other" />
<release version="%version_number%" build="0" date="%today%" />
<language code="en">
<translator user="__YOUR_ACCOUNT_NAME_AT_CONTAO" name="__YOUR_NAME__" />
<searchtags>languagepack,core translation</searchtags>
<title>%langname% Language Pack</title>
<teaser>__ENTER_A_TEASER__</teaser>

<description>
__ENTER_A_DESCRIPTION__
</description>
<releasenotes>
%release_notes%
</releasenotes>
<manual link="__YOUR_WEBSITE__" />
</language>
</extension>

and provide the missing information, below you will find the package.xml used by the Italian Contao Community:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE typolightpackage>
<extension name="%languagepack_name%" date="%today%">
<author user="contaocms.it" name="Italian Contao Community" />
<copyright>(c) Italian Contao Community</copyright>
<license>LGPL</license>
<classification type="free" category="translation" />
<release version="%version_number%" build="0" date="%today%" />
<language code="en">
<translator user="contaocms.it" name="Italian Contao Community" />
<searchtags>languagepack,core translation</searchtags>
<title>%langname% Language Pack</title>
<teaser>The Italian translation by contaocms.it community
</teaser>
<description>The Italian translation of core modules
</description>
<releasenotes>
%release_notes%
</releasenotes>
<manual link="http://www.contaocms.it" />
</language>
</extension>

The script will take care of:

• Package name
• Version
• Release notes

Please do not modify the values between % symbol (e.g. %version_number%)

Create the extension on the Contao repository

Please note that this is a one-time operation, you need to accomplish it only the first time you create the extension

Go to the extension list page on Contao.org and click on “Manage extensions” (be sure to login first)

then click on the “Add extension” button

Fill in the fields as illustrated below and click on the “Add extension” button

The extension is now listed in your extension list.

Build the extension

Open the command line window. In Windows 2000 and XP, select Start, Programs (All Programs in XP), Accessories, Command Prompt. Alternatively, you can open the window by choosing Start, Run, typing command (in Windows 98 and Me) or cmd (in 2000 and XP), and pressing <Enter>.

Type the following command into the window

c:\>c:\php5\php.exe c:\contao_language_extension\contao_languagepack_builder\build_languagepack.php c:\contao_language_extension\TYPOlight-Italian-v24.zip c:\contao_language_extension\out

You will be prompted with a summary screen:

Contao Language Pack builder by zedseries.com
====================
A Contao extension will be created with the following settings:

sourceFile        :   c:\contao_language_extension\TYPOlight-Italian-v24.zip
destinationDir    :   c:\contao_language_extension\out
languageName      :   italian
versionNo         :   010000249

Do you wish to continue (y/n)?

Just type “y” to go on.

A new fill will be created into the out  folder

C:\CONTAO_LANGUAGE_EXTENSION
¦   TYPOlight-Italian-v24.zip
¦
+---contao_languagepack_builder
¦   ¦   .hgignore
¦   ¦   .hg_archival.txt
¦   ¦   build_languagepack.php
¦   ¦   CHANGELOG.txt
¦   ¦   README.txt
¦   ¦
¦   +---lib
¦   ¦       cmd_class.php
¦   ¦       utils.php
¦   ¦       zip.class.php
¦   ¦
¦   +---package
¦           package.xml
¦           package.xml.sample
¦
+---out
        TYPOlight_italian_languagepack_010000249.zip

Upload the extension to the repository

Go to the manage extensions page on Contao.org click on the “Upload package” button, then click the “Browse” button and select the file in the out folder. Once selected click on the Upload package button.

Publish the release

The final step is to publish the release, at http://www.youtube.com/watch?v=L_IphZYBY_8#t=3m08s you will find a video tutorial on how to accomplish this step.

Need help?

Feel free to comment below if you need further assistance.

This article has developers as audience, if you came here wondering why your custom template doesn’t get listed, please contact the author of the extension and tell him about this article

From version 2.9 Contao introduces the concept to pick templates from different directories and subdirectories.

Contao 2.9 introduces also the concept of themes, and let users assign a directory of templates to a theme. You can read the full announcement here.

If an user put a custom template into a subdirectory of the main templates dir, some extensions will not show it.

Every developers should update their extensions to reflect the above changes, here I will propose a cross-version solution to solve this problem.

If your extension uses a custom template, you will have a line like this in your d.c.a (let me tell we are talking about the tl_example dca):

$GLOBALS[‘TL_DCA’][‘tl_example’][‘fields’][‘my_template_field’] = array(
    ‘inputType’ => ‘select’,
    ‘options’ => $this->getTemplateGroup(‘my_prefix’)
);

in order to list the templates that exists in the template folder assigned to a theme, you must make the following changes:

Create a class wherever you want

(the “Contao way”  of doing it is to create a class named as the dca inside the same file.)

class tl_example extends Backend {
    public function __construct() {
        parent::__construct();
    }

    public function listTemplates($dc) {
        if (version_compare(VERSION.BUILD, '2.9.0', '>=')) {
            return $this->getTemplateGroup(‘my_prefix’, $dc->activeRecord->pid);
        } else {
            return $this->getTemplateGroup(‘my_prefix’);
        }
    }
}

then change the field’s entry in your dca to take the list of templates from the above function:

$GLOBALS[‘TL_DCA’][‘tl_example’][‘fields’][‘my_template_field’] = array(
    ‘inputType’ => ‘select’,
    ‘options_callback’ => array('tl_example', 'listTemplates')
);

These changes will make you extension compatible with Contao 2.9 and mantain the compatibilty with older versions.

Please comment below if you find errors or you simply  want to say something

Feel free to comment below if you find errors or if you have suggestions to improve it.

In order to show how ZedSeries Listing module works we are going to build a Faq Listing/Viewer. We will create the following three modules:

• F.A.Q. Categories listing (will show a list of F.A.Q. categories)
• F.A.Q. listing (will show a list of F.A.Q. belonging to the selected category)
• F.A.Q. details (will show the answer of a specific F.A.Q.)

Getting Started

In order to follow this tutorial you need at least:

• some F.A.Q., so you’ll have to go to the FAQ module and create some categories and then some faq.
• three pages that will contain the above modules

and you need to be able to do some operations (e.g. module creation) because this steps are not explained.

Basic styling with CSS

ZedSeries Listing comes with an example stylesheet, you can find it in the contrib folder of zedseries_listing directory.

The quickest way to incorporate it, is to add the following line:

<link rel="stylesheet" href="system/modules/zedseries_listing/contrib/zedseries_listing_style.css" media="screen" />

to the "Additional head tags" section of your layout

F.A.Q. Categories listing

This module will show a list of all F.A.Q. categories.

Our listing will contain the id, title and headline of each f.a.q. category sorted by title and without pagination. We link each faq category to another listing module with an url like this: (assuming that we have a category which title is "faq-category" with id 1)

http://www.example.com/faq-listing-page/i/1/t/faq-category.html

We’ll add the ability to search by title.

F.A.Q. Categories listing configuration

Create a new module of type "ZedSeries Listing" and fill in the fields as illustrated below:

The result (once you have put the module inside an article) should be something like this:

Now it’s time to create our F.A.Q. Listing module

F.A.Q. Listing

Our F.A.Q. Listing module will display all the F.A.Q. that belong to a selected category.

Our list will be searchable for a specific question.

This time we’ll add a "condition" to show only the faq of a specific category. The condition will be:

pid={{request::i}}

since in the database the pid field of table tl_faq is associated with the id field of the tl_faq_category table.

We use the {{request::i}} insert tag to retrieve the "i" param from the url. If you followed the previous step you know that the i url name is associated with the field "id" of tl_faq_category.

We’ll link this module to another module with an url like this: (assuming that we have a faq which alias is "our-faq-question")

http://www.example.com/faq-details-page/question/our-faq-question.html

Create a module and fill in as illustrated below:

The result will be something like this:

F.A.Q. Details module

This module will show the selected question and the answer. It is the simplest module of our tutorial since we have to select the fields we want to show and the "source" listing module.

Create a module of type "ZedSeries Listing Details" and fill in as illustrated below:

The result will be something like this:

Final notes

ZedSeries Listing module is a powerful module that speed up data listing with a litte effort (you have to deal with fields, table and url schema).

Every output generated by the ZedSeries Listing modules can be customized, take a look at How to use helper in template writing

However this topic will be covered in the next version of this guide.

If you want to get notified about the updates of this guide you can follow the zedserieslab’s tweets

Feel free to comment below if you have any questions.

Offers, also, the possibility to setup a relation between the topic and any table in your TYPOlight installation.

The screenshot below show how appears the comments module (after users have made a comment) used by default in the F.A.Q. module

As you can see there is no way to know that F.A.Q. 1 (listed in the filters bar) is related to the “Question #1”, this can be ok if you do not have many faq or if you have just some comments.

Using ZedSeriesCommentEverything you have more control on the comments of your website. It adds a new filter on the comments module so you can filter only the comments about a topic.

“Question #1” is more readable than “Parent ID 1” isn’t it?

How to setup ZedSeriesCommentEverything

The extension replaces the content element “comments” so don’t expect to find additional entries in your “content elements” list: just use a “content element” of type “comments”.

You can setup the (new) comments element with or without a database table relation.

Database table relations are useful if you want to bind  comments with existing data such as the f.a.q. example above. To add a relation just enter the topic and specify the field of which table will match the topic. Then you have to specify a field that will be used as label on the filters panel.

The (new) comments element can be set up with a topic that is not related to existing data. A tipical usage could be to setup a `shoutbox`on your website.

In this article we are going to show how to setup a (new) comments content element in both cases.

Setup with a relation to existing data

In order to reproduce the example above (comments related to the faq) set the “content element” as follow: dynamic

To give it a try, just put it in the same article in which you put the faq reader.

(If you are wondering about the ”{{request::}}” “insert tag” it is bundled with zedseries_lib)

Setup up as a shoutbox

Another way of using the (new) comments content element is to use it to put comments to a specific section of your website (e.g. the layout, a restricted member area section … and so on).

Create a (new) comments content element and specify a topic leaving blank the “Foreign key” and “Show field” fields.

Once your users add comments you can filter it using the MyShoutbox filter as “Related topic”.

That’s all

ZedSeries CommentEverything can be installed through the TYPOlight repository catalog browser.

You can find it quickly searching for “comment topic” tag-

If you need help or have some questions please post a comment.

Basically it allows users to select more than just one field.

The new interface is composed by two select and one text field

Compared to the previous interface now user can choose not only the field to filter but also the comparison operator. Multiple conditions can be added easily clicking on the green plus sign or deleted clicking on the red x.

Currently the operators supported are the following:

• equal
• greater than
• equal or greater then
• lower than
• equal or lower than
• starts with
• contains
• ends with

Next release will contain the option to show only selected operators.

ZedSeriesUI satisfies these needs.

With ZedSeriesUi output your message will be easily as writing these lines:

        $ui = new ZedSeriesUi();

        return  $ui->title('Operation completed')
               .$ui->box(
                         $ui->beLink('Go back to the main module.', 'do=myModule&key=MyModule')
                );

the result will be graphically  integrated with TYPOlight default theme:

Another useful function, if you need to build a list from custom data, is the  listingContainer function that along with the listingItem, can produce output like this:

The above result can be produced with the following code:

        $ui = new ZedSeriesUi();

        // just a fake data array
        $items = range(1, 15);

        $listingItems = array();

        foreach ($items as $item) {
           // collect them using listingItem
            $listingItems[] = $ui->listingItem('List item #'.$item, $ui->beLink('edit', 'do=MyModule&key=MyFunction&id='.$item));
        }

        // then return it inside a listingContainer
        return $ui->listingContainer(implode("\n", $listingItems));

ZedSeriesUI is distributed inside the ZedSeries Library extension for TYPOlight cms

ZedSeriesUI is a young project but it will grow in the next releases of ZedSeriesLibrary

Do not forget to add the proper ‘<requiredextension name=”zedseries_lib” … />’ in the package.xml of your extension

Issues of the ZedSeries Library extension are managed through bitbucket at: http://bitbucket.org/zedseries/zedseries_lib/issues/

Project webSvn page: (http://websvn.cyberspectrum.de/wsvn/tl_debug/)

tl_debug enable using firePhp from inside your TYPOlight extension.

Installation

You can download the source through svn.

At this time the most recent version is available doing a checkout at http://websvn.cyberspectrum.de/wsvn/tl_debug/tags/0.5.0

If you are not familiar with svn you can use tools like TortoiseSVN  (http://tortoisesvn.net/downloads)

Once downloaded the source you must copy the directory contained in system/modules (z___debug and debug) to your system/modules installation (i.e. TL_ROOT/system/modules/). Then a “developers” section appears to backend menu: click on “Debugger” to open the tl_debug settings panel.

In order to display the log messages you need the Firebug add on for Firefox (at least version 1.5.0 http://getfirebug.com/releases/firebug/1.5X/) and the firePHP plugin for FireBug https://addons.mozilla.org/en-US/firefox/addon/6149

Usage

Be sure to enable the debug in the backend module (Debugger) and set the options related to error level and database query you wish to log. You can log hooks on database queries coming from specific modules. It is a great tool.

Usage is simple as adding these lines where you need to debug:

/**
 * $channel is one of ('log', 'info', 'error', 'warn')
 * $label is a custom label
 * $message is the message you want to show
 */
if ($GLOBALS['TL_CONFIG']['debugMode'])
    $GLOBALS['TL_DEBUG'][$channel][$label] = $message;

This is the results on message logged with channel ‘log’ label ‘Hello’ and message ‘World!’;

i.e.

if ($GLOBALS['TL_CONFIG']['debugMode'])
    $GLOBALS['TL_DEBUG']['log']['hello']= 'world!';

I hope you enjoy it!

thank you to qrczak for letting me know this project.