Fork CMS (frontend widget: image gallery)

Fork CMS (frontend widget: image gallery)
Naar aanleiding van deze tutorial, besloot ik m'n eigen frontend widget te schrijven. Het is een goede manier om de gedachtegang van Fork CMS onder de knie te krijgen. De widget die ik maak, is een eenvoudige image gallery. Het heeft vooral als doel meer inzicht te krijgen in development voor Fork CMS. Als dit je eerste aanraking met Fork CMS is, raad ik aan eerste deze en deze blogposts te lezen. Done? Allright, let's go!

Widgets?

Zoals je misschien al weet worden pagina's binnen Fork opgebouwd met templates. Deze templates kunnen 'blocks' bevatten waaraan widgets gekoppeld worden. Als je niet weet waarover ik het heb, check dan eerst dit even. Widgets kunnen zowat vanalles bevatten: blogposts, content-blocks,... een image gallery! Widgets kunnen zelfs aangestuurd worden vanuit de backend. Maar dat is voor een andere keer.

Een widget kan alleen maar bestaan binnen een module. Voor de duidelijkheid bekijken we even hoe de mappenstructuur van onze gallery-module in elkaar zit. We bevinden ons dus in de map frontend.

Om deze structuur na te maken zonder risico op fouten, kun je een andere module kopiëren en overbodige files/mappen verwijderen. Zo doe ik dat meestal.

De map 'js' bevat de eventuele javascript files die je widget zal gebruiken. De image gallery zal gebruik maken van jQuery en de jCycle plugin. Download deze twee files en sla ze op in de map 'js' onder de naam 'CGallery.js' en 'jQuery.js'.

We moeten deze scripts natuurlijk ook toevoegen aan elke pagina waarop de gallery te zien zal zijn. Daar bestaat in de backend een erg handige tool voor. Ga naar Settings - General. Daar vind je de mogelijkheid om extra code mee te geven aan elke pagina.

De map 'layout/widgets' zal de template van onze widget bevatten. In de bovenliggende map 'widgets' steekt de php-file die onze template zal aansturen. Straks ga ik hier dieper op in. De naam van de template 'images' is niet lukraak gekozen. De naam zal je namelijk terug vinden in de klassenaam in de php-file.

De config-file is het eerste wat Fork zal raadplegen. Deze ziet er zo uit:
```
/**
*This is the configuration-object
*
*@package frontend
*@subpackage gallery
*@author Koen Vinken
*since 2.6
*/

final class FrontendGalleryConfig extends FrontendBaseConfig
{

}
```
Let op de naamgeving van onze klasse, die gebruikt maakt van CamelCasing. In ons geval wordt dit FrontendGalleryConfig. We hoeven voor onze image gallery geen extra configuraties mee te geven.

Widget code

Onderstaande code komt in de file "images.php". Er staat telkens bij wat het doet.
```
/**
* This is a widget with the gallery-images
* It will show do the oAuth-dance if no settings are stored.
* If the settings are stored it will grab the last
*
* @package frontend
* @subpackage gallery
*
* @author Koen Vinken
* @since 2.6
*/
class FrontendGalleryWidgetImages extends FrontendBaseWidget
{
public function execute()
{
// call parent
parent::execute();
```
```
// load template
$this->loadTemplate();
```
```
// parse
$this->parse();
}
```
```
/**
Parse
*
* @return void
*/
private function parse()
{
//load template
$tpl = new SpoonTemplate();
```
```
//force compiling
$tpl->setForceCompile(true);
```
```
//choose compile directory
$tpl->setCompileDirectory('/Applications/XAMPP/xamppfiles/htdocs/frontend/');
```
```
//setting up a simple array that contains the name of the images.
$widgetGalleryImages[0]['Name'] = "1.jpg";
$widgetGalleryImages[1]['Name'] = "2.jpg";
```
```
//assign widgetGalleryImages to var $widgetGalleryImages
$this->tpl->assign('widgetGalleryImages', $widgetGalleryImages);
}
}
```
Template code

Met een iteration lezen we de array 'widgetGalleryImages' uit.
```
{option:widgetGalleryImages}
{iteration:widgetGalleryImages} 
<img src="/frontend/core/layout/images/gallery/{$widgetGalleryImages.Name}" width="500"> 
{/iteration:widgetGalleryImages}
{/option:widgetGalleryImages}
```
Zoals je misschien gemerkt hebt, moeten er twee afbeeldingen met de naam "1.jpg" en "2.jpg" aanwezig zijn in de map '/frontend/core/layout/images/gallery/'. Je kiest zelf maar de afbeeldingen. De grootte maakt niet uit, zolang de naamgeving maar juist is.

Database stuff

Nu moeten we nog het een en ander duidelijk maken aan Fork. Bijvoorbeeld dat de module 'Gallery' bestaat. Voer daarom volgende sql code uit in je databank:
```
INSERT INTO modules(name, description, active) VALUES ('gallery', NULL, 'Y');
INSERT INTO modules(name, description, active) VALUES ('gallery', NULL, 'Y');
```
Je moet ook nog de rechten plaatsen zodat je in de backend de widget kan koppelen aan een template.
```
INSERT INTO groups_rights_modules(id, group_id, module) VALUES (NULL, 1, 'gallery'); 
```
Je moet er ook voor zorgen dat, in de backend, 'gallery' selecteerbaar zal zijn in de lijst met widgets. Daarvoor voeg je een record toe aan de tabel pages_extra.
```
INSERT INTO pages_extras(id, module, type, label, action, data, hidden, sequence)
VALUES (NULL, 'gallery', 'widget', 'Images', 'images', NULL, 'N', '10000');
```
Let er goed op dat de label 'Images' mét hoofdletter is, en de action 'images' zonder hoofdletter is! Onze module moet nu nog labels toegewezen krijgen voor de backend. Dit doe je in de backend via settings - translations - Add translations.

Doe hetzelfde voor de widget 'Images'.

Time for some magic!

Tijd om je creatie te testen. Ga naar Pages - Template. Als alles goed is kun je nu de module 'Gallery' kiezen uit de lijst.

Bekijk vervolgens de pagina in de frontend. Als alles goed is, wisselen de twee afbeeldingen elkaar automatisch af.

Als dit niet het verwachte resultaat heeft, laat dan gewoon iets na in de comments hieronder.