Fermer

octobre 8, 2019

Développer un plugin personnalisé pour October CMS8 minutes de lecture


À propos de l'auteur

Andriy Haydash est l'un des fondateurs de PROGMATIQ agence de conception de sites Web. Il se spécialise dans la création de sites Web pour les propriétaires de petites entreprises afin de les aider à…
Plus d'informations sur
Andriy
Haydash

Si vous aimez écrire du code orienté objet et facile à lire, cet article est pour vous. Vous apprendrez comment écrire votre propre plugin et pourquoi octobre peut être un bon choix pour votre prochain projet.

L'année dernière, j'ai effectué des recherches sur les nouveaux systèmes CMS en PHP afin de trouver une bonne alternative à WordPress . Idéalement, il devait s'agir d'une solution à source ouverte dotée d'une base de code propre et moderne

L'un d'eux intéressait: October CMS . Je l'ai essayé et presque instantanément aimé. La structure du code était vraiment agréable et il était facile d'écrire des plugins personnalisés.

Cet article a pour but de vous donner un aperçu de ce à quoi vous attendre de la plate-forme et de vous en donner un avant-goût avant de décider de vous engager à l'utiliser. 19659007] Pourquoi choisir October comme plate-forme CMS?

J'ai personnellement décidé de l'utiliser personnellement pour mes projets pour plusieurs raisons.

Powered By Laravel

Octobre est construit sur le plus puissant des PHP. cadre pour la création d'applications Web modernes: Laravel . Je peux dire avec une grande confiance que c’est le meilleur. Il est très facile à utiliser et à comprendre, et dispose de toutes les fonctionnalités nécessaires à une infrastructure moderne, telles que le routage, le mappage objet-relationnel (ORM), l’autorisation, la mise en cache, etc. Comme il est propulsé par Laravel, October a hérité toutes ces fonctionnalités de son grand frère.

Clean Code And Documentation

Contrairement à de nombreuses autres solutions CMS, October dispose d'un code très propre et bien documenté. C’est écrit en utilisant un paradigme orienté objectivement. Octobre utilise plutôt Twig comme moteur de création de modèles, ce qui simplifie les choses pour les développeurs. La ​​documentation technique est également bien écrite et vous aide à trouver rapidement des réponses à la plupart de vos questions.

Même si la communauté d’octobre n’est pas encore si nombreuse, elle est très utile et réactive. Vous pouvez vous joindre à une chaîne publique Slack, où les développeurs seront ravis de vous aider à résoudre votre problème.

Big Marketplace

Comme WordPress et d’autres CMS, Octobre est un marché pour les thèmes et les plug-ins. Bien qu’il n’y ait pas beaucoup de bons thèmes à choisir, il existe actuellement plus de 700 plugins. Il est donc très probable que vous pourrez ajouter des fonctionnalités simplement en recherchant et en installant l’un d’eux. Une fonctionnalité intéressante des plugins est qu'ils peuvent être facilement synchronisés entre tous vos projets si vous ajoutez simplement l'ID de votre projet dans le tableau de bord de l'administrateur.

Plug-ins et composants

Les plug-ins permettent d'ajouter de nouvelles fonctionnalités à October. Un plugin peut comprendre plusieurs fichiers et répertoires chargés d'enregistrer des composants personnalisés, des modèles, de mettre à jour la structure de la base de données ou d'ajouter des traductions.

Un plugin est généralement créé dans le répertoire plugins / du projet. Étant donné que de nombreux plug-ins sont soumis au marché pour que d'autres puissent les utiliser, chaque plug-in doit avoir un espace de noms personnalisé, qui commence généralement par le nom de la société ou du développeur qui a créé le plug-in. Ainsi, par exemple, si votre nom est Acme et que vous avez créé un plugin génial appelé Blog, votre plugin vivra sous l’espace-noms de Acme Blog .

Laissez-moi vous montre comment une structure de répertoire de plug-in pourrait ressembler à:

 Exemple de structure de répertoire de plug-in
Exemple de structure de répertoire de plug-in ( Grand aperçu )

Comme vous pouvez le constater, il existe également un fichier appelé plugin.php responsable de l'enregistrement d'un plugin et de tous ses composants dans le système de gestion d'octobre

Une autre chose importante à noter est que tous les répertoires énumérés ci-dessus ne sont pas nécessaires à son exécution. Votre plugin pourrait avoir la structure suivante et fonctionner encore parfaitement:

 Structure de répertoire de plugin simple
Structure de répertoire de plugin simple ( Grand aperçu )

Le plus souvent, un plugin est construit pour ajouter seulement une fonctionnalité. Par exemple, le plug-in "Traduire" est conçu pour vous aider à traduire le contenu de votre site Web dans différentes langues et à fournir un support multilingue aux utilisateurs.

