Sviluppare un'estensione in Contao - Prima parte

08/01/2011 22:14

Questa è la traduzione del tutorial Create a custom Contao module.

Per errori nella traduzione o incomprensioni della guida, contattatemi nel forum dove mi trovate con il nickname paplo.

In questo tutorial andremo a creare un modulo personalizzato in Contao.
Il nostro modulo si chiamerà CD Collection e presenterà la nostra collezione di CD suddivisi per categorie.

Prima di tutto dovete sapere che Contao è diviso in backend (area amministrativa) e frontend (sito web visto dai visitatori). Il nostro modulo presenterà la collezione di CD sul sito (che è la parte frontend), ma ha anche bisogno di una sezione di gestione dei contenuti (parte backend).


Struttura dei file

Ogni modulo in Contao è organizzato nella seguente struttura:

/cd_collection

La cartella principale del modulo. Contiene, oltre a sottocartelle, anche i file .php principali.

/cd_collection/config

Contiene config.php e di solito database.sql. Il file config.php indica a Contao come utilizzare il modulo, mentre il file database.sql contiene le query SQL per creare nuove tabelle o modificare quelle esistenti.

/cd_collection/DCA

La cartella Data Container Array (DCA), come possiamo leggere sul wiki ufficiale, è un array che dice, alla classe Backend di Contao, come far vedere all'utente i dati ottenuti dalla libreria DataContainer. La DCA ha dei parametri per la configurazione generale, per le operazioni possibili, per la visualizzazione dei campi e il loro raggruppamento in fieldset, e per la validazione dei dati e la formattazione.

/cd_collection/html

Questa cartella è opzionale e non ha bisogno di essere inclusa. Lo scopo principale è di essere un deposito per altri file, come immagini, fogli di stile, script, etc. E' spesso utilizzata per contenere l'icona del modulo utilizzata nel backend.

/cd_collection/languages

Cartella in cui sono conservati tutti i testi e le etichette. Durante lo sviluppo di un modulo, non si scrive il testo nei file .php, ma si utilizzano le variabili che sono dichiate nei file delle traduzioni. Questo aumenta la flessibilità, ma è anche necessario per rendere il nostro modulo multilingua.

/cd_collection/templates

Ogni modulo frontend è basato su template. Essi sono utilizzati per separare la parte di codice dalla parte di presentazione. Inoltre, gli utenti amministratori saranno in grado di creare i propri template adeguati alle loro esigenze.

Ora creiamo la struttura di cui sopra nella cartella /system/modules/.



Database e configurazione

Ora è il momento di preparare le tabelle del database e il file di configurazione, che dirà a Contao come gestire il nostro modulo.

Entriamo nella cartella /config e creiamo il file database.sql con il seguente codice:

--
-- Table `tl_cds_category`
--

CREATE TABLE `tl_cds_category` (
  `id` int(10) unsigned NOT NULL auto_increment,
  `tstamp` int(10) unsigned NOT NULL default '0',
  `title` varchar(64) NOT NULL default '',
  `description` text NULL,
  PRIMARY KEY  (`id`)
) ENGINE=MyISAM DEFAULT CHARSET=utf8;

--
-- Table `tl_cds`
--

CREATE TABLE `tl_cds` (
  `id` int(10) unsigned NOT NULL auto_increment,
  `pid` int(10) unsigned NOT NULL default '0',
  `tstamp` int(10) unsigned NOT NULL default '0',
  `title` varchar(64) NOT NULL default '',
  `artist` varchar(64) NOT NULL default '',
  `image` varchar(64) NOT NULL default '',
  `comment` text NULL,
  PRIMARY KEY  (`id`),
  KEY `pid` (`pid`)
) ENGINE=MyISAM DEFAULT CHARSET=utf8;

Penso che il codice sia chiaro e non necessiti di alcuna spiegazione. Si noti che i campi ID e tstamp sono richiesti da Contao per le nuove tabelle.

Nota: Ho notato che ci devono essere due spazi dopo PRIMARY KEY. Se c'è ne uno solo, Contao cercherà di eseguire DROP INDEX 'id' e aggiungere la chiave primaria 'id', che non può essere aggiunta perché la chiave 'id' esiste già!

Nota: Per modificare una tabella esistente ed basta scrivere i nuovi campi così:

CREATE TABLE `tl_newsletter` (
  `newField1` varchar(128) NOT NULL default '',
  `newField2` varchar(128) NOT NULL default ''
) ENGINE=MyISAM DEFAULT CHARSET=utf8;

La relazione tra le nostre tabelle è molto semplice ed è di tipo padre-figlio. Il figlio 'tl_cds' identifica il padre 'tl_cds_category' tramite il campo pid.

Non abbiamo bisogno di importare manualmente il file tramite phpMyAdmin o shell. Come si può notare durante l'installazione, Contao fornisce una sorta di sincronizzazione tra il database e i file database.sql. E' sufficiente eseguire l'install tool di Contao (www.website.com/contao/install.php) per aggiornare le tabelle del database.

Quando Contao viene inizializzato, ogni file di configurazione dei moduli viene caricato consentendo di sovrascrivere le impostazioni predefinite. Vale la pena notare che i moduli di Contao vengono caricati in ordine alfabetico. Per esempio, se vogliamo sovrascrivere i metodi del modulo News, abbiamo bisogno di creare una cartella XYZ, e NON Abc.

Nella stessa cartella /config creiamo un file chiamato config.php:

<?php

// Back end module
array_insert($GLOBALS['BE_MOD']['content'], 3, array
(
  'cd_collection' => array
  (
    'tables' => array('tl_cds_category', 'tl_cds'),
    'icon'   => 'system/modules/cd_collection/html/icon.gif'
  )
));

// Front end module
array_insert($GLOBALS['FE_MOD']['miscellaneous'], 0, array
(
  'cd_collection' => 'ModuleCdCollection'
));

?>

Ok, riepiloghiamo quello che abbiamo fatto fino a qui. In primo luogo, abbiamo aggiunto un nuovo modulo backend chiamato 'cd_collection' al gruppo 'contenuti'. Esso utilizza due tabelle chiamato tl_cds e tl_cds_category. Abbiamo anche definito il percorso di un'icona che sarà caricata in seguito. Poi, abbiamo aggiunto un nuovo modulo frontend chiamato cd_collection al gruppo 'varie'.

Se si utilizza la funzione array_insert per aggiungere un nuovo modulo, backend o frontend, si può definire la sua esatta posizione. Nel nostro esempio, stiamo usando la funzione per rendere il nostro modulo il primo all'interno del gruppo.

Diamo uno sguardo a come è cambiato il backend:

Icona del modulo

Ora, la parte più piacevole del nostro modulo. Aggiungiamo un'icona alla cartella html (come definito nel file di configurazione), così sarà visibile nel backend.

Tags

Torna indietro

Aggiungi un commento