Development with Contao cms

Quick tip: easy writing of informative fields with ZedSeriesUi

2011-11-29T12:45:00.001+01:00

The Data Container Array (a.k.a. dca) of Contao cms allows to define custom fields through the input_field_callback entry. A common usage scenario is providing informative contents to your users. This can be accomplished easily using the ZedSeriesUi class (that is included in ZedSeries Library for Contao cms).

Define your informative field as input_field_callback:

<?php

$GLOBALS['TL_DCA']['tl_dummy']['fields']['my_info_field'] = array(
				     'input_field_callback' => array('tl_dummy', 'myInfoField')
);

?>

Write your callback

<?php 

class tl_dummy {

    public function myInfoField($dc) {
        $ui = new ZedSeriesUi();
        return $ui->ifcMessage('My content', 'zsui_info');
    }

}

This will output a nice informative message

Feel free to comment below if you have further questions.

How to create a custom insert tags for Contao

2011-11-25T23:39:00.001+01:00

The Contao cms supports dynamic content integration through the so called "insert-tags". Contao has a lot of built in "insert-tags" but sometimes when writing custom extensions may be the need to create a custom one.

Our custom “insert tags”

For the purpose of this tutorial we will create an extension for Contao that that provides two “insert tags” in order to display:

The ip address of the visitor when called as {{mytag::ip_address}}
The current page title when called as {{mytag::page_title}}

please note that the above functionalities are provided by the default {{env::ip}} and {{env::page_title}} “insert tags”.

Prepare the directory structure And files

Create the following files and directory under TL_ROOT/system/modules

[D]: directory - [F]: file
----------------------------------------------
[D] my_inserttags/
        [D] config/
                [F] config.php
        [F] MyInsertTags.php

Let’s start

Contao provides the insert-tags functionality through the replaceInsertTags hook, so the creation of a custom "insert tags" is a simple two step operation:

Step 1:

Put the following code into my_inserttags/config/config.php

<?php
$GLOBALS['TL_HOOKS']['replaceInsertTags'][] = array('MyInsertTags', 'outputTagContent');
?>

Step 2:

Put the following code into my_inserttags/MyInsertTags.php

<?php

class MyInsertTags extends Controller {
    
    
    public function outputTagContent($strTag) {
    
        /**
         * we need to run our function only if the $strTag argument is one of:
         * mytag::ip_address
         * or
         * mytag::page_title
         */
        
        $arrParts = explode('::', $strTag);
        
        /**
         * returning false means that our function can not recognize the tag
         * so Contao will try if the next hook applies
         */

        if ($arrParts[0] != 'mytag') {
            return false;
        }
        
        switch ($arrParts[1]) {
            
            case 'ip_address':
                
                /**
                 * here goes the code that match our mytag::ip_address tag
                 */
                
                return $this->Environment->ip;
            break;
            case 'page_title':

                /**
                 * here goes the code that match our mytag::page_title tag
                 */

                return $GLOBALS['objPage']->pageTitle;
            break;
        }
        
        /**
         * mytag::something is still an unrecognized tag
         */
        
        return false;
    }
}
?>

We are done

Our estension is ready to run. We can test it by creating a content element through the Contao backend and put the following lines in it:


You ip address is: {{mytag::ip_address}}

The page title is: {{mytag::page_title}}

If you have questions or comments do not hesitate to comment below.

ZedSeries bug tracker changes

2011-11-11T07:55:00.001+01:00

The ZedSeries bug tracker located at dev.zedseries.com no longer allows anonymously bug reporting. This is due to two main reasons:

Anonymous reporter does not receive update of the ticket status through email this lead them to “forgot” about the report they did. Especially if an answer to the ticket come after some time (e.g. one week)
There are some annoying spammer out there

However there is no need to register if you only want to view a ticket.

For any questions do not hesitate to comment below.

Thanks.

What’s new in ZedSeries Im.Ex. 0.8.0

2011-07-02T07:37:00.000+02:00

Just released version 0.8.0, main features:

- direct upload to contaotemplates.com through the Im.Ex. center

- ability to mark packages as private so noone except allowed members can access it.

ConfigWizard available in version 1.5.0

2011-05-15T18:24:00.002+02:00

