Création d'un module: Frontend

ilune_fr > Contao - Typolight > Découverte de Contao > Création d'un module: Frontend

Création d'un module pour le Frontend

Avant de poursuivre, je vous invite à lire l'article sur la différence entre un module et un content, si ce n'est pas déjà fait, où que la distinction n'est pas encore tout à fait claire pour vous Sourire !

Créer un module pour le frontend, consiste en fait à afficher des données, votre popote pour que tout le monde puisse y accéder. Rigolant

Pour bien faire, il faudra que vous soyez à l'aise avec la notion de template Surpris. En effet, pour Contao, un module de frontend ressemble à un formulaire dont vous remplissez les vides avec vos valeurs, ce que vous faites via la classe dynamiquement ! Mais n'anticipons pas trop Clin d'œil...

Définition du module dans la liste des modules selectionnables

//$sous_partie correspond aux sous catégories, lors de la selection du module, par defaut, c'est "miscellaneous"
$GLOBALS['FE_MOD'][$sous_partie]['nom_module']=>'nom_classe_a_appeler';

Créer le DCA pour les paramètres d'affichage du module dans le frontend

Lors de la création d'une nouvelle instance pour un module, vous avez sans doute remarqué, que vous aviez quelques paramètres à renseigner avant de l'ajouter Rigolant ! 

Par exemple Quand vous ajoutez un module de type "menu de navigation", vous pouvez indiquer un titre, un niveau de début et de fin.

La DCA de création du formulaire doit dont être renseignée dans un fichier que vous nommerez tl_module.php et que vous placerez dans le dossier dca.

Comme pour toutes les DCA, vous y renseignerez les palettes, et les fields de ce formulaire et cela dans l'arborescence suivante:

$GLOBALS['TL_DCA']['tl_module']['palettes'][{nom_module}]

et

$GLOBALS['TL_DCA']['tl_module']['fields'][{nom_module}]

Vous noterez que tl_module est un seul et même DCA (prédéfini), géré un peu particulièrement, vous ne renseignerez donc pas la partie générale config ($GLOBALS['TL_DCA']['tl_module']['config'])

Définition de config pour le DCA tl_module défini dans le module Backend

$GLOBALS['TL_DCA']['tl_module'] = array
(

	// Config
	'config' => array
	(
		'dataContainer'               => 'Table',
		'ptable'                      => 'tl_theme',
		'enableVersioning'            => true,
		'onload_callback' => array
		(
			array('tl_module', 'checkPermission')
		)
	)
);

A noter vous pouvez définir plusieurs modules pour le front end, dans ce cas, vous indiquerez des {nom_module} différents et dans$GLOBALS['FE_MOD'][$sous_partie][num], vous indiquerez tout ceux que vous définirez dans le fichier dca (voir plus haut, nom_module correspondant à nom_module !!), et vous penserez à créer toutes les classes correspondantes !

Liens avec la BDD

Enfin, vous penserez à augmenter le nombre de champs de la table tl_module, des champs fields que vous aurez rajoutés en rajoutant la table module dans votre fichier database.sql :

database.sql

CREATE TABLE `tl_module` (
  `{nom_module}_field_text` text NULL,
  `{nom_module}_categories` blob NULL
) ENGINE=MyISAM DEFAULT CHARSET=utf8;

Reprendre des champs existants

Plutôt que de faire des doublons de champs déjà créés par d'autres modules, vous pouvez les reprendre !

Ainsi quand vous définirez votre palettes, vous n'aurez qu'à préciser leurs noms comme par exemple ici (les paramètres de bases):

    $GLOBALS['TL_DCA']['tl_module']['palettes'][{nom_module}]
    ='{title_legend},name,headline,type;{protected_legend:hide},protected;{expert_legend:hide},guests,cssID,space';

Je vous recommande chaudement de parcourir les fichier tl_modules.php déjà existant pour vous inspirer, et pas faire de bêtises Rigolant !

Créer/utiliser une table étrangère

Vous pouvez également créer/utiliser une table étrangère pour trouver les valeurs de votre DCA (select, radio etc...).

