About The Creator

Andriy Haydash is a founding father of PROGMATIQ internet design company. He makes a speciality of constructing web sites for small enterprise house owners to assist them construct and develop their …
Extra about
Andriy
Haydash

In the event you like writing object-oriented and easy-to-read code, then this text is for you. You’ll discover ways to write your personal plugin and why October could also be a sensible choice on your subsequent undertaking.

Final yr, I did some analysis about new CMS methods in PHP with a view to discover a very good different to WordPress. Ideally, it needed to be an open-source resolution with a clear and trendy codebase.

One in all them caught my curiosity: October CMS. I attempted it and virtually immediately favored it. The code construction was very nice and it was straightforward to jot down customized plugins.

This text goals to provide you an outline of what to anticipate from the platform and provide you with a style of it earlier than you resolve to decide to utilizing it.

Why Select October As Your CMS Platform?

There are a couple of major explanation why I’ve personally determined to make use of it for my tasks.

Powered By Laravel

October is constructed on prime of essentially the most highly effective PHP framework for creating trendy internet apps: Laravel. I can say with nice confidence that it’s the most effective. It is rather straightforward to make use of and perceive, and has all of the options trendy framework wants, from routing, object-relational mapping (ORM), authorization, caching, and plenty of others that present a pleasant and clear MVC construction. As it’s powered by Laravel, October has inherited all these options from its huge brother.

Clear Code And Documentation

Not like many different CMS options, October has a really clear and well-documented codebase. It’s written in utilizing an objectoriented paradigm. As an alternative of plain outdated PHP, October makes use of Twig as its templating engine, which simplifies issues for builders. Technical documentation can be effectively written, and helps you shortly discover solutions to most of your questions.

Though October’s neighborhood shouldn’t be but that huge, it’s very useful and responsive. There’s a public Slack channel you possibly can be part of, the place you’ll discover builders completely happy to help you in fixing your problem.

Huge Market

Like WordPress and different CMSes, October has a market for themes and plugins. Though there aren’t that many good themes to select from, there are over 700 plugins proper now, so it’s very doubtless you’ll have the ability to add performance by merely looking for and putting in certainly one of them. An ideal characteristic of plugins is that they are often simply synchronized between all of your tasks when you simply add your undertaking ID within the admin dashboard.

PlugIns And Elements

Plugins are a basis of including new performance to October. A plugin can encompass a number of recordsdata and directories which are liable for registering customized parts, fashions, updating database construction, or including translations.

A plugin is often created within the plugins/ listing of the undertaking. Since many plugins are submitted to for others to make use of, every plugin ought to have a customized namespace, which often begins with the title of the corporate or developer that created the plug-in. So, as an illustration, in case your title is Acme and also you’ve created an superior plugin known as Weblog, your plugin will reside underneath the namespace of AcmeBlog.

Let me present you the way a plugin listing construction would possibly appear like:

Pattern plugin listing construction (Massive preview)

As you possibly can see, there may be additionally a file known as plugin.php that’s liable for registering a plugin and all of its parts in October CMS.

One other essential factor to say is that not all directories listed above are obligatory for a plugin to run. Your plugin might have the next construction and nonetheless work completely effectively:

Easy plugin listing construction (Massive preview)

Most frequently, one plugin is constructed so as to add just one piece of performance. For instance, the ‘Translate’ plugin is designed that can assist you translate content material in your web site into totally different languages, and supply the multi-language help for the customers.

October CMS has an important market the place you will discover on your wants.

October market (Massive preview)

Not like WordPress and different fashionable CMSes, October plugins may also have parts. In keeping with October’s documentation, parts are “configurable constructing parts that may be hooked up to any web page, partial or structure.” Examples would possibly embrace: a contact kind, navigation, an inventory of FAQs and their solutions; mainly something that it is sensible to bundle collectively as one constructing block that may be reused on a number of pages.

Elements are created as part of a plugin they usually exist within the parts/ subdirectory:

Element listing construction (Massive preview)

Every part has a PHP file like componentName.php that defines the part, in addition to an non-compulsory subdirectory for part partials. A part partials folder will need to have the identical title in lowercase because the part itself.