Version 1.5.0 of ZedSeries Library features a ConfigWizard class that lets developers quickly implement custom config options for their Contao extensions.

Config options are managed through a section/key/value schema.

In the following example we’ll manage two configuration options for a virtual extension. We’ll choose to assign to this configuration the name ‘dummy_ext’ (it will be our “section” name). Our two configuration options will be named option_string and option_flag.

Setting up the dca

First of all we define our two field in the tl_zedseries_config dca.

Fields must be defined through the standard Contao notation as if they were standard database fields.

The only difference is the key of the “fields” array that must be prefix’ed with the section name: so the entry for the option_string field will be dummy_ext_options_string and the entry for the option_flag will be dummy_ext_option_flag

The option_string will be a TextWidget, the option_flag will be a CheckBoxWidget field.

Create the system/modules/dummy_ext/dca/tl_zedseries_config.php file and put the following lines:

please note that in the example below the labels for each fields are autoloaded from the tl_zedseries_config language file

<?php

$GLOBALS['TL_DCA']['tl_zedseries_config']['fields']['dummy_ext_option_string'] = array('label' = >$GLOBALS['TL_LANG']['tl_zedseries_config']['dummy_ext_option_string'],  'inputType' => 'text', 'eval' => array('mandatory'=>true)); 

$GLOBALS['TL_DCA']['tl_zedseries_config']['fields']['dummy_ext_option_flag'] = array('label' => &$GLOBALS['TL_LANG']['tl_zedseries_config']['dummy_ext_option_flag'], 'inputType' => 'checkbox'); 

?>

Setting up the backend menu entry

Add this code to system/modules/dummy_ext/config/config.php:

<?php

array_insert($GLOBALS['BE_MOD']['content'], 9, array( 'CustomConfiguration' =>array( 'callback' => 'DummyExtConfig' ) ) ); 

?>

then put in system/modules/dummy_ext/DummyExtConfig.php

<?php

class DummyExtConfig extends ZedSeriesConfigWizard { 

     public function getSection() { 

         return 'dummy_ext'; 

     } 

     public function getTitle() { 

         return 'Configuration for dummy extension';

     }

     public function getLogo() { 
        return 'system/modules/dummy_ext/media/images/config_logo.png'; 

    } 
} 

?>

Retrieve settings

Settings can be retrieved using:

the ZedSeriesConfig::getValue($section, $k) static method, that returns the value for the specified section/key
the ZedSeriesConfig::getValues($section) static method that returns an associative array containing the keys and values for the specified section
the {{zcfg::_section_::_key_}} insert-tags

Conclusion

The above is only a quick example, feel free to comment below for any doubts or questions

What’s new on ZedSeries Maps 1.2.0

2011-03-21T07:02:00.001+01:00

ZedSeries Maps 1.2.0 contains the following changes:

ability to show the infowindow of the map center after map loads
a new item type was added: “Directions item” let you define some starting points that will be shown in the "Get directions" form

Take a look at the new features in the demo page of ZedSeries Maps

If you wish to have a preview of all the features of ZedSeries Maps download the user guide.

ZedSeries Library documentation (API)

2011-03-20T18:22:00.001+01:00

The documentation for the ZedSeries Library extension (zedseries_lib) is available at http://api.zedseries.com

What’s new in ZedSeries Help System 2.0

2010-11-02T11:57:00.002+01:00

ZedSeries Help System for Contao cms is a valuable tool that allows you to easily create user guides.
Through full integration with Contao you can associate a particular paragraph in a specific context, eg you can create a link into the “global operations menu” of the “news module” and bind it to a paragraph that explains the “news module”.

For more information you can download the user guide of ZedSeries Help System.
Version 2.0 is actually in rc1, these are the major improvements of this release:

Preview

Books can now be previewed before publishing, simply click on the icon and a popup with the book content will be opened.

Direct access to the filemanager

When editing paragraphs you can open the Contao filemanager inside an inline popup

New image selector

the old image selector has been replaced by an improved version with a better preview.

Paragraphs selector restyled

A little descrption was added after the buttons

How to create an extension for Contao starting from a Language Pack

2010-07-25T13:35:00.000+02:00

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

Create a folder into the drive C:\ and name it contao_language_extension
Download the zip file containing the command line script and unzip it into the above dir
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.
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.

Let users find custom templates with Contao 2.9

