Laravel to October CMS: The Differences (Part 2)

If you missed it, click here for part one.

So in the previous posts we covered the directory structure of October CMS and then pretty much stuck to plugins from thereon in. Plugins are a powerful beast but, from what we've seen, they don't differ that significantly from Laravel. That's not to say that plugins don't significantly change the game mind.

So onto the next...

Theme Park

So themes basically cover the vast majority of everything you see on the front end; that's HTML, CSS, Javascript, images, fonts and everything that comes between that. I say vast majority because plugins can serve up the same stuff through components (more on those in the next blog).

It's easy enough to create a theme. Head into the CMS, under Settings > CMS > Front-end theme. Click the 'Create a new blank theme' button, fill in some basic settings and you're away. A folder with your theme name will appear with the theme's name and the following structure:

+ assets/
+ content/
+ layouts/
+ pages/
+ partials/
theme.yaml

Your theme definitions are in theme.yaml. All of those folders will be empty to start with and it'll be obvious what some do, here's an explanation anyway!

• assets/ - covers your CSS, Javascript, fonts, images. You can have Less in there too, or Sass, or CoffeeScript. Anything that you consider an 'asset' obviously! You've got pretty free reign to structure this as you like.
• content/ - this is where you put all those bits of static text that you'd usually dump in your page and feel bad about! The great thing about this is it supports HTML (with a .htm extension), plain text (with a .txt extension) and - amazingly - markdown (.md).
• layouts/ - think of this as a house for your main HTML templates. The ones that contain the html, head and body elements, all your page meta, styles, scripts and everything else that's common over your pages. You'll probably only ever have one file in here. But if you've got some pages/sections that need to look very different from the rest, you'll find this useful.
• pages/ - this is where the vast majority of your page HTML will sit. New files for every different page you have.
• partials/ - think of any bit of HTML that you'll need more than once in various different pages, you'll put that here. For example, a little row of share buttons.

Thinking in Laravel terms, this is a combination of the resources/ folder and the assets you'd chuck into the public/ folder. Only the views/ directory is split out into layouts, pages and partials. Probably that's vaguely how you'd divide your views anyway, but it forces you not to keep a messy views/ directory from the off.

FKA Twig

An empty theme probably isn't the best place to learn how to build a theme, so go and have a look at some code in the demo theme. Where the bloody hell are the .blade.php files?! I'm afraid to say, Blade is out, replaced by its older sibling Twig.

The main difference between Twig and Blade is that Blade is essentially PHP with some syntactical differences that make it look nicer for templating;Blade compiles directly to PHP and runs (and displays) where it's called. Twig takes a template and parses it, evaluating the result and outputting it. I'm massively oversimplifying that as I've just given it a cursory glance; for more detail on the inner working, Twig explain it far better than I ever could!

What that means is that you're bound to the syntax that Twig has defined whereas in Blade you're only bound by what you can achieve in PHP. You can even stick PHP tags in there (don't!). A basic example could be as below:

In Blade, you might want to check if a string is empty before outputting it, you'd probably do something like this:

@if (!empty($string))
    {{ $string }}
@endif

Which is effectively just fancy-looking PHP ie this:

Blade probably does some processing on the variable, but it's not far off. Whereas Twig would look as follows:

{% if string|length > 0 %}
    {{ string }}
{% else %}

It's not vastly different but you're having to use one of Twig's filters, length, to achieve the same as you could with some PHP code; you have to learn a new language. Whereas with blade you were just learning a new syntax to the same language. Disclaimer: I prefer Blade!

There are resources that will get you started learning Twig far better than I ever could in the October CMS documentation and in more depth in the Twig documentation. But here's a quick little snippet:

@include('partials.nav')
@yield('content')

In Blade you might put the above in your app.blade.php file where partials.nav is a view in the partials/ directory and is being dropped into the page. And content refers to a section in another view. Your Twig code will look as follows:

{% partial "nav" %}
{% page %}

Where the first line includes the file nav.htm in the partials/ directory. The second line outputs the content of whichever page you're on.

Route Manoeuvre

I just touched on pages, which nicely brings me to the next fairly substantial change: routes. Well, erm... the routes.php file is nowhere to be found. This also takes your controllers out of the equation. At this point, I'm sure a lot of you are befuddled that the C of you MVC has just been blown from the equation.

And it's a baffling decision at first. Instead of pointing routes at functions on controllers, you create a new file in the pages/ directory. Which seems even more baffling! It seems like a step backward; you're creating a new file for each page. Isn't that what you did in the dark ages of procedural PHP?

And the reason is simple; none of your business logic (and so controllers) belong in the theme. Your business logic, as we've determined, belongs in the controllers through a thing called components.

Ch-Ch-Changes

That's a fair few differences with Laravel we've covered so I'll save components for the next post.

Regarding the change to routes, it's worth saying that I don't think this is a perfect solution. It seems a little weird that the pages your application has is dependent on your theme, that changing your theme could potentially change your URL scheme. And what if you're migrating an existing application over to October CMS; how do you translate and redirect your old URLs to the new ones?

It's a question I'd love for someone to answer but one I have no idea about currently. Sorry about that!

So not quite so glowing as my last post, but the separation between themes and plugins is where the deepest differences between Laravel and October CMS lie, for obvious reasons. And developers are like cats; change makes them uncomfortable! But, like cats, it's something they'll get used to.

I think I have legitimate concerns with the routing, but I'm sure there's an explanation and solutions to my issues. My preference for Blade is mostly an opinion and an aversion to having to learn something new. The reality is themes make the most sense for very standard sites and anyone building a bespoke application will have a single theme which is entirely bespoke and will never change. But I'm speaking as a professional developer; everyone else will benefit from themes, as long as the theme developers agree on a standardised URL structure.

Reading in the wrong order? Click here for part one.