Octobre Le CMS offre un excellent marché où vous pouvez trouver ce dont vous avez besoin.

 Marché d'octobre
Marché d'octobre ( Grand aperçu )

Contrairement à WordPress et à d'autres systèmes de gestion de contenu populaires, les plugins d'Octobre peuvent également comporter des composants. Selon la documentation d’octobre, les composants sont des «éléments de construction configurables qui peuvent être attachés à n’importe quelle page, partie ou présentation.» Les exemples peuvent inclure: un formulaire de contact, la navigation, une liste de FAQ et leurs réponses; En principe, tout ce qui a du sens à regrouper comme un bloc de construction pouvant être réutilisé sur plusieurs pages.

Les composants sont créés en tant que composants d'un plugin et existent dans le sous-répertoire composants / : [19659032] Structure du répertoire des composants « />

Structure du répertoire des composants ( Grand aperçu )

Chaque composant contient un fichier PHP tel que composantName.php qui définit le composant, ainsi qu'un sous-répertoire facultatif. pour les composants partiels. Un dossier de composants partiels doit porter le même nom en minuscule que le composant lui-même.

Pour montrer comment un composant fonctionne, supposons que notre composant est responsable de l'affichage des articles de blog.

 espace de nom Acme  Blog  Components;

classe BlogPosts extend  Cms  Classes  ComponentBase
{
    fonction publique composantDétails ()
    {
        retour [
            'name' => 'Blog Posts',
            'description' => 'Displays a collection of blog posts.'
        ];
    }

    // Ce tableau devient disponible sur la page en tant que {{composant.posts}}
    messages de fonction publique ()
    {
        retour ['First Post', 'Second Post', 'Third Post'];
    }
} 

Comme nous pouvons le constater, le composant a deux fonctions principales. Le premier, composantDetails () fournit des informations sur le composant à l'administrateur qui ajoutera et utilisera des composants sur ses pages Web.

La seconde fonction, posts () renvoie des articles factices qui peuvent ensuite être utilisés dans un composant partiel ( blogposts / default.htm fichier) comme ceci:

 url = "/ blog"

[blogPosts]
==
{% pour la publication dans blogPosts.posts%}
    {{post}}
{% endfor%} 

Pour que CMS d'octobre sache que notre composant existe, nous devons l'enregistrer à l'aide de notre fichier de plug-in principal dans une fonction nommée registerComponents () :

 public function registerComponents ()
{
    retour [
        'OctoberDemoComponentsTodo' => 'demoTodo'
    ];
} 

Création d’un plug-in de formulaire de contact personnalisé

Nous allons créer un plug-in de formulaire de contact personnalisé. Voici les hypothèses sur le fonctionnement du plug-in:

  • Le formulaire comportera les champs suivants: Prénom, Nom, Email, Message.
  • Les données seront soumises au serveur à l'aide de Ajax.
  • Après les données est envoyé, l'administrateur recevra un email avec le message envoyé par l'utilisateur.

Pour les besoins de ce tutoriel, nous allons utiliser une nouvelle installation du système de gestion de contenu d'octobre: ​​

 Vue par défaut après la nouvelle installation
Vue par défaut après nouvelle installation ( Grand aperçu )

Commençons par créer notre plugin en lançant une commande dans un terminal qui générera la structure du plugin: php artisan create: plugin progmatiq.contactform

 Création d'un nouveau plugin depuis terminal
Création d'un nouveau plugin depuis terminal ( Grand aperçu )

L'argument progmatiq.contactform contient le nom de l'auteur (progmatiq) et le nom de celui-ci. le plugin (contactform).

 Nouveau plugin structure des dossiers
Nouvelle structure des dossiers des plugins ( Grand aperçu )

Nous devons maintenant ouvrir notre fichier plugin.php et modifier les détails du plugin de la manière suivante:

 ] fonction publique pluginDetails ()
   {
        retour [
            'name'        => 'Contact Form',
            'description' => 'A simple contact form plug-in',
            'author'      => 'progmatiq',
            'icon'        => 'icon-leaf'
        ];
    } 

Voici quelques autres méthodes que vous devriez examiner:

  • registerComponents ()
    Vous pouvez définir ici un tableau de composants fournis par votre plug-in.
  • registerPermissions ()
    Vous pouvez enregistrer des autorisations personnalisées que vous pourrez ensuite utiliser ultérieurement dans d'autres zones de l'application.
  • registerNavigation ()
    Vous pouvez ajouter un élément de menu personnalisé avec une URL au menu du tableau de bord de l'administrateur. .

