This module enables you to insert diaporamas into descriptions.
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
Action
Config
Controller
Event
Filter
Form
Hook
I18n/backOffice/default
Loop
Model
templates
.gitignore
Diaporamas.php
LICENSE.txt
README.md
composer.json

README.md

Diaporamas module v0.1.6

Author: Romain Ducher

  1. Usage

This module enables you to insert diaporamas into descriptions. It currently works for products, categories, folders, contents and brands.

Diaporamas are identified with short codes. Diaporama shortcodes are strings containing letters (lowercase and uppercase), numbers, underscores and hyphens. A shortcode has to contain between 1 and 32 characters.

To insert a diaporama into a description, insert the "[£ shortcode £]" tag, where shortcode is your diaporama shortcode. For example, writing "[£ foo £]" will insert in the description the diaporama whose shortcode is "foo". Do not forget spaces around the shortcode or the diaporama tag will not be interpreted as a diaporama in your description.

To manage your diaporamas, log in into Thelia's back office and go to Tools > Diaporamas in Thelia's menu. There is a list summing up existing diaporamas. For each diaporama, the ID in the database, the title and the shortcode are displayed. In an upcoming release, you will be able to see the diaporama by clicking on its shortcode or by clicking on the opened eye in diaporama actions.

If you want to create diaporamas, click on the '+' sign in the top-right corener of the Diaporama list. Write its title in the lang precised by the flag in the title field and then write its shortcode in the corresponding field. If the shortcode has been already used by an existing diaporama, the diaporama creation will fail. It will create an empty diaporama, without images.

To edit a diaporama, go to the diaporamas list and click on its database ID, its title or the edit button in the diaporama actions. Here you can manage your diaporama just like you want. There are two tabs for this:

  • The first tab, called "General", enables you to change the shortcode or the title in the Thelia lang you want to. Save your changes by clicking on "Save" or "Save and Close" and go back to the diaporama list by clicking on "Close".
  • The second tab, called "Images", enables you to manages diaporama's images. You manage them just like images for products, categories, brands, folders or contents in Thelia.

To delete diaporamas, go to the diaporama list and click on the Trash Icon of the diaporama you want to delete.

The module uses the SmartyFilter module to change shortcodes into diaporamas. For this, the Smarty filter whose code is diaporamas.filter.shortcodes has to be activated. The filter is activated automatically while activating the Diaporamas module.

  1. API

The module provides some entities for using Diaporamas in Thelia.

2.1. Loops

The module provides two loops.

2.1.1. Diaporama

It deals with diaporamas in general, with their general information.

Inputs:

Argument Description
id The diaporama IDs in the database, separated by commas
title The diaporama title
shortcode The diaporama shortcode
order How to order diaporamas. Values can be id, id-reverse (order by id), title, title-reverse (order by title), or shortcode and shortcode-reverse (order by shortcode).

Outputs:

Variable Description
$ID Diaporama ID
$TITLE Diaporama title
$SHORTCODE Diaporama shortcode

2.1.2. DiaporamaImage

This loops deals with diaporama images. It almost works like Thelia's Image Loop, whose reference is here. The difference is that you do not have to give a source argument. If you give it, it will be ignored. Do not provide category, product, folder, content or brand arguments too. You are dealing with diaporama images, not images for those sources. Those arguments will be ignored if you give them too. To give a diaporama ID to the loop, write it in the source_id argument.

2.2 Models

There are classes for diaporama and diaporama images.

Diaporamas are represented by the \Diaporamas\Model\Diaporama class. They contain general information for diaporamas, i.e. the database ID, the shortcode and the (i18n) title.

Diaporama images are represented by the \Diaporamas\Model\DiaporamaImage class. They work just like classic Thelia images whose source would be "diaporama".

2.3. Forms

There are forms to create, update and delete diaporamas and to update diaporama images. See the config.xml file to have information about them.

2.4. Services and events

Event to dispatch (namespace \Diaporamas\Event\) Event type (namespace \Diaporamas\Event\) Description
DiaporamaEvents::CREATE DiaporamaEvent Creating a diaporama
DiaporamaEvents::UPDATE DiaporamaEvent Updating a diaporama
DiaporamaEvents::DELETE DiaporamaEvent Deleting a diaporama
DiaporamaEvents::DIAPORAMA_HTML DiaporamaHtmlEvent While retrieving diaporama's HTML in the back office
DiaporamaEvents::DIAPORAMA_PARSE DiaporamaHtmlEvent While parsing descriptions to insert diaporama's HTML in the back office
DiaporamaEvents::DIAPORAMA_HTML_FRONT DiaporamaHtmlEvent Same as DiaporamaEvents::DIAPORAMA_HTML but for front office
DiaporamaEvents::DIAPORAMA_PARSE_FRONT DiaporamaHtmlEvent Same as DiaporamaEvents::DIAPORAMA_PARSE but for front office
DiaporamaImageEvents::CREATE DiaporamaImageEvent Creating a diaporama image
DiaporamaImageEvents::UPDATE DiaporamaImageEvent Updating a diaporama image
DiaporamaImageEvents::DELETE DiaporamaImageEvent Deleting a diaporama image
DiaporamaImageEvents::UPDATE_POSITION DiaporamaImageEvent Updating the image position in the diaporama
DiaporamaImageEvents::TOGGLE_VISIBILITY DiaporamaImageEvent Changing image visibility in the diaporama

2.5. Useful endpoints

Endpoint Description
GET /admin/module/Diaporamas/diaporama/{shortcode}/html HTML code for the [£ shortcode £] diaporama. For the back office.
GET /admin/module/Diaporamas/diaporama/{shortcode}/data Data for the [£ shortcode £] diaporama. It returns general data for the diaporama and information about diaporama images too. For the back office.
GET /diaporama/{shortcode}/html Same as "GET /admin/module/Diaporamas/diaporama/{shortcode}/html" but for the front office.
GET /diaporama/{shortcode}/data Same as "GET /admin/module/Diaporamas/diaporama/{shortcode}/data" but for the front office.
  1. Installation

The Diaporamas module requires the SmartyFilter module. It is used to replace shortcodes with their corresponding HTML codes. Install it and activate it before activating the Diaporamas module.

Install it as a Thelia module by downloading the zip archive and extracting it in thelia/local/modules or by uploading it with the backoffice (at /admin/modules), or by requiring it with Composer:

"require": {
    "thelia/diaporamas-module": "~0.1.6"
}

Note: The module will create a thelia/local/media/images/diaporama folder to store diaporama images.