Sviluppo di un plug-in personalizzato per ottobre CMS

L'anno scorso ho fatto delle ricerche sui nuovi sistemi CMS in PHP per trovare una buona alternativa a WordPress. Idealmente, doveva essere una soluzione open source con una base di codice pulita e moderna.

Uno di questi ha catturato il mio interesse: October CMS. L'ho provato e mi è piaciuto quasi subito. La struttura del codice era davvero bella ed è stato facile scrivere plugin personalizzati.

Questo articolo ha lo scopo di darti una panoramica di cosa aspettarti dalla piattaforma e darti un assaggio prima di decidere di impegnarti a utilizzarla.

Perché scegliere October come piattaforma CMS?

Ci sono alcuni motivi principali per cui ho deciso personalmente di usarlo per i miei progetti.

Alimentato da Laravel

October si basa sul framework PHP più potente per la creazione di app Web moderne: Laravel. Posso dire con grande sicurezza che è il migliore. È molto facile da usare e comprendere e ha tutte le funzionalità di cui ha bisogno un framework moderno, dal routing, alla mappatura relazionale degli oggetti (ORM), all'autorizzazione, alla memorizzazione nella cache e molti altri che forniscono una struttura MVC piacevole e chiara. Poiché è alimentato da Laravel, October ha ereditato tutte quelle caratteristiche dal suo fratello maggiore.

Codice pulito e documentazione

A differenza di molte altre soluzioni CMS, October ha una base di codice molto pulita e ben documentata. È scritto usando un paradigma orientato agli oggetti. Invece del semplice vecchio PHP, October utilizza Twig come motore di creazione di modelli, il che semplifica le cose per gli sviluppatori. Anche la documentazione tecnica è ben scritta e ti aiuta a trovare rapidamente le risposte alla maggior parte delle tue domande.

Grande Comunità

Anche se la community di October non è ancora così grande, è molto utile e reattiva. C'è un canale Slack pubblico a cui puoi unirti, dove troverai sviluppatori felici di aiutarti a risolvere il tuo problema.

Grande mercato

Come WordPress e altri CMS, October ha un mercato per temi e plugin. Anche se non ci sono molti buoni temi tra cui scegliere, ci sono oltre 700 plugin in questo momento, quindi è molto probabile che sarai in grado di aggiungere funzionalità semplicemente cercando e installandone uno. Una grande caratteristica dei plugin è che possono essere facilmente sincronizzati tra tutti i tuoi progetti se aggiungi semplicemente il tuo ID progetto nella dashboard di amministrazione.

PlugIn e componenti

I plugin sono una base per aggiungere nuove funzionalità a ottobre. Un plug-in può essere costituito da più file e directory responsabili della registrazione di componenti personalizzati, modelli, aggiornamento della struttura del database o aggiunta di traduzioni.

Un plugin viene solitamente creato nella directory plugins/ del progetto. Poiché molti plug-in vengono inviati al mercato per essere utilizzati da altri, ogni plug-in dovrebbe avere uno spazio dei nomi personalizzato, che di solito inizia con il nome dell'azienda o dello sviluppatore che ha creato il plug-in. Quindi, ad esempio, se il tuo nome è Acme e hai creato un fantastico plugin chiamato Blog, il tuo plugin vivrà sotto lo spazio dei nomi di Acme\Blog .

Lascia che ti mostri come potrebbe apparire una struttura di directory di plugin:

Come puoi vedere, esiste anche un file chiamato plugin.php che è responsabile della registrazione di un plugin e di tutti i suoi componenti in ottobre CMS.

Un'altra cosa importante da menzionare è che non tutte le directory sopra elencate sono necessarie per l'esecuzione di un plugin. Il tuo plugin potrebbe avere la seguente struttura e funzionare ancora perfettamente:

Molto spesso, un plug-in viene creato per aggiungere solo una funzionalità. Ad esempio, il plug-in "Traduci" è progettato per aiutarti a tradurre i contenuti del tuo sito Web in diverse lingue e fornire il supporto multilingue per gli utenti.