Pour cela, vous utiliserez options_callback qui appellera une méthode de classe pour retourner les différentes valeur (voir comment définir une table étrangère dans les DCA ).


Il vous suffira ensuite dans votre classe de compiler vos requètes personalisés et de retourner les valeur désirées.

Egalement, rien ne vous empèche de saisir des valeurs particulières dans le backend, et ne chercher qu'à faire un lien avec dans tl_modules (avec options_callback).

Les fichiers de langues

Pour définir le nom du module selon la langue, vous devrez renseigner son nom dans les fichiers langages présents du fichier /languages/[fr-en-de...]/modules.php:

$GLOBALS['TL_LANG']['FMD'][{nom_module}] = array("nom","description");

Création de la classe de prise en charge du frontend

Tandis que les classes pour gérer le Backend doivent hériter de la classe BackendModule (voir création d'un module pour le backend), les classes pour gérer le frontend doivent hériter de la classe Module.

De la même façon nous avions noté que la méthode generate() renvoyait l'affichage pour le Backend, nous noterons que en ce qui concerne le frontend, il s'agit de la méthode compile(); (déjà évoqué cela dit. Sourire)

Par soucis de compatibilité, et comme dans certains cas (comme dans l'aperçu du module dans le backend), la méthode generate() peut être appelée, nous la rajouterons dans notre classe, avec un return assez simple.

Attention, dans le frontend, la méthode generate doit ABSOLUMENT retourner le parent::generate(), sinon votre module ne s'affichera pas : en effet Module::generate() appelle le $this->compile() qui lancera notre méthode compile !

Info : Module ::generate est executé par la méthode Controller::getFrontendModule();

Exemple "bateau" de méthode generate pour un module de frontend

/**
 * Display a wildcard in the back end
 * @return string
 */
public function generate()
{
	if (TL_MODE == 'BE')
	{
		//Si la fonction est appelée dans le Backend:
		$objTemplate = new BackendTemplate('be_wildcard');
		//la fonction generate est appelée ici pour afficher un aperçu
		// ==>on prend donc le template adapte "be_wildcard"
		//On renseigne ensuite les paramètres du template:
		
		$objTemplate->wildcard = '### MON MODULE ###';
		$objTemplate->title = $this->headline;
		$objTemplate->id = $this->id;
		$objTemplate->link = $this->name;
		$objTemplate->href = 'contao/main.php?do={mon_module_backend}';
	
		return $objTemplate->parse();
	}
	return parent::generate();
}

Rajouter des fichier CSS et JS au chargement de votre module

Comment indiquer à Contao de charger certains fichier JS ou CSS lorsque vous ajoutez votre module ?

Pour cela au seins de votre fichier /config/config.php vous renseignerez dans le $GLOBALS ceci:

//fichiers à ne charger que dans le frontend
if (TL_MODE == 'FE')
{
	$path_css = "{mon_path_vers_fichier_css}.css";
	$already_set_css = false;
	foreach($GLOBALS['TL_CSS'] as $name=>$value)
	{
		//verification que le fichier n'est pas deja inclu
		if ($value == $path_css)
		{
			$already_set_css = true;
			break;
		}
	}
	if (!$already_set_css)
	{
		//si il n'a pas été déjà défini on rajoute le fichier à la liste des fichiers à charger
		$GLOBALS['TL_CSS'][] = $path_css; 
	}
	$path_js = "{mon_path_vers_fichier_js}.js";
	$already_set_js = false;
	foreach($GLOBALS['TL_JAVASCRIPT'] as $name=>$value)
	{
		//verification que le fichier n'est pas deja inclu
		if ($value == $path_js)
		{
			$already_set_js = true;
			break;
		}
	}
	if (!$already_set_js)
	{
		//si il n'a pas été déjà défini on rajoute le fichier à la liste des fichiers à charger
		$GLOBALS['TL_JAVASCRIPT'][] = $path_js; 
	}
}

to be continued...

  Cet article est sous licence LGPL, vous pouvez le modifier, le copier et le publier, mais en signalant son auteur d'origine. ( http://www.ilune.fr )