Créons maintenant notre composant ContactForm :

  1. Créez un nouveau dossier nommé components / dans le répertoire racine de votre plug-in.
  2. Créez un fichier nommé ] contactForm.php dans le dossier composants / .
  3.  Création d'un nouveau composant
    Création d'un nouveau composant ( Grand aperçu )
  4. Collez le code suivant. cela dira à octobre ce que fait notre composante. Nous pouvons le faire en créant une méthode dans notre composant appelée composantDetails () .
  'Formulaire de contact',
            'description' => 'Un simple formulaire de contact'
        ];
    }
} 

Nous devons maintenant enregistrer notre composant dans le plug-in. Pour ce faire, nous modifions la méthode registerComponents () :

 public function registerComponents ().
    {
        retour [
            'ProgmatiqContactformComponentsContactForm' => 'contactForm',
        ];
    } 

Cette fonction retourne un tableau de composants fournis par notre plugin. Le nom de classe complet du composant est une clé dans cette méthode et une valeur est un alias que nous utiliserons pour référencer notre composant dans nos modèles Twig.

Une fois le composant enregistré, vous pouvez créer une nouvelle page de contact et ajoutez notre composant (les numéros dans les étapes se rapportent à la capture d'écran):

  1. Dans votre tableau de bord administrateur, accédez à CMS (1)> Pages (2) et cliquez sur + Ajoutez (3).
  2. Donnez à votre page un nom et une URL (4).
  3. Nommez votre fichier (5) et sélectionnez la mise en page par défaut (6).
 Création d'une page de contact [19659021] Création d'une page de contact (<a href= Grand aperçu )

Ajoutons notre nouveau composant à la page:

  1. Cliquez sur Composants dans le menu de gauche (1), puis sélectionnez notre composant "Formulaire de contact". Une fois que vous avez cliqué dessus (2), il devrait être ajouté à la page.
  2. Nous devons placer un morceau de code qui donnerait à notre page un titre et rendrait le composant à l'aide du {% composant '. contactForm '%} Directive sur les brindilles:

Contact

    {% composant 'contactForm'%}
 Ajout d'un composant de formulaire de contact à la page de formulaire de contact
Ajout d'un composant de formulaire de contact à la page de formulaire de contact ( Grand aperçu )

Si vous ouvrez votre page de contact maintenant, vous verrez le titre intitulé “Contact” et rien d'autre.

 Page de contact
Page de contact ( Grand aperçu )

En effet, notre formulaire de contact n'a pas de code HTML à restituer.

Il nous faut créez un fichier contactform / default.htm dans notre dossier composants / .

 Ajout d'une vue HTML à notre composant
Ajout d'une vue HTML à notre composant ( Image agrandie )

Et ajoutez le code HTML suivant au fichier:

    

La ​​plupart de ce code est assez simple. Cependant, elle est assortie d'attributs spéciaux de données * qu'Octobre nous permet d'utiliser :


  1. La balise possède trois attributs spéciaux:

    • data-request = " onSend ". Cet attribut indique à octobre que la fonction onSend de notre composant (que nous allons créer par la suite) doit être appelée lorsque le formulaire est soumis à l'aide d'Ajax.
    • data-request-validate activera la validation de formulaire Ajax en utilisant des erreurs qui seront envoyées par le serveur si le formulaire est invalide.
    • data-request-success = "this.reset (); alert ('Merci d'avoir soumis votre inquiry ') " efface le formulaire, puis déclenche le message d'alerte si la demande aboutit et qu'aucune erreur de validation ou côté serveur n'est présente.
  2. Chaque entrée a un bloc suivant responsable. pour afficher les erreurs de validation renvoyées par le serveur pour cette entrée donnée:
  3. Le bouton d'envoi a l'attribut data-attach-loading ce qui ajoute un spinner et le désactive pendant le traitement de la demande par le serveur. Ceci afin d'éviter que l'utilisateur ne soumette à nouveau un formulaire tant que la demande précédente n'est pas terminée.

Voici comment notre page se présente:

 Vue de la page de contact
Vue de la page de contact ( Grand aperçu )

Revenons à notre composant contactForm.php et créons la méthode d'assistance onSend () ainsi que validate () être responsable du traitement de la soumission du formulaire:

 public function onSend ()
    {
        // Obtenir les données de la demande
        $ data =  Input :: only ([
            'first_name',
            'last_name',
            'email',
            'content'
        ]);

        // Valider la demande
        $ this-> validate ($ data);

        // Envoyer un email
        $ receiver = 'admin@gmail.com';

         Mail :: send ('progmatiq.contact::contact', $ data, function ($ message) use ($ receiver) {
            $ message-> to ($ receiver);
        });
    }

    fonction protégée valider (tableau $ data)
    {
        // Valider la demande
        $ rules = [
            'first_name' => 'required|min:3|max:255',
            'last_name' => 'required|min:3|max:255',
            'email' => 'required|email',
            'content' => 'required',
        ];

        $ validator =  Validator :: make ($ data, $ rules);

        if ($ validator-> fail ()) {
            lance la nouvelle ValidationException ($ validator);
        }
    }

La ​​première chose à faire est d’obtenir des données de la requête et de les valider à l’aide de la méthode auxiliaire validate () . ( Toutes les règles de validation disponibles que vous pouvez utiliser se trouvent dans la documentation .) Si la validation échoue, la méthode validate () lève l'exception ValidationException l'exécution du code s'arrête et le serveur répond par le code d'état 406 et par des messages de validation

Si la validation aboutit, nous vous enverrons un courrier électronique à notre administrateur

. : Par souci de simplicité, j'ai supposé que le courrier électronique auquel nous souhaitons envoyer la soumission était admin@gmail.com. Assurez-vous d'utiliser votre propre email!

Voici le code complet de votre plug-in contactForm.php :

  'Formulaire de contact',
            'description' => 'Un simple formulaire de contact'
        ];
    }

    fonction publique onSend ()
    {
        // Obtenir les données de la demande
        $ data =  Input :: only ([
            'first_name',
            'last_name',
            'email',
            'content'
        ]);

        // Valider la demande
        $ this-> validate ($ data);

        // Envoyer un email
        $ receiver = 'admin@gmail.com';

         Mail :: send ('progmatiq.contact::contact', $ data, function ($ message) use ($ receiver) {
            $ message-> to ($ receiver);
        });
    }

    fonction protégée valider (tableau $ data)
    {
        // Valider la demande
        $ rules = [
            'first_name' => 'required|min:3|max:255',
            'last_name' => 'required|min:3|max:255',
            'email' => 'required|email',
            'content' => 'required',
        ];

        $ validator =  Validator :: make ($ data, $ rules);

        if ($ validator-> fail ()) {
            lance la nouvelle ValidationException ($ validator);
        }
    }
}

