Craft CMS

After a pretty long time using WordPress to build content managed sites I’ve finally gotten to the point where I’m not doing it anymore. A couple of reasons for this which I’ll get into in a moment. Don’t get me wrong, WordPress has served me well over the years, and we have really learnt to make good sites using WP. For more info on that I’ll just send you over to Roots.

That being said; it’s still a pain in the arse to use WordPress as a CMS — which is what we tend to do a lot of. The lack of any real templating language is the one of the main pains for me – using PHP functions and logic right in the templates seems like a lot of hard work for a non-programmer like myself. Thankfully I’ve spent many years in there so it’s gotten easier. The next major bugbear is that a lot of what should be standard functionality for a modern CMS simply isn’t there:

  • No native way to add custom fields to posts.
  • No easy way to make custom post types (yes, it’s easy if you’re a programmer)
  • Out of the box it’s pretty easy to create a hackable, unsafe website. 

I know what you’re thinking: “Darren, just use plugins, man – that’s what they’re there for!” Okay, yes – but there are literally thousands of plugins and most of them are shit at best and completely unsafe at worst. Over the years we’ve worked out the best ones to use, but this stuff should really be baked in, right?

No more

A few months back we discovered a new(ish) CMS called Craft. After a lot of research it became clear that I needed to try it out. What you’re looking at now is the start of that process. I’ve spent the last couple of weeks building this site using Craft. I’ve started over a few times, but that’s the point: trial and error; learn, learn, learn.

What I like about Craft is that someone with very little programming chops can get a pretty complex CMS up and running within a few hours. Custom post types (or Entries in Craft parlance) are a breeze to setup using the great admin interface. Custom fields also. And there are lots of great defaults to use. I’m not going to get into the detail here, but suffice it to say that it is an enjoyable experience.

A few tips

I’ve picked up a few nifty tips and tricks while setting up this site. Techniques, plugins & best practice. I’m still learning so please tell me if it’s bullshit.

Move your templates and plugins folders out of the main craft folder

Craft Ls@2X

This allows you to have it in Git without getting all caught up in the core craft files. Also makes for a slightly neater project folder. To get this to work you will need to update public/index.php to reflect that change: 

<?php

// Path to your craft/ folder
$craftPath = '../craft';


// Move plugins path to right above web root
define('CRAFT_PLUGINS_PATH', realpath(dirname(__FILE__) . "/../plugins").'/');

// Move templates path to right above web root
define('CRAFT_TEMPLATES_PATH', realpath(dirname(__FILE__) . "/../templates").'/');



// Do not edit below this line
$path = rtrim($craftPath, '/').'/app/index.php';

if (!is_file($path))
{
    exit('Could not find your craft/ folder. Please ensure that <strong><code>$craftPath</code></strong> is set correctly in '.__FILE__);
}

require_once $path;

Environment based config

There are two main configuration files you need to tweak for your setup: craft/config/db.php and craft/config/general.php I encourage you to read the documentation.

Both files have a similar pattern so I’ll illustrate using the db.php example:

$customDbConfig = array(
	// For all environmants
  '*' => array(
  		// Use the same prefix in all environments
  		'tablePrefix' 	=> 'craft',
  		'server' 		=> 'localhost',
		'user' 			=> 'username',
		'password' 	=> 'password',
		'database' 	=> 'database_name'
  ),
  
  // Dev database info
	'.dev' => array(
  		'server' 		=> 'localhost',
		'user' 			=> 'username',
		'password' 	=> 'password',
		'database' 	=> 'database_name'
  ),
  
  // Live database info
	'www.yoursite.com' => array(
  		'server' 		=> 'localhost',
		'user' 			=> 'username',
		'password' 	=> 'password',
		'database' 	=> 'database_name'
  )
);

Setup server paths & URLs to use in the CMS admin

The idea here is that you can setup CMS variables from your general configuration file. These need to be defined in the craft/config/general.php config file like the example below:

// Ensure our urls have the right scheme
define('URI_SCHEME',  ( isset($_SERVER['HTTPS'] ) ) ? "https://" : "http://" );
// The site url
define('SITE_URL',    URI_SCHEME . $_SERVER['SERVER_NAME'] . '/');
// The site basepath
define('BASEPATH',    realpath(dirname(__FILE__) . '/../') . '/');

$customConfig = array(
  '*' => array(
    // Environmental variables
    //    siteUrl   can be references as {siteUrl}
    //    basePath  can be references as {basePath}
    'environmentVariables' => array(
      'basePath' => BASEPATH,
      'siteUrl'  => SITE_URL
    ),
...

We can now use the two CMS variables throughout our CMS setup as is illustrated in the following screenshot

Screenshot 2016 04 15 16 05 53
basePath & baseURL in the Assets setting page.

Plugins I’ve used & will continue to use on future projects

Blueprint

From the README

Show, filter and provide overview (names, handles, twig variables) of all defined content (fields, sections, globals, assets, categories, tags …).
Because I forget things. Just ask my wife.

This is purely a development plugin. What I mean by that is that it shows you all your custom fields, entries, etc on one easy page. A cheatsheet, if you will. Looks like this:

Screenshot 2016 04 15 16 30 42
Makes life easier

I’ve found this such a help while building the twig templates. A handy reference of all the custom bits and pieces you’ve added.

Typogrify

This is a nifty little addition that gives you twig filters to use with text output in your templates. You have access to a bunch of filters which will prettifiy your web typography by preventing ugly quotes and widows and providing CSS hooks to style some special cases.

Truncate

Pretty much what it says on the box – gives you a twig filter to truncate text fields. Useful for automagic excerpts on a landing page, etc.

Retinafy

This will automatically take an image uploaded with @2x in the file name and create a half sized version. It’ll then spew out the correct srcset attribute.

Many others

There are lots of really useful plugins out there – the ones I’ve mentioned are just handy little helpers. Check here for a much larger list of plugins.

Help

There is an excellent community that you can tap into if you need help with any aspect of Craft CMS. I’ve found the official docs & support pages very useful. There’a a bunch of good Stack Exchange threads and an active and responsice Slack group

As I mentioned earlier, I’m still very much learning so if you have any tips please let me know on twitter.