October CMS ha un ottimo mercato dove puoi trovare per le tue esigenze.

A differenza di WordPress e di altri popolari CMS, anche i plugin di ottobre possono avere componenti. Secondo la documentazione di October, i componenti sono "elementi di costruzione configurabili che possono essere allegati a qualsiasi pagina, parziale o layout". Esempi potrebbero includere: un modulo di contatto, la navigazione, un elenco di FAQ e le relative risposte; praticamente tutto ciò che ha senso raggruppare insieme come un unico elemento costitutivo che può essere riutilizzato su più pagine.

I componenti vengono creati come parte di un plug-in ed esistono nella sottodirectory components/ :

Ogni componente ha un file PHP come nomecomponente.php che definisce il componente, nonché una sottodirectory opzionale per i componenti parziali. Una cartella dei componenti parziali deve avere lo stesso nome in minuscolo del componente stesso.

Per dimostrare come funziona un componente, supponiamo che il nostro componente sia responsabile della visualizzazione dei post del blog.

 namespace Acme\Blog\Components; class BlogPosts extends \Cms\Classes\ComponentBase { public function componentDetails() { return [ 'name' => 'Blog Posts', 'description' => 'Displays a collection of blog posts.' ]; } // This array becomes available on the page as {{ component.posts }} public function posts() { return ['First Post', 'Second Post', 'Third Post']; } }

Come possiamo vedere, il componente ha due funzioni principali. Il primo, componentDetails() , fornisce informazioni sul componente all'amministratore che aggiungerà e utilizzerà i componenti sulle proprie pagine web.

La seconda funzione, posts() , restituisce post fittizi che possono quindi essere utilizzati all'interno di un componente partial (file blogposts/default.htm ) come questo:

 url = "/blog" [blogPosts] == {% for post in blogPosts.posts %} {{ post }} {% endfor %}

Affinché il CMS di ottobre sappia che il nostro componente esiste, dobbiamo registrarlo utilizzando il nostro file di plugin principale all'interno di una funzione denominata registerComponents() :

 public function registerComponents() { return [ 'October\Demo\Components\Todo' => 'demoTodo' ]; }

Creazione di un plug-in per modulo di contatto personalizzato

Creeremo un plug-in personalizzato per il modulo di contatto. Ecco le ipotesi su come dovrebbe funzionare il plugin:

• Il modulo avrà i seguenti campi: Nome, Cognome, Email, Messaggio.
• I dati verranno inviati al server tramite Ajax.
• Dopo l'invio dei dati, l'amministratore riceverà un'e-mail con il messaggio inviato dall'utente.

Ai fini di questo tutorial utilizzeremo una nuova installazione di October CMS:

Iniziamo a creare il nostro plugin eseguendo un comando in un terminale che genererà la struttura del plugin: php artisan create:plugin progmatiq.contactform

L'argomento progmatiq.contactform contiene il nome dell'autore (progmatiq) e il nome del plugin (contactform).

Ora dobbiamo aprire il nostro file plugin.php e modificare i dettagli del plugin nel seguente metodo:

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

Ecco alcuni altri metodi che dovresti dare un'occhiata:

• registerComponents()
  Qui puoi definire una serie di componenti forniti dal tuo plug-in.
• registerPermissions()
  È possibile registrare autorizzazioni personalizzate da utilizzare successivamente in altre aree dell'applicazione.
• registerNavigation()
  Puoi aggiungere una voce di menu personalizzata con un URL al menu della dashboard dell'amministratore.

Ora creiamo il nostro componente ContactForm :

1. Crea una nuova cartella denominata componenti/ all'interno della directory principale del tuo plug-in.
2. Crea un file chiamato contactForm.php all'interno della cartella components/ .



3. Incolla il codice seguente che dirà a October cosa fa il nostro componente. Possiamo farlo creando un metodo all'interno del nostro componente chiamato componentDetails() .

 <?php namespace Progmatiq\Contactform\Components; use Cms\Classes\ComponentBase; class ContactForm extends ComponentBase { public function componentDetails() { return [ 'name' => 'Contact Form', 'description' => 'A simple contact form' ]; } }

Ora dobbiamo registrare il nostro componente all'interno del plug-in. Per farlo, modifichiamo il metodo registerComponents() :

 public function registerComponents() { return [ 'Progmatiq\Contactform\Components\ContactForm' => 'contactForm', ]; }

Questa funzione restituisce una serie di componenti forniti dal nostro plugin. Il nome completo della classe del componente è una chiave in questo metodo e un valore è un alias che useremo per fare riferimento al nostro componente all'interno dei nostri modelli Twig.

Una volta registrato il componente, possiamo creare una nuova pagina di contatto e aggiungere il nostro componente (i numeri nei passaggi si riferiscono allo screenshot):

1. Nella dashboard di amministrazione vai su CMS (1) > Pagine (2) e fai clic su + Aggiungi (3).
2. Assegna alla tua pagina un nome e un URL (4).
3. Assegna un nome al file (5) e seleziona il layout predefinito (6).

Aggiungiamo il nostro nuovo componente alla pagina:

1. Fare clic su Componenti nel menu a sinistra (1) e quindi selezionare il nostro componente "Modulo di contatto". Dopo aver fatto clic su di esso (2), dovrebbe essere aggiunto alla pagina.
2. Abbiamo bisogno di inserire un pezzo di codice che dia alla nostra pagina un titolo, oltre a rendere il componente usando la direttiva Twig {% component 'contactForm' %} :

 <div class="container"> <h1> Contact </h1> {% component 'contactForm' %} </div>

Se apri la tua pagina dei contatti in questo momento, vedrai il titolo che dice "Contatto" e nient'altro.

Questo perché il nostro modulo di contatto non ha alcun codice HTML da visualizzare.

Dobbiamo creare un file contactform/default.htm all'interno della nostra cartella components/ .

E aggiungi il seguente codice HTML al file:

 <form method="POST" data-request="onSend" data-request-validate data-request-success="this.reset(); alert('Thank you for submitting your inquiry')" > <div> <label for="first_name">First Name</label> <input type="text" name="first_name" class="form-control"> <p data-validate-for="first_name" class="text-danger"></p> </div> <div> <label for="last_name">Last Name</label> <input type="text" name="last_name" class="form-control"> <p data-validate-for="last_name" class="text-danger"></p> </div> <div> <label for="email">Email</label> <input type="text" name="email" class="form-control"> <p data-validate-for="email" class="text-danger"></p> </div> <div> <label for="content">Content</label> <textarea rows="6" cols="20" name="content" class="form-control"></textarea> <p data-validate-for="content" class="text-danger"></p> </div> <div> <button type="submit" class="btn btn-primary" data-attach-loading>Send</button> </div> </form>

La maggior parte di questo codice è piuttosto semplice. Tuttavia, è aromatizzato con attributi data-* speciali che ottobre ci consente di utilizzare:

1. Il tag <form> ha tre attributi speciali:
   • data-request="onSend" . Questo attributo indica a October che la funzione onSend del nostro componente (che creeremo in seguito) deve essere chiamata quando il modulo viene inviato utilizzando Ajax.
   • data-request-validate consentirà la convalida del modulo Ajax utilizzando errori che verranno inviati dal server se il modulo non è valido.
   • data-request-success="this.reset(); alert('Thank you for submitting your inquiry')" cancella il modulo e quindi attiva il messaggio di avviso se la richiesta ha avuto esito positivo e non sono presenti errori di convalida o lato server.
2. Ogni input ha un blocco seguente che è responsabile della visualizzazione degli errori di convalida restituiti dal server per quel dato input:

 <p data-validate-for="content" class="text-danger"></p>

3. Il pulsante di invio ha l'attributo data-attach-loading , che aggiungerà uno spinner e disabiliterà il pulsante mentre la richiesta viene elaborata dal server. Questo viene fatto al fine di evitare che l'utente invii nuovamente un modulo fino al completamento della richiesta precedente.

Ed ecco come appare ora la nostra pagina:

Torniamo al nostro componente contactForm.php e creiamo il onSend() e validate() che sarà responsabile della gestione dell'invio del modulo:

 public function onSend() { // Get request data $data = \Input::only([ 'first_name', 'last_name', 'email', 'content' ]); // Validate request $this->validate($data); // Send email $receiver = '[email protected]'; \Mail::send('progmatiq.contact::contact', $data, function ($message) use ($receiver) { $message->to($receiver); }); } protected function validate(array $data) { // Validate request $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->fails()) { throw new ValidationException($validator); } }

La prima cosa che stiamo facendo è ottenere i dati dalla richiesta e convalidarli usando il metodo helper validate() . (Tutte le regole di convalida disponibili che puoi utilizzare sono disponibili nella documentazione.) Se la convalida fallisce, il metodo validate() genererà l'eccezione ValidationException e l'esecuzione del codice si interromperà e il server risponderà con il codice di stato 406 e con la convalida messaggi.

Se la convalida ha esito positivo, invieremo un'e-mail al nostro amministratore.

Nota : per semplicità, ho presupposto che l'e-mail a cui vogliamo inviare l'invio sia [email protected]. Assicurati di utilizzare la tua e-mail!

Ecco il codice completo del plug-in contactForm.php :

 <?php namespace Progmatiq\Contactform\Components; use Cms\Classes\ComponentBase; use October\Rain\Exception\ValidationException; class ContactForm extends ComponentBase { public function componentDetails() { return [ 'name' => 'Contact Form', 'description' => 'A simple contact form' ]; } public function onSend() { // Get request data $data = \Input::only([ 'first_name', 'last_name', 'email', 'content' ]); // Validate request $this->validate($data); // Send email $receiver = '[email protected]'; \Mail::send('progmatiq.contact::contact', $data, function ($message) use ($receiver) { $message->to($receiver); }); } protected function validate(array $data) { // Validate request $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->fails()) { throw new ValidationException($validator); } } }

Come puoi vedere, il primo argomento accettato dalla funzione Mail::send() è il nome del modello di email che verrà visualizzato per il corpo dell'email. Dobbiamo crearlo nel pannello di amministrazione. Vai su Impostazioni > Modelli di posta e fai clic sul pulsante Nuovo modello . Quindi compila il modulo come mostrato nella schermata seguente:

Ecco il corpo dell'e-mail che utilizzeremo:

 You have received a new contact inquiry **First Name**: {{ first_name }} *** **Last Name**: {{ last_name }} *** **Email**: {{ email }} *** **Message**: {{ content }} ***

Ora salva il modello di email. La prossima cosa che dobbiamo fare è configurare il server SMTP che invierà le email.

Vai su Impostazioni > Configurazione posta e compila tutte le impostazioni.

Ovviamente, non condividerò la mia configurazione personale. Usa le tue impostazioni.

A questo punto abbiamo tutto pronto per iniziare a testare il nostro componente del modulo di contatto.

Innanzitutto, controlliamo se la convalida funziona quando lasciamo vuoto il campo "Contenuto" e inseriamo un'e-mail non valida:

La convalida funziona come previsto. Ora inseriamo i dati corretti e vediamo se l'e-mail verrà inviata correttamente al nostro amministratore.

Ecco l'e-mail che [email protected] riceverà:

Dopo che il modulo è stato inviato correttamente, l'utente vedrà un messaggio di avviso che lo informa che l'operazione è andata a buon fine:

Conclusione

In questo tutorial, abbiamo spiegato cosa sono un plug-in e un componente e come utilizzarli con October CMS.

Non aver paura di creare un plug-in personalizzato per il tuo progetto se non riesci a trovarne uno esistente adatto alle tue esigenze. Non è così difficile e hai il pieno controllo su di esso e puoi aggiornarlo o estenderlo in qualsiasi momento. Anche la creazione di un semplice plug-in per moduli di contatto come abbiamo fatto oggi può essere utile se si desidera poi integrarlo con altri servizi come Mailchimp o HubSpot.

Spero che questo tutorial ti sia stato utile. Se hai domande, non esitare a chiedere nella sezione commenti qui sotto.