2010-07-19T10:26:00.000+02:00

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

Just published api.zedseries.com

2010-07-11T13:46:00.000+02:00

I have just uploaded the documentation for ZedSeries Library to http://api.zedseries.com.

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

ZedSeries Listing Tutorial (part #1)

2010-07-05T21:42:00.000+02:00

Today was released ZedSeries Listing 1.6.0.stable, it is compatible with Contao 2.9 and is shipped with an inline guide. The following tutorial is taken from the inline guide. The project page is located at http://www.zedseries.com/zedseries-listing-extension-for-typolight.html. The issues are managed through bitbucket at http://bitbucket.org/zedseries/zedseries_listing/issues/. You can also visit the project page of ZedSeries Listing on Contao.org website.

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.

An overview of ZedSeries CommentEverything

2010-02-28T21:40:00.000+01:00

ZedSeries CommentEverything is an open source extension for TYPOlight cms provided by zedseries.com improves the comments default module providing the ability to setup a 'topic' for each content element;

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.

ZedSeries Listing v. 1.6.x: search system improved

2010-02-27T21:46:00.000+01:00

From version 1.6.x (currently in rc1) ZedSeries Listing introduces a new search system to improve the search experience of the users of your website.

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 supported operators 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: how to output nice messages in your backend modules

2010-02-25T13:00:00.000+01:00

Sometimes you need to show some messages coming from your own backend module. In these cases usage of a template would be only a waste of time.

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/

tl_debug: An useful extension for debugging TYPOlight

2010-02-22T12:37:00.000+01:00

Project: http://www.cyberspectrum.de/

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.

Quick tip: how to change page title in a frontend module or template

2009-12-15T10:40:00.000+01:00

A common needs while working with Contao is to set the page title from a frontend module or inside a template.

For modules:

class MyModule extends Module {
    protected function compile() {
        // ... your code ...
        $GLOBALS['objPage']->pageTitle = 'My custom title';
        // ... your code ...
    }
}

For templates:

<?php $GLOBALS['objPage']->pageTitle = 'My custom title'; ?>

Quick tip: How to remove .html extension from url with TYPOlight

2009-11-06T08:54:00.000+01:00

A quick tutorial showing how to remove “.html” suffix from the url of your website

Go to “Settings” (it’s under “System” section), make sure to set:

URL suffix: empty the field
Rewrite URLs: checked
Disable page alias usage: unchecked

Open the “.htaccess” (it is located into the root of your website) and replace the line containing

RewriteRule .*\.html$ index.php [L]

with:

RewriteRule .* index.php [L]

That’s all.

Select configuration: Manage options

2009-10-29T08:04:00.001+01:00

SelectMenu is a powerful widget that let user choose a value from a select box.
to use it in your Data Container Array please add

'my_field' => array(
// ... field configuration entries
    'inputType' => 'select',
// ... field configuration entries
);

to the field configuration as ‘select’ is the corresponding alias for the SelectMenu widget

It features data retrieving from the following sources:

an array
a foreign field from a custom table
a custom callback

Using array as source

Define the options array

<?php
$myOptions = array(
'a' => 'label a',
'b' => 'label b'
);

$GLOBALS['TL_DCA']['my_dca'] = array(
// other sections like palettes etc.
    'fields' => array(
'my_field' => array(
'inputType' => 'select',
'options'     => $myOptions
),
// ... other fields
    )
);
?>

the resulting html will be:

<select name="wselectmenu" id="ctrl_wselectmenu" class="tl_select mandatory" onfocus="Backend.getScrollOffset();">
<option value="a">label a</option>
<option value="b">label b</option>
</select>

Grouping options

Options can be grouped by putting them as array element, starting from the code above:

$myOptions = array(
'my_group' => array(
'a' => 'label a',
'b' => 'label b'
)
);

will be rendered as:

<select name="wselectmenu" id="ctrl_wselectmenu" class="tl_select mandatory" onfocus="Backend.getScrollOffset();">
<optgroup label="&nbsp;my_group">
<option value="a">label a</option>
<option value="b">label b</option>
</optgroup>
</select>

Labelling the group

Labels can be managed through an array; e.g.:

'my_field' => array(
// ... other field entries
   'options'     => $myOptions,
'reference'   => $GLOBALS['TL_LANG']['tl_dev_sandbox']['optionsLabel']
// ... other field entries
);

the reference array can be put into languages/your_language_code/your_dca_name dir (e.g. languages/en/tl_dev_sandbox.php for english and tl_dev_sandbox table) so it will be loaded when your dca is loaded.

this the method used by TYPOlight core extensions and it makes translations in other languages easy.

$GLOBALS['TL_LANG']['tl_dev_sandbox']['optionsLabel']=  array(
'my_group' => 'label for my group',
);

the resulting html will be:

<select name="wselectmenu" id="ctrl_wselectmenu" class="tl_select mandatory" onfocus="Backend.getScrollOffset();">
<optgroup label="&nbsp;label for my group">
<option value="a">label a</option>
<option value="b">label b</option>
</optgroup>
</select>

Using the reference array to label the whole select items

Using the code above we manage the labels for options through the $myOptions array (‘a’ => ‘label a’) while the groups labels are managed through the reference array.
Applying a small change we can manage all the select items (groups and options) with the reference array.
change the $myOptions array so it will looks like:

$myOptions = array(
'my_group' => array(
'a',
'b'
)
);

then add the missing entries to the reference array

$GLOBALS['TL_LANG']['tl_dev_sandbox']['optionsLabel'] = array(
'my_group' => 'label for my group',
'a'              => 'label for option a',
'b'             => 'label for option b'
);

Querying the database to populate the options

This is useful when you have a foreignKey relationship with another table (e.g. the tl_article table refers to tl_user to associate its own author).
To use this feature just specify the table and field from which you want to populate the selectbox

please note:
table must have a field named id. For each row retrieved the id will be used as value and the field will be used as label.

e.g. the following field configuration entry:


'my_field' => array(

'inputType' => 'select',
'foreignKey' => 'tl_user.name',
)

will populate a select with id as values and name as labels querying the table tl_user.

Using custom callback to generate the options

Sometime you need more control on options. Luckily the options can be generated through a custom callback.
Create the callback:

please note:
the standard way used by TYPOlight core extensions when dealing with callback is to create a class named as the dca and put it into the dca file. The callback class will extends Backend.


class tl_dev_sandbox extends Backend {

/***
* since Backend::__construct is protected we must
* redefine it as public
*/

public function __construct() {
parent::__construct();    
}

public function generateOptions() {
// you can use the logic explained above to create groups
        
$myOptions = array();

// fill in the myOptions array

// this is useless but you can query the database or read data from somewhere
        $myOptions = array('a', 'b');

return $myOptions;
}
}

then change your field configuration:

'my_field' => array(
'inputType' => 'select',
'options_callback'     => array('tl_dev_sandbox', 'generateOptions')
)

That’s it. If you have questions please comment below.

ZedSeries Help System released

2009-10-28T09:59:00.000+01:00

Hi all,

today I've released ZedSeries Help System, an extension that let developers creating manuals of their own extensions and distributing them with the extension. It is available in the official repository so can be installed through the Extension Catalog

In other words if you are a developer and are you looking for a way to document your extension I suggest you to give a try at ZedSeriesHelpSystem .

The included "inline" manual is (of course) built with ZedSeries Help System, this way the application itself is a demo of some ways of integrating inline help.

from the description of extension:
(http://www.typolight.org/extension-list ... 09.en.html)

ZedSeries Help System provides a quick and easy way to build and manage an help system for TYPOlight extensions. Create a powerful help system that incorporates context-sensitive help.

The project changelog is managed through bitbucket (http://bitbucket.org/zedseries/zedseries_help_system/)
If you have questions, doubts, feature requests, bug reports etc. please let me know creating a new issue at http://bitbucket.org/zedseries/zedseries_help_system/issues/new/ .

ZedSeries Listing new class available in version 1.5

2009-10-27T18:56:00.001+01:00

Starting from version 1.5 ZedSeries Listing features a class that let you create listing with a few lines of code:

<?php
// put this inside your Module's compile method to give a quick try

// in this example we'll query the tl_page table
// we pass $this->Template to assign vars to current template

// set "tl_page" as namespace
$l = new ZedSeriesListing('tl_page');

// you can set "frontend module" params through php code

$l->setFields('id,pageTitle,language');
$l->setSearchFields('pageTitle');
$l->setWhere('published = 1');
$l->setSorting('tstamp DESC');
$l->setPaging(5);

$l->query();
// $this->Template is created automatically by the (Backend|Frontend)Module
$lt = new ZedSeriesListingTemplate($l, $this->Template);
$lt->assignListingVars();
$lt->assignSearchVars();
$lt->assignPaginationVars();

ZedSeries Listing: template changes from version 1.5

2009-10-27T18:17:00.000+01:00

Starting from version 1.5 the zslist_default.tpl has changed. So if you upgrade your ZedSeries Listing extension (that is highly recommended) you need to apply the following changes to templates/zslist_default.tpl.

Please upgrade your template in this way: (remove the lines starting with a dash and add the ones which start with a plus sign)

-<input type="hidden" name="<?php echo $this->ns; ?>_order_by" value="<?php echo $this->order_by; ?>" />
-<input type="hidden" name="<?php echo $this->ns; ?>_sort" value="<?php echo $this->sort; ?>" />
-<input type="hidden" name="<?php echo $this->ns; ?>_per_page" value="<?php echo $this->per_page; ?>" />
-<select name="<?php echo $this->ns; ?>_search" class="select">
+<input type="hidden" name="<?php echo $this->nsorderby; ?>" value="<?php echo $this->Input->get($this->nsorderby); ?>" />
+<input type="hidden" name="<?php echo $this->nsdirsort; ?>" value="<?php echo $this->Input->get($this->nsdirsort); ?>" />
+<input type="hidden" name="<?php echo $this->nsperpage; ?>" value="<?php echo $this->per_page; ?>" />
+<select name="<?php echo $this->nssearch; ?>" class="select">
-<input type="text" name="<?php echo $this->ns; ?>_for" class="text" value="<?php echo $this->for; ?>" />
+<input type="text" name="<?php echo $this->nsfor; ?>" class="text" value="<?php echo $this->for; ?>" />
-<input type="hidden" name="<?php echo $this->ns; ?>_order_by" value="<?php echo $this->order_by; ?>" />
-<input type="hidden" name="<?php echo $this->ns; ?>_sort" value="<?php echo $this->sort; ?>" />
-<input type="hidden" name="<?php echo $this->ns; ?>_search" value="<?php echo $this->search; ?>" />
-<input type="hidden" name="<?php echo $this->ns; ?>_for" value="<?php echo $this->for; ?>" />
-<select name="<?php echo $this->ns; ?>_per_page" class="select">
-  <option value="10"<?php if ($this->per_page == 10): ?> selected="selected"<?php endif; ?>>10</option>
-  <option value="20"<?php if ($this->per_page == 20): ?> selected="selected"<?php endif; ?>>20</option>
-  <option value="50"<?php if ($this->per_page == 50): ?> selected="selected"<?php endif; ?>>50</option>
-  <option value="100"<?php if ($this->per_page == 100): ?> selected="selected"<?php endif; ?>>100</option>
-  <option value="250"<?php if ($this->per_page == 250): ?> selected="selected"<?php endif; ?>>250</option>
-  <option value="500"<?php if ($this->per_page == 500): ?> selected="selected"<?php endif; ?>>500</option>
+<input type="hidden" name="<?php echo $this->nsorderby; ?>" value="<?php echo $this->Input->get($this->nsorderby); ?>" />
+<input type="hidden" name="<?php echo $this->nsdirsort; ?>" value="<?php echo $this->Input->get($this->nsdirsort); ?>" />
+<input type="hidden" name="<?php echo $this->nssearch; ?>" value="<?php echo $this->search; ?>" />
+<input type="hidden" name="<?php echo $this->nsfor; ?>" value="<?php echo $this->for; ?>" />
+<select name="<?php echo $this->nsperpage; ?>" class="select">
+<?php echo $this->perPage_fields; ?>
-    <td class="body <?php echo $this->col_last; ?> col_last"><a href="<?php echo $row['details_href']; ?>"><img src="system/modules/zedseries_listing/media/images/details.gif" alt="" /></a></td>
+    <td class="body col_last"><a href="<?php echo $row['details_href']; ?>"><img src="system/modules/zedseries_listing/media/images/details.gif" alt="" /></a></td>

These changes are very easy to apply but if you need help try asking below. Thank you.

Validators in ZedSeriesWizard

2009-10-27T09:34:00.000+01:00

About writing validators using ZedSeriesWizard

note

before reading this be sure to read and understand Getting started with ZedSeriesWizard

Built-in validators

Since ZedSeriesWizard uses standard TYPOlight widgets we can take advantage of them. Please refer to http://www.typolight.org/reference.html#evaluation (rgxp section) for a list of built-in validators.

Custom validators

Sometimes the built-in validators does not fulfill our requirements, fortunately we can specify custom validators. We are going to add the following condition to MyFirstWizard:

These are our validation requirements:

The fullname must begins with an "a"
The age must be in the range 20, 25
The email must not ends with a .info domain

note

if you think these requirements are eccentric, I agree with you :)

Adding validators to MyFirstWizard

First of all let's create our validator class:

methods used for validation have the following signature:

public function myValidatorMethod(Widget $w)

take a look at http://api.typolight.org/ for more information about the Widget class

<?php
class MyFirstWizardValidator {

    public function validateName(Widget $w) {
        $firstLetter = substr($w->value, 0, 1);

        if (strtolower($firstLetter) != 'a') {
           $w->addError('Fullname must begins with a');
        }
    }

    public function ageCheck(Widget $w) {
        if ($w->value < 20 || $w->value > 25 ) {
           $w->addError('Your age does not fulfill the requirements');
        }
    }

    public function validateEmail(Widget $w) {
        $emailParts = explode('.', $w->value);
        $domain = array_pop($emailParts);

        if ($domain == 'info') {
           $w->addError('email with domain ".info" are not allowed');
        }
    }

}

Now it is time to write MyFirstWizard->getValidators in order to use the MyFirstWizardValidator class.

getValidators may returns an associative array where the keys are the fields that must be validated and the values are array callback (like the ones used in DCA, e.g. options_callback)

<?php
  // inside MyFirstWizard class ...

  protected function getValidators() {
      $objValidator = new MyFirstWizardValidator();

      return array(
                  'fullname' => array($objValidator, 'validateName'),
                  'age'      => array($objValidator, 'ageCheck'),
                  'email'    => array($objValidator, 'validateEmail')
             );
  }

That is! Our wizard now features custom validation.

Customizing a wizard

2009-10-27T09:09:00.000+01:00

Learn how to customize wizards created with ZedSeriesWizard

How to define settings with ZedSeriesWizardHelper

note

before reading this be sure to read and understand Getting started with ZedSeriesWizard

ZedSeriesWizardHelper uses it's getSettings() method in order to apply settings to the wizard; this method must return either a string or a ZedSeriesIniConfigWizard instance. If a string is returned ZedSeriesWizard will look for a file named "string_returned".ini.php (e.g. myconfig.ini.php) in the zedseries_lib/wzconfig/ directory and creates a ZedSeriesIniConfigWizard instance reading settings from it.

ZedSeriesIniConfigWizard

This class let us customize the wizard, basically you can:

choose to display a header with a logo inside (or even without the logo :D)
load css and javascript ; different files can be specified for front end and backend
choose whether to show a progress bar during wizard run (i.e. step 1 of 3)
specify a different template
modify the "next" "previous" and "finish" labels (with i18n support)

tip
please refer to "ZedSeriesWizard Settings" for an explanation of each directive

Returning an object

We override ZedSeriesWizardHelper's getSettings method to change our settings in order to show a progress bar when the wizard is created in front end mode.

<?php 
// ... inside MyFirstWizard class 
protected function getSettings() { 
  // create a new instance and load default settings 
  $cfg = new ZedSeriesIniConfigWizard('wizard'); 
  // change the display"ProgressBar" entry from the "fe" section 
  $cfg->fe__displayProgressBar = true; 
  return $cfg; 
}

Load settings from external file

The getSettings() method can also returns a string, in this case we must create a file named "string_returned" inside the zedseries_lib/wzconfig/ directory.

So create the zedseries_lib/wzconfig/myconfig.ini.php and put there the following code:

;<?php exit; ?> 
[fe] 
displayProgressBar = true;

then modify the getSettings() method in this way:

<?php 
protected function getSettings() { 
  /* the wizard will search for a file named "myconfig.ini.php" 
  * into the "zedseries_lib/wzconfig/" directory. */ 
  return 'myconfig'; 
} 
?>

Taking more control

If you need to:

specify the directory from which load the ini files
share your settings between different wizards

it's time to extend the ZedSeriesIniConfigWizard class.

So, create your own config class

<?php
class MyConfigClass extends ZedSeriesIniConfigWizard {
    protected $strDir = '/system/modules/mymodule/';
}
?>

and modify the getSettings method to reflect the above changes

<?php
protected function getSettings() {
    /* this time the wizard will search for a file named "myconfig.ini.php"
    * into the "mymodule/wzconfig/" directory. */
    
    $cfg = new MyConfigClass('myconfig');
    return $cfg;
}
?>

Custom configuration without external file

You can specify your own configuration settings directly into the config class

<?php
class MyConfigClass extends ZedSeriesIniConfigWizard {
public function __construct($filename='wizard') {
    // load the filename
    parent::__construct($filename);
    // apply the changes
    $this->fe__displayProgressBar = true;
}
}
?>

Configuration settings

Here is a list of all sections of a config ini file with explanation of each entry. Remember that you can set every entry in your config class just using the syntax

$configInstance->section__entry (e.g. $configInstance->fe__displayProgressBar if you want to change the progress bar behaviour)

be

these directives will be applied only when TYPOlight runs in backend (TL_MODE is be)

useHeader	whether to show an header before the widgets
title	title to display in header (ignored if useHeader is false)
logo	logo to display in header (ignored if useHeader is false)
css	a comma separated list of css files to load
js	a comma separated list of javascript files to load
template	template used for rendering the wizard, its behaviour is the same as TYPOlight module's template

fe

these directives will be applied only when TYPOlight runs in frontend (TL_MODE is fe) and are the same of be ones.

wizard

wizard section contains directives that changes the way ZedSeriesWizard works

showAllWidgets

if true every step displays the widgets beloging of the previous step in disabled state

form

in the form section can be specified attributes you want to render in the html tag form, please enter as name=value

e.g.

if you enter
class=stdform
target=_blank
the form will be rendered as
<form class=”stdform” target=”_blank”>

labels

labels section allows you to quickly override default label for buttons

next	label for the “next” button
prev	label for the “previous” button
finish	label for the “finish” button

Getting started with ZedSeriesWizard

2009-10-27T06:47:00.000+01:00

How to create a simple wizard using ZedSeries Library extension for TYPOlight webCMS

Before reading this you must have a (almost basic) knowledge of how to create extension for TYPOlight.

Please refer to "How to create a custom module" at http://dev.typolight.org/wiki/typolight/TutorialsExtension for more information about module creation

Our first wizard

A wizard is composed by a set of steps that, once completed, will end in an action.

We'll create our first wizard prompting user for name, age and email address; our wizard will contains the following steps:

print a welcome message
ask for name and age
ask for email address
display a "thank you" message

To build our wizard we can use standard TYPOlight widget as:

FormExplanation: used in steps 1 and 4 to display the messages
FormTextField: used in steps 2 and 3 to collect name and email
SelectMenu: used in step 2 to let user choose his age from a set of predefined values

Some notes on widget:

AFAIK there is no explicit documentation for Widget class. Luckily we can use the same options used in writing DCA fields definition

Take a look at Learn how to develop for TYPOlight - TYPOlight Open Source CMS on typolight.org for more informations about writing a Data Configuration Array

ZedSeriesWizardHelper class

ZedSeries Library comes with the ZedSeriesWizardHelper class that can be used to quickly setup our wizard. This is an abstract class that contains only one abstract mehotd: getSteps. As the name suggests the getSteps method must returns an array of steps to perform in order to complete the wizard. Each step is an array of widgets to display.

The name of our class will be MyFirstWizard: we are going to extend the ZedSeriesWizardHelper class so we only need to implement the getSteps method.

<?php

class MyFirstWizard extends ZedSeriesWizardHelper {

    protected function getSteps() {
    
        $steps = array();
        
        $steps[0] = array(
        # FormExplanation is a frontend widget used by TYPOlight form generator
        # is located in TL_ROOT/system/modules/frontend/ directory
        new FormExplanation(array('text' => 'Welcome to our first wizard click next to begin'))
        );
        $steps[1] = array();
        
        # this time we'll use Controller prepareForWidget method (through ZedSeriesControllerUtils)
        # to create our input text, prepareForWidget allow us to use the same field's configuration options used in dca
        # please refer to http://api.typolight.org/Controller/Controller.html#prepareForWidget
        # for more information about parameters
        
        $steps[1][] = new FormTextField(
                $this->cu->prepareForWidget(
                    array(
                    'label' => array('Full name', 'Please enter your name'),
                    'eval' => array('mandatory'=>true)
                    ), 'fullname'
                )
            );
        
        $ageOptions = array_combine(range(17, 42), range(17, 42));
        
        $steps[1][] = new SelectMenu(
            $this->cu->prepareForWidget(
                array(
                'label' => array('Age', 'Please Enter your age'),
                'options' => $ageOptions,
                'eval' => array('mandatory'=>true)
                ), 
                'age'
            )
        );
        
        $steps[2] = array(
            new FormTextField(
                $this->cu->prepareForWidget(
                    array(
                    'label' => array('Email', 'Please enter your email address'),
                    'eval' => array('mandatory'=>true, 'rgxp' => 'email')
                    ), 
                    'email'
                )
            )
        );
        $steps[3] = array(
            new FormExplanation(
                    array('text' => 'Thank you, click finish to end the wizard')
                )
        );
        
        return $steps;
    }
}

Running the wizard inside TYPOlight

Ok, we have our wizard but how we can run it?

There are two ways:

as standalone script after initializing the TYPOlight engine: pretty useless, but useful if you want to try your wizard quickly.
inside a (Backend|Frontend)Module using the "generate" method

1st way:

create a file named MyFirstRun.php and place it inside your TL_ROOT

paste the code below

<?php
define('TL_MODE', 'FE');
require_once 'system/initialize.php';

/**
* put here the MyFirstWizard class code
*
* class MyFirstWizard extends ....
*/

$obj = new MyFirstWizard();
$data = $obj->run();
echo $data;

then open http://yourhost/path/to/typolight/MyFirstRun.php and play with wizard going back and forth

2nd way:

override your module "generate" method in this way:

<?php
public function generate() {
    $wz = new MyFirstWizard();
    $data = $wz->run();
    return $data;
}
?>

then access your module and play with the wizard as usual

Array?

If you follows the above directions after hitting the "Finish" button, you've got "Array" on your screen

As you may guessed the ZedSeriesWizardHelper's run method return an array with the data entered when user completes the wizard

The ZedSeriesWizardHelper class has a "completed" property that can be used to detect if the wizard was completed:

<?php

$wz = new MyFirstWizard();

$data = $wz->run();

/* if $wz->completed == false $data contains the wizard html output

if (!$wz->completed) { 
    // use return if you are inside the generate method of a module
    # return $data; 
    echo $data;
} else {
    // $data is an associative array containing the entered user data
    print_r($data);
}

?>

The next steps

In following articles we extend our Wizard adding some validators and learning how to customize it.

ZedSeries Listing: How to use helper in template writing

2009-10-26T18:58:00.000+01:00

ZedSeries Listing set a template variable named fh that can be used for better customize our listing template.

A little example for clarifying how the help can be used:

For the following example we assume that we are querying the pageTitle,language and tstamp fields from tl_page to show some pages of our website with creation date.

<div<?php echo $this->cssID; ?>
<?php if ($this->style): ?>
style="<?php echo $this->style; ?>"
<?php endif; ?>>
<?php foreach ($this->tbody as $class=>$row): ?>
<p>
<small><?php echo $this->thead[$this->fh->pageTitle]['link']; ?></small>:
<?php echo $row[$this->fh->pageTitle]['content']; ?>
</p>
<p>
<small>Created on</small>:
<?php echo date("Y-m-d H:i:s", $row[$this->fh->tstamp]['raw']); ?>
</p>
<hr />
<?php endforeach; ?>
</div>

As shown above we can use $this->fh->%fieldname% to refer to our fields: so we can displays them without worrying about select order.

New posts are coming

2009-10-26T13:50:00.000+01:00

Hi all,

I am moving all the articles from zedseries.com here. This place will also contain articles tips and tricks on development with TYPOlight webCMS.

Hope you enjoy it.