To reveal how a part features, let’s assume that our part is liable for displaying weblog posts.

namespace AcmeBlogComponents;

class BlogPosts extends CmsClassesComponentBase

    public operate componentDetails()
    
        return [
            'name' => 'Blog Posts',
            'description' => 'Displays a collection of blog posts.'
        ];
    

    // This array turns into out there on the web page as 
    public operate posts()
    

As we will see, the part has two major features. The primary one, componentDetails(), offers details about the part to the administrator who will add and use parts on their internet pages.

The second operate, posts(), returns dummy posts that may then be used inside a part partial (blogposts/default.htm file) like this:

url = "/weblog"

[blogPosts]
==

    

For October CMS to know our part exists, we should register it utilizing our major plugin file inside a operate named registerComponents():

public operate registerComponents()

Creating A Customized Contact Type plugin

We’re going to create a customized contact kind plug-in. Listed below are the assumptions about how the plugin ought to work:

  • The shape may have the next fields: First Title, Final Title, Electronic mail, Message.
  • Information shall be submitted to the server utilizing Ajax.
  • After knowledge is submitted, the admin will obtain an electronic mail with the message despatched by the person.

For the aim of this tutorial we’ll use a contemporary set up of October CMS:

Default view after contemporary set up (Massive preview)

Let’s begin creating our plugin by working a command in a terminal that may generate the plugin construction: php artisan create:plugin progmatiq.contactform

Creating a brand new plugin from terminal (Massive preview)

The progmatiq.contactform argument comprises the title of the writer (progmatiq) and the title of the plugin (contactform).

New plugin folder construction (Massive preview)

Now we have to open our plugin.php file and modify the plugin particulars within the following methodology:

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

Listed below are a couple of different strategies that it is best to check out:

  • registerComponents()

    Right here you possibly can outline an array of parts that your plugin offers.
  • registerPermissions()

    You’ll be able to register customized permissions which you could then use later in different areas of the appliance.
  • registerNavigation()

    You’ll be able to add a customized menu merchandise with a URL to your admin dashboard menu.

Now let’s create our ContactForm part:

  1. Make a brand new folder named parts/ inside your plug-in’s root listing.
  2. Create a file named contactForm.php contained in the parts/ folder.
  3. Creating a brand new part (Massive preview)
  4. Paste the next code that may inform October what our part does. We will do it by creating a way inside our part known as componentDetails().

Now we have to register our part contained in the plug-in. To do this, we modify the registerComponents() methodology:

    public operate registerComponents()
    

This operate returns an array of parts that our plugin offers. The part’s full class title is a key on this methodology, and a price is an alias that we’ll use to reference our part inside our Twig templates.

As soon as we've registered the part, we will create a brand new contact web page and add our part (numbers within the steps consult with the screenshot):

  1. In your admin dashboard go to CMS (1) > Pages (2) and click on on + Add (three).
  2. Give your web page a reputation and a URL (four).
  3. Title your file (5) and choose the default structure (6).
Making a contact web page (Massive preview)

Let’s add our new part to the web page:

  1. Click on on Elements within the left menu (1) after which choose our “Contact Type” part. When you click on on it (2), it ought to be added to the web page.
  2. We have to place a chunk of code that may give our web page a headline in addition to render the part utilizing the % part ‘contactForm’ % Twig directive:

Contact

Including contact kind part to contact kind web page (Massive preview)

In the event you open your contact web page proper now, you will notice the headline saying “Contact” and nothing else.

Contact web page (Massive preview)

That’s as a result of our contact kind doesn’t have any HTML to render.

We have to create a contactform/default.htm file inside our parts/ folder.

Including an HTML view to our part (Massive preview)

And add the next HTML code to the file:

