feedback

 

Comment créer un bloc pour concrete5 :

Les blocs sont le moyen d'ajouter des fonctionnalités sur concrete5 et améliorer votre contenu de site web. Nous allons détailler la façon dont l'utilisateur ajoute des blocs sur son site.

Dans tous les cas, Concrete5 embarque un certain nombres de blocs. En général, ceux-ci sont suffisant pour avoir un site riche et fonctionnel, c'est pourquoi la première chose à faire pour les développeurs est de jouer avec le blocs existants sur Concrete5. Ce peut être juse de changer l'apparence des blocs; ou bien peut être avez vous besoins de créer une fonction nouvelle, comme un gestionnaire d'évènement, un calendrier ou un autre type de bloc. Heureusement, travailler sur les blocs de Concrete5 est relativement simple.

Structure de bloc basique:

Voici un un bloc tout simple que vous pouvez installer sur votre environement. Il est utiliser sur le tutoriel des développeurs.

Introduction

Un bloc est un ensemble de fichiers dans un répertoire particulié, qui est lui même situé dans le répertoire /blocks à la racine de votre site web. (Un autre répertoire blocks, situé dans le répertoire /concrete, contient les blocs embarqués avec le CMS. Pour préservez vos travaux des mises à jours futures, il est probablement mieux de ne pas toucher à ces fichiers - de toute façon ses couches sont écrasées par celle situé dans votre répertoire à la racine du site.)

Contenu d'un répertoire de bloc

add.php

Obligatoire. Ce fichier est le thème affiché lorsque vous ajoutez un bloc via le tableau de bord.

edit.php

Optionnel, bien que très souvent nécessaire. Ce fichier est affiché lorsque le bloc est en mode édition.

Les deux fichiers add.php et edit.php sont juste de smpls formulaires englobés dans Concrete. Habituellement, ces éléments de formulaire ont le même nom que ceux des colonnes de leur table de base de données.

controller.php

Obligatoire. Ce fichier contient des paramètres vitaux pour le bloc (son nom, une description, la dimension de son interface, etc…), tout comme bon nombre d'objets/fonctions nécessaires. La classe du bloc est également responsable de la sauvegarde de celui-ci, bien que de nombreux blocs simples n'ont pas à préciser leur méthode de sauvegarde, aussi longtemps que les variables postées sont mappées dans les tables de la base de données.

db.xml

Obligatoire pour tout bloc ayant besoins de sauvegarder leur données dans la base (ce qui représente 99% d'entre eux). Ce fichier contient les informations nécessaires pour créer la table de votre bloc dans la base de données, selon le format ADOXMLS.

auto.js

Optionnel. Si ce fichier existe il est automatiquement inclus lorsque le bloc est en mode ajout ou édition.

icon.png

Optionnel. Cette image est affichée sur l'interface de concrete lorsque le bloc est listé.

tools/

Optionnel. Les éléments de ce répertoire est utilisé par le bloc à quelque fin que se soit. Le bloc AutoNav utilise ce type de fonctionnalité.

templates/

Optionnel. Le contenu de ce répertoire sont les types d'affichages alternatifs du bloc, qui peuvent être des thèmes personnalisés utilisés par le CMS. Par exemple, Le format typique du bloc autonav est une liste à puces, mais le thème "Header Menu" peut être aplliqué au bloc autonav, ce qui restructure le menu avec des DIVs.

Installer un Bloc

Avant de crée un bloc, il peut être utiliede créer un bloc from scratch, partant du principe qe le plus simple est le mieux. Pour cela, nous vus avons fournit un lien de bloc vraiment très simple un peu plus haut.

Pour installer ce bloc:

  • Décompressez l'archive.
  • ploader le dossier dans le répertoire /blocks à la racine, qui est normalement vide si vous n'y avez rien ajouté.
  • Connectez vous sur votre tableau de bord, et allez sur Ajouter des fonctionnalités.
  • Vous devirez voir votre bloc listé comme prêt à installer (en bas de page après la liste de blocs disponibles).
  • Cliquez sur installer.

C'est tout ce qu'il y a à faire. Le bloc va automatiquement créer sa table dans la bse de données et son enregistrement pris en compte dans Concrete, vous serz donc en mesure d'ajouter celui-ci sur votre site.

Comment votre bloc sait qu'il doit se nommer Basic Test ? Et comment celui-ci cré-t-il sa table dans la base de données ? Pour avoir la réponse nous allons étudier le fichier controller.php

1 Informations sur l'installation:  Propriétés dans Controller.php

Controller.php contient les données sur votre bloc, aussi bien que celles-ci vont s'exécuter automatiquement lorsque des actions seront requises sur le bloc.

Propriétés requises

btDescription: C'est la description de ce que fait votre bloc. C'est affiché dans le tableau de bord et sur l'interface d'ajout de bloc.

btName: Le nom du bloc.

Propriétés optionelles

btTable: La table primaire de la base de données du bloc. Si celle-ci est spécifiée, et si le bloc utilise seulement cette table là, alors le bloc sera capable de sauvegarder automatiquement ses données dans cette table, à condition que les champs du formulaire du bloc soient directement mappés sur les colonnes de la table.

btInterfaceWidth: La largeur de la popup qui apparaitra lorsque ce bloc est édité ou ajouté sur une page.

btInterfaceHeight: La hauteur de la popup qui apparaitra lorsque ce bloc est édité ou ajouté sur une page.

Comme vous le voyez, c'est comme cela que notre bloc sait qu'il est nommé Basic Test: l'information est dans le fichier de classes du bloc. Vous remarquerez, c'est un bon moyen de tester le contrôleur du bloc. Il peut y avoir plus d'informations dans ce contrôler, cependant nous irons un peu plus loin par la suite.

2 Informations sur:  db.xml

Maintenant que nous savons que notre bloc récupère son nom et sa description durant l'installation, regardons comment il construit sa table dans la base de données. Dans notre bloc de test basique, nous avons défini notre table de base de données en tant que btBasicTest. Si vous ouvez db.xml situé dans le répertoire du bloc. Vous allez trouver notre table btBasicTest définie en XML:

C'est en effet assez simple à lire:

D'abord, nous définissons le nom btBasicTest.

Ensuite nous définissons notre premier champ, nommé bID, et son type (integer). Elle est également définie comme unsigned, et la clef primaire de la table.

Puis nous avons un champ nommé content, qui est du type longtext (c'est le pourquoi du X2).

Le schéma pour ce fichier est AXMLS. Vous pouvez en apprendre plus sur le sujet ici, cela inclus aussi les différentes définitions de champs.

Une dernière chose: chaque table spécifiée avec les propriétés du contrôleur btTable doivent avoir bID comme clef primaire. C'est un entier (et non réglé sur auto_increment). Ce shéma de clef correspond à une entrée dans la table des blocs de Concrete5, et c'est utilisé pour joindre les données spécifiques du bloc aux données de Concrete5 (métadonnées, sa positions, sa version, etc...)

Maintenant regardons comment notre bloc fonctionne. Essayez de l'ajouter sur une page. Vous devriez voir un simple formulaire. pour savoir commen celui-ci est construit, jettons un oeil sur le fichier add.php.

add.php

Editez le fichier add.php. La première chose qui saute aux yeux est qu'il n'y a pas grand chose Langue tirée.

Ce code est plutôt simple à lire. Nous avons d'abord notre paragraphe d'introduction. Ensuite, nous avons un label pour le champ de notre formulaire, qui est affiché par le moteur HTML. Puis, le moteur HTML (HTML helper) affiche un champ de texte avec le nom content. Pour styliser le champ d'entrée texte, nous passons par un tableau associatif comme la deuxième option avec quelques informations sur le style.

Lorsqu'un bloc de ce type est ajouté par le CMS, ce bloc de PHP et HTML complet sera enveloppé dans un formulaire qui permettra de contrôler la présentation du contenu sur Concrete. Pour être certain que les conenus de ce formulaire seront correctement routés jusqu'à la table du bloc, vous devriez nommer les champs de ce formulaire de la même façon que les champs de la table de la base de données. (Note: Ce n'est qu'un fil directeur, mais aujoud'hui ce n'est qu'un petit formulaire. Vous pouvez le nommer comme vous voulez. Vous devriez pas avoir à utiliser les élément d'aide de formulaire de Concrete - bien qu'un jour ils puissen s'avérés utiles.)

Soumettre le résultat du bloc ajouté

Lorsque votre bloc est à ajouté via le CMS, vous verrez un bouton Ajouter sous la zone de contenu principale de votre interface d'ajout. Lorsque vous cliquez sur celui-ci, Concrete route les requête jusqu'au contrôleur pour votre bloc, et invoque automatiquement la méthode save() .

Si votre bloc estsimple, et n'a pas esoins de faire autre chose que de sauvegarder les champs dans la table comme ils sont, vous n'aurez pas besoins d'implémenter votre propre méthode save()  - le contrôleur de bloc de Concrete5 le fera pour vous. C'est pourquoi, lorsque vous étudiez le contrôleur pour le bloc de test, vous ne voyez aucune méthode save().

Editer un bloc avec edit.php

Edit.php est le fichier PHP automatiquement afficher lorsque le boloc est en mode édition. La plupart du temps ce fichier est très, très, similaire au fichier add.php, avec quelques additions pour permettre de passer les valeurs existante du formulaire du block au éléments de cleui-ci.

Voici le contenu du thème d'éditiond e notre bloc basique:

Cela semble identique au thème d'ajout, mais remarquez le paramètre $content. Dans notre contrôleur de bloc typique, les valeurs des champs des tables sont automatiquement extraite et placées dans le champ d'application locale. Nous allons ensuite transmettre ces données à l'aide du formulaire afin qu'elles puissent êtres affichées en mode édition .

Que cela veut-il dire exactement ? Et bien, par défaut, chaque champ de votre base de données, pour le bID courrant, est disponible en tant que variable PHP ans votre modèle d'édition ou d'affichage.

Voir votre bloc

Le thème d'affichage de votre bloc est comparable à votre thème d'édition, mais simplifié. Il affiche les valeurs courantes sauvegardées pour votre bloc, toujours avec les spécificités d'affichage de celui-ci. Pour un contenu de bloc HTML, cela va juste affiché la variable $content du bloc. Pour l' autonav par exemple il parserait les paramètres sauvegardés et construire l'arbre à partir de ceux-ci. Pour un évènement vous devrez parser les dates sauvegarder à travers une interface de calendrier.

Mise en place thèmes personnalisés pour les blocs existants

Pour beaucoup de sites, les blocs inclus dans concrete suffisent largement. Mais pour les autres, vous aurez besoins de créer les votre entièrement personnalisés. Toutfois, si vous souhaitez utiliser un bloc inclus dans Concrete, mais avec un thème personnalisé, cette section est pour vous.

Mettre à jour un thème de bloc embarqué par concrete

Disons que vous voulez que le bloc autonav utilisent uniquement des DIVs au lieu des listes. Au lieu de modifier blocks/content/autonav/view.php (que serait écrasé lors de la prochaine mise à jour), créez plutôt /blocks/autonav.php à la racine de votre site web. Ce modèle sera automatiquement utilisé par votre bloc autonav.

Créer des thèmes supplémentaires pour le blocs

Pour créer un thème personnalisé pour vos blocs qui soit disponible dans la boite de dialogue de choix de thèmes, Créez un répertoire /templates avec à l'intérieur des répertoires correspondant a ceux des blocs se trouvant dans votre répertoire /blocks .Que diriez vous d'un petit exemple ?

Disons que vous voulez créer un thème pour votre bloc autonav. Le présent pour l'autonav tire sur les tons amende, mais vous voulez un thème type breadcrumb. Dans votre répertoire local /blocks (qui est normalement vide lorsque vous installez Concrete5), créez:

autonav/templates/breadcrumb.php

Copiez le code /concrete/blocks/autonav/view.php dans ce fichier, et modifiez le ensuite comme bon vous semble. Ensuite, lorsque vous désirez utiliser ce thème,cliquez sur le bloc que vous désirez modifier, et sélectionnez Choisir un thème personnalisé depuis le menu. Votre thème Breadcrumb devrait apparaitre dans le menu de sélection.

Méthode additionelle optionnel du contrôleur de bloc

Avec la plupart des blocs, vous n'aurez pas besoins de réécrire votre contrôleur. Toutefois, si votre bloc est plus complexe, vous aurez à le faire. La méthode suivante est utilisée dans certaines situations:

install()

Ce fichier est automatiquement exécuté lorsqu'un bloc est installé. Généralement il parse le fichier db.xml du bloc, mais si vous avez besoins de créer de nouveaux répertoires ou écrire d'autres objets dans la base de données, c'est ici que vous devrez le faire.

save($args)

Cette méthode est automatiquement appellé avec un tableau associatif de clefs ou de valeurs lorsque un bloc est édité ou ajouté.

duplicate($newBlockID)

Cette méthode est appelée sur un bloc existant et donne un nouvel ID de bloc, et est donc responsable de récupérer toutes les données de l'instance courante du bloc et de s'assurer que les données sont mappées à la nouvelle instance du bloc.

delete()

Cette méthode est responsable du nettoyage de toutes les informations du bloc lorsque celui-ci est supprimé.

NOTE IMPORTANTE : Assurez vous d'appeller parent::__methodname(); lorsque vous avez terminé avec votre code perso.