Comme vous pouvez le constater, le premier argument que la fonction Mail :: send () accepte est le nom du modèle de courrier électronique qui sera rendu pour le corps du courrier électronique. Nous devons le créer dans le panneau d'administration. Allez à Paramètres> Modèles de messagerie et cliquez sur le bouton Nouveau modèle . Remplissez ensuite le formulaire tel qu'il apparaît à l'écran ci-dessous:

 Ajout d'un nouveau modèle de courrier électronique
Ajout d'un nouveau modèle de courrier électronique ( Grand aperçu )

Voici le corps du courrier électronique que nous allez utiliser:

 Vous avez reçu une nouvelle demande de contact

**Prénom**:
{{ Prénom }}
***
**Nom de famille**:
{{ nom de famille }}
***
**Email**:
{{ email }}
***
**Message**:
{{ contenu }}
*** 

Enregistrez maintenant le modèle de courrier électronique. La prochaine chose à faire est de configurer le serveur SMTP qui enverra les courriels.

Allez à Paramètres> Configuration du courrier et remplissez tous les paramètres.

 Configuration du serveur de messagerie
Serveur de messagerie configuration ( Grand aperçu )

Évidemment, je ne partagerai pas ma configuration personnelle. Utilisez vos propres paramètres. 😉

À ce stade, nous avons tout prêt pour tester notre composant de formulaire de contact.

Commençons par vérifier si la validation fonctionne lorsque nous laissons le champ “Contenu” vide et introduisons un courrier électronique non valide:

 Validation du formulaire de contact.
Validation du formulaire de contact ( Aperçu large )

La validation fonctionne comme prévu. Entrons maintenant les données correctes et voyons si le courrier électronique sera envoyé avec succès à notre administrateur

Voici le courrier électronique que admin@gmail.com recevra:

: email de soumission du formulaire de contact
Courriel de soumission du formulaire de contact ( Image agrandie )

Une fois le formulaire correctement envoyé, l'utilisateur voit un message d'alerte l'informant que l'opération a abouti:

 Envoi du formulaire de contact
. Soumission réussie du formulaire de contact ( Image agrandie )

Conclusion

Dans ce tutoriel, nous avons présenté le type de plug-in et de composant et leur utilisation avec October CMS.

Don N'hésitez pas à créer un plugin personnalisé pour votre projet si vous ne trouvez pas celui qui correspond à vos besoins. Ce n’est pas si difficile et vous en avez le plein contrôle, et vous pouvez le mettre à jour ou le prolonger à tout moment. Même créer un simple plugin de formulaire de contact comme nous le faisons aujourd'hui peut être utile si vous souhaitez ensuite l'intégrer à d'autres services tels que Mailchimp ou HubSpot.

J'espère que ce tutoriel vous a été utile. Si vous avez des questions, n’hésitez pas à poser vos questions dans la section des commentaires ci-dessous.

 Smashing Editorial (dm, yk, il)



Source link