Most of this code is fairly simple. Nevertheless, it's flavored with particular data-* attributes that October permits us to make use of:


  1. tag has three particular attributes:

    • data-request="onSend". This attribute tells October that the onSend operate from our part (that we’re going to create subsequent) needs to be known as when the shape is submitted utilizing Ajax.
    • data-request-validate will allow kind Ajax validation utilizing errors that shall be despatched from the server if the shape is invalid.
    • data-request-success="this.reset(); alert('Thanks for submitting your inquiry')" clears the shape after which triggers the alert message if the request was profitable and no validation or server-side errors have been current.
  2. Each enter has a following block that's liable for displaying validation errors returned by the server for that given enter:
  3. The submit button has the data-attach-loading attribute, which can add a spinner and disable the button whereas the request is being processed by the server. That is executed with a view to stop the person submitting a kind once more till the earlier request is full.

And right here is how our web page seems now:

Contact web page view (Massive preview)

Let’s return to our contactForm.php part and create the onSend() in addition to validate() helper methodology that shall be liable for dealing with kind submission:

public operate onSend()
    
        // Get request knowledge
        $knowledge = Enter::solely([
            'first_name',
            'last_name',
            'email',
            'content'
        ]);

        // Validate request
        $this->validate($knowledge);

        // Ship electronic mail
        $receiver = 'admin@gmail.com';

        Mail::ship('progmatiq.contact::contact', $knowledge, operate ($message) use ($receiver) 
            $message->to($receiver);
        );
    

    protected operate validate(array $knowledge) 
    min:3

The very first thing we’re doing is getting knowledge from the request and validating it utilizing the validate() helper methodology. (All of the out there validation guidelines you need to use will be discovered within the documentation.) If validation fails, the validate() methodology will throw the ValidationException an exception and code execution will cease, and the server will reply with standing code 406 and with validation messages.

If validation succeeds, then we'll ship an electronic mail to our admin.

Notice: For simplicity, I’ve assumed that the e-mail we wish to ship the submission to is admin@gmail.com. Ensure to make use of your personal electronic mail!

Right here is the complete code of your contactForm.php plug-in:

validate($knowledge);

        // Ship electronic mail
        $receiver = 'admin@gmail.com';

        Mail::ship('progmatiq.contact::contact', $knowledge, operate ($message) use ($receiver) 
            $message->to($receiver);
        );
    

    protected operate validate(array $knowledge) 
    min:3

As you possibly can see, the primary argument that the Mail::ship() operate accepts is the title of the e-mail template that shall be rendered for the e-mail physique. We have to create it within the admin panel. Go to Settings > Mail Templates and click on on the New Template button. Then fill out the shape as it's proven on the display screen beneath:

Including new electronic mail template (Massive preview)

Right here is the physique of the e-mail that we’re going to be utilizing:

You may have acquired a brand new contact inquiry

**First Title**:
 first_name 
***
**Final Title**:
 last_name 
***
**Electronic mail**:
 electronic mail 
***
**Message**:

***

Now save the e-mail template. The subsequent factor we have to do is configure the SMTP server that may ship emails.

Go to Settings > Mail Configuration and fill out all of the settings.

Electronic mail server configuration (Massive preview)

Clearly, I gained’t share my private configuration. Use your personal settings. 😉

At this stage we've all the things prepared to begin testing our contact kind part.

First, let’s examine if validation works after we depart the “Content material” subject empty and enter an invalid electronic mail:

Contact kind validation (Massive preview)

Validation works as anticipated. Let’s now enter right knowledge and see if the e-mail shall be despatched efficiently to our admin.

Right here is the e-mail that admin@gmail.com will obtain:

Contact kind submission electronic mail (Massive preview)

After the shape is submitted efficiently, the person will see an alert message informing him that the operation was profitable:

Profitable submission of contact kind (Massive preview)

Conclusion

On this tutorial, we’ve coated what a plugin and a part are and easy methods to use them with October CMS.

Don’t be afraid to create a customized plugin on your undertaking when you can’t discover an present one that matches your wants. It’s not that tough and you've got full management over it, and you'll replace or prolong it at any time. Even making a easy contact kind plugin like we’ve executed at present will be helpful if you wish to then combine it with different companies like Mailchimp or HubSpot.

I hope this tutorial was useful to you. If in case you have any questions, don’t hesitate to ask within the feedback part beneath.

(dm, yk, il)