Introduction

Thelia is an open source tool for creating e-business websites and managing online content. Created in 2005, the new version of Thelia aims to be the next generation E-commerce system. It is based on Symfony 2 components and meets the following objectives : performance and scalability.

Installation

Requirements

Thelia needs at least php 5.4 and works with php 5.5 and 5.6 for now. For the database, Thelia requires at least MySQL 5.5.

PHP extensions

• intl
• mcrypt
• mysql and pdo_mysql
• curl
• gd

Download Thelia

You can download Thelia in two different ways

From the Thelia website

Go to the thelia website (http://thelia.net) and download it.

Using Composer

$ curl -sS https://getcomposer.org/installer | php
$ php composer.phar create-project thelia/thelia your-path 2.2.0 # replace 2.2.0 by the version of thelia you want

Install Thelia

First of all, create a vhost dedicated to Thelia and put the documentRoot in the web directory.

Here again you can install Thelia in two different ways

Using install wizard

with your favorite browser, navigate to the install directory :

http://yourdomain.tld/[/subdomain_if_needed]/install

For example, I have thelia downloaded at http://thelia.net and my vhost is correctly configured, I have to go to this address :

http://thelia.net/install

Using cli tools

$ php Thelia thelia:install

and follow the instructions

After installing Thelia, remove the web/install directory

Thelia's structure

After the installation you have an architecture like this

www <- your web root directory
    thelia <- your thelia directory
        bin
        cache
        core
        setup
        local
            config
            media
            modules
            session
        log
        templates
        web <- the only directory accessible by your web server

Local directory

In this directory you can find four directories :

• config : contains the database.yml file. In this file is stored the information for connecting to the database.
• modules : contains the modules developed by yourself or the community
• media : contains the media uploaded from the back-office. For example you can find all the product pictures.
• session : by default Thelia stores the sessions in this directory. You can change the directory where the sessions are saved. To do this insert a new record in the config table with session_config.save_path for the column name and in the value column put the full path where you want to store the sessions.

Template directory

The template directory contains all the templates for all Thelia's environment : front-office, back-office, email and pdf. For each type of templates a directory exists and contains as many template as you want but only one can be enabled (in the back-office panel -> Configuration -> System variables)

A good practice is to duplicate the default template and then modify to have a custom template. The default front-office template is highly customizable, see some example at https://github.com/thelia-templates

Web directory

The web directory is the only one accessible by your web server. It contains by default two controllers :

• index.php : used in production environement, it calculates the cache only once and never tries to know if it is outdated or not so after each modification don't forget to clear the cache
• index_dev.php : used when you develop the store. This controller is more flexible, the cache is checked all the time and refreshed if needed. It also logs a lot of information, like every request you make, all assets creation, etc.

Other directories

The other directories are less important :

• bin : propel and phpunit binaries are in this directory
• cache : the cache for each environment so you find a dev, prod and even test directory if you run test. Each environment has its own cache so if you clear the cache for the dev environment, only the dev environment will be affect.
• core : Thelia's source code and third party dependencies managed with composer.
• setup : all the files needed for bootstraping thelia : sql database, fake catalog script, etc
• logs : Thelia's logs. The configuration is in the admin panel (configuration -> System logs)

CLI Tools

Thelia has a command line tool that can help you automate repetitive tasks. Obviously you can develop your own command.

Usage

$ cd to/thelia/repository
$ php Thelia

If you use the command line without any argument, it will display all command and options available.

List of available commands :

tip: you can get help on a command using php Thelia help COMMAND

Other useful commands

Modules

Modules are the best way to extend Thelia functionalities. Payment and delivery methods are all modules.

The structure of a module is exactly the same as Thelia's core. A module can interact with the container in order to add its own services, to create new compilers, etc.

Thelia have a cli command to generate all needed files for creating a new Module : php Thelia generate:module MyModule

Structure

\MyModule
    \Config
        config.xml   <- mandatory
        module.xml   <- mandatory
        routing.xml
        schema.xml
    MyModule.php <- mandatory
    \Loop
        Product.php
        MyLoop.php
    ...

Config.xml content

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

<config xmlns="http://thelia.net/schema/dic/config"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://thelia.net/schema/dic/config http://thelia.net/schema/dic/config/thelia-1.0.xsd">

        <loops>
            <loop name="MySuperLoop" class="MyModule\Loop\MySuperLoop" />
        </loops>

        <forms>
            <form name="MyFormName" class="MyModule\Form\MySuperForm" />
        </forms>

        <commands>
            <command class="MyModule\Command\MySuperCommand" />
        </commands>

        <services>
            <service id="Mymodule.service.id" class="MyModule\MySuperService"/>
        </services>

        <hooks>
            <hook id="mymodule.hook" class="MyModule\Hook\MySuperHook" scope="request">
                <tag name="hook.event_listener" event="main.body.bottom" type="front|back|pdf|email" method="onMainBodyBottom" />
            </hook>
        </hooks>

        <exports> </exports>

        <imports> </imports>

</config>

<hook id="mymodule.hook" class="MyModule\Hook\MySuperHook" scope="request">
    <tag name="hook.event_listener" event="main.body.bottom" type="front" method="onMainBodyBottom" />
</hook>

<export id="your.export.id" class="Your\ExportHandler" category_id="the.category_id">
  <descriptive locale="en_US">
      <title>Your export title </title>
      <!-- you may add an optional description -->
      <description> ... </description>
  </descriptive>
  <descriptive locale="fr_FR">
      <!-- Here's for another locale -->
  </descriptive>
</export>

<export_categories>
    <export_category id="your.category.id">
        <title locale="en_US">A title</title>
        <title locale="fr_FR">Un titre</title>
    </export_category>
    <export_category id="your.other.category.id">
        <!-- here's another import category -->
    </export_category>
</export_categories>

<import id="your.import.id" class="Your\ImportHandler" category_id="the.category_id">
    <descriptive locale="en_US">
        <title>Your import title </title>
         <!-- you may add an optional description -->
         <description> ... </description>
    </descriptive>
    <descriptive locale="fr_FR">
        <!-- Here's for another locale -->
    </descriptive>
</import>

Module.xml content

Module.xml file is a description of your module. It includes the author's name, his contact details, module version and the version of Thelia it is compatible with.

<?xml version="1.0" encoding="UTF-8"?>
<module>
    <fullnamespace>Atos\Atos</fullnamespace>
    <descriptive locale="en_US">
        <title>Atos-sips payment module</title>
    </descriptive>
    <descriptive locale="fr_FR">
        <title>module de paiement Atos-sips</title>
    </descriptive>
    <version>0.9</version>
    <author>
        <name>Manuel Raynaud</name>
        <email>manu@thelia.net</email>
    </author>
    <type>payment</type>
    <thelia>2.0.0</thelia>
    <stability>beta</stability>
</module>

Routing

Thelia uses the Symfony-cmf Routing component, so it's possible to declare as many routers as are needed and add them in this routing component. If you need to add a router you can do it in two different ways

The default behavior

All you have to do is to create a file named routing.xml in your Config directory. Thelia will configure a new router and set a default priority (150) to it.

Custom routing

If you need a custom configuration for your routing, you can declare a new service and tag this service and put router.register for the name property and the priority you want.

Here is an example :

<service id="router.front" class="%router.class%">
    <argument type="service" id="router.module.xmlLoader"/>
    <argument>Front/Config/front.xml</argument>
    <argument type="collection">
        <argument key="cache_dir">%kernel.cache_dir%</argument>
        <argument key="debug">%kernel.debug%</argument>
    </argument>
    <argument type="service" id="request.context"/>
    <tag name="router.register" priority="128"/>
</service>

Model

Your module may need to create tables, generate model classes and interact with Thelia's model. How to do ?

1. Create the file schema.xml in your Config directory.
2. Fill schema.xml file, you can find all the information you need in Propel documentation.
3. Use the CLI tools to generate model and sql (php Thelia module:generate:model MyModule --generate-sql).

Note : it's better to put the namespace property on each table attribute instead of the database attribute.

Main class

The main class in your module is the most important file. This class is used when the module is activated or deactivated.

Most of the time this class will have the same name as your module directory. If my module directory is Atos, my main class will be Atos too and the full namespace will be Atos\Atos.

Depending of the type of your module, this class must extend a specific abstract class. Here is a list of all abstract classes :

• Thelia\Module\AbstractDeliveryModule : Use this class when you develop a delivery module
• Thelia\Module\AbstractPaymentModule : Use this class when you develop a payment module
• Thelia\Module\BaseModule : Use this class when you develop a classic module

AbstractDeliveryModule and AbstractPaymentModule classes extend the BaseModule class.

Some methods in BaseModule can be useful if you want to interact with Thelia during the installation or the removal process. You just have to overload the method you want and implement your code.

Specific methods for AbstractDeliveryModule

Specific methods for AbstractPaymentModule

Templating

Thelia templates use the Smarty template engine, enriched by many Thelia additions, such as loops, data access functions, internationalization function, etc

Structure

See Thelia structure for more information.

Every template should contain specific template files, which are the views invoked in the Front and Back Offices controllers. For a front-office template, these files are :

• product.html : displays a product.
• content.html : displays a content.
• category.html : displays a category's content.
• feed.html : the RSS product or content feed.
• folder.html : displays a folder content.
• 404.html : is displayed if a page cannot be found.
• order-delivery.html : is displayed during ordering process to choose a delivery method
• order-invoice.html : is displayed during ordering process to choose a payment gateway.
• order-failed.html : is displayed when a payment fails.
• order-payment-gateway.html : filled by the payment gateway to send to the platform a specific form.
• order-placed.html : is displayed once the payment is successfully performed

Assets management

Template assets are managed in a sub-directory of the template directory. For example, the default front-office template contains an 'assets' directory to store all template's assets.

To use this feature, you'll have to add some specific directives to your template files.

{declare_assets}

This directive tells Thelia's template system where your assets are located, e.g. the name of the root directory which contains all your assets.

Example :

{declare_assets directory="assets"}

{stylesheets}

This directive processes your CSS style sheets.

Example :

{stylesheets file="assets/css/*.less" filters="less"}
    <link href="{$asset_url}" rel="stylesheet" type="text/css" />
{/stylesheets}

This block returns only one parameter, $asset_url, which is the asset URL in the web directory, e.g. under the web/assets path.

List of parameters

{images}

This directive processes the static images used in your template.

Example :

{images file='assets/img/favicon.ico'}
    <link rel="shortcut icon" type="image/x-icon" href="{$asset_url}">
{/images}

This block returns only one parameter, $asset_url, which is the asset URL in the web directory, e.g. under the web/assets path.

List of parameters

{javascripts}

This directive processes your javascript files

Example :

{javascripts file='assets/js/script.js'}
    <script type="text/javascript" src="{$asset_url}"></script>
{/javascripts}

List of parameters

Internationalization

If you want to create multilingual compatible templates, you have to pay special attention to : - static text - date formatting - number formatting

Thelia provides several Smarty functions to help you.

{intl}

The {intl} function translates a string into the current language.

Example :

{intl l="This is a string to translate"}

List of parameters

 var myString = '{intl l="A string with 'simple' and \"double\" quotes" js=1}';

{format_date}

Use this function to format a date according to the current locale standards.

example :

{format_date date=$dateTimeObject}

List of parameters

{format_number}

Use this function to format a number according to the current locale standards, or to a specific format.

Example :

Outputs "1246,12" if locale is fr_FR, 1 246.12 if locale is en_US
{format_number number="1246.12"}

List fo parameters

Loop system

Loops are the most convenient feature in Thelia for frontend developers. Already there in Thelia's first version, they have to be improved for Thelia v2. Loops allow to gather data from your shop and display them in your front view. In Thelia v2, loops are a Smarty v3 plugin.

Syntax

{ifloop rel="my_associated_content_loop"}
    Associated contents for this product :
    <ul>
        {loop type="associated_content" name="my_associated_content_loop" product="12"}
            <li>
                <a href="{$URL}">{$TITLE}</a>
            </li>
        {/loop}
    </ul>
{/ifloop}
{elseloop rel="my_associated_content_loop"}
    No associated content for this product
{/elseloop}

{loop} {/loop}

the loop function have at least two mandatory parameters :

Each loop type defines its own parameters, you can search this parameter in Thelia documentation.

{ifloop}/{elseloop}

{ifloop} and {elseloop} are conditional loops. They allow to define a different behaviour depending on if the a classic loop displays something or not.

A conditional loop is therefore linked to a classic loop using the rel attribute which must match a classic loop named attribute.

Resources

• Documentation : http://doc.thelia.net
• Github repo : https://github.com/thelia/thelia
• Website : http://thelia.net

Contact : dev@thelia.net

Authors : Manuel Raynaud, Julien Chanséaume, Benjamin Perche, Franck Allimant, Gilles Bourgeat

Acknowledgements : Damien Souza, Stéphanie Pinet, Marion Laurent, Roxane Fabre