Build­ing My Site Part II: Setup

In the first part of this series I talked about the deci­sions that led to using the likes of Craft and Lar­avel Mix. So now it’s time to get it all up and running.

Craft #

At the moment, while Craft is in it’s release can­di­date stage, it’s only avail­able as a Com­pos­er pack­age. This is set to change once it’s ready for a wider release.

I’m using Valet for local devel­op­ment, but you can use what­ev­er suits your work­flow pro­vid­ed it meets the require­ments, with the main ones being PHP >= 7 and either MySQL 5.5+ or Post­greSQL 9.5+. It’s worth look­ing at the full list of require­ments to see what PHP exten­sions are required as well.

To get a starter project installed, you can run:

composer create-project -s RC craftcms/craft PATH_TO_YOUR_PROJECT

And with­in your new project you’ll find the file .env.example which you can rename to .env. This is where you’ll fill in your data­base details, along with any oth­er secrets you want to keep from pry­ing eyes. (If this is going in a git repo, make sure you add .env to your .gitignore.)

Final­ly, then, vis­it­ing your new site will prompt the instal­la­tion wiz­ard to begin which you can fol­low through to install Craft.

Plu­g­ins #

Already, Craft 3 has quite a col­lec­tion of great plu­g­ins and I wast­ed no time in going through them. To be hon­est, I only had a few ideas of the things I need­ed, the rest fell into my life as I fig­ured they’d be nice to have.

  • Con­tact Form — Add a sim­ple con­tact form to your Craft CMS site”
  • HTTP2 Serv­er Push — Auto­mat­i­cal­ly add HTTP2 Link head­ers for CSS, JS and image assets.”
  • Typogri­fy — Typogri­fy pret­ti­fies your web typog­ra­phy by pre­vent­ing ugly quotes and wid­ows’ and more”
  • Mix — Helper plu­g­in for Lar­avel Mix in Craft CMS templates.”
  • Dox­ter — Mark­down Edi­tor & Pars­er for Craft 3.”
  • Redi­rect Man­ag­er — Man­age 301 and 302 redi­rects with an easy to use user interface.”
  • Mail­gun — Mail­gun inte­gra­tion for Craft CMS.”
  • Pic Puller — Inte­grate Insta­gram into Craft CMS.”
  • Scout — Craft Scout pro­vides a sim­ple solu­tion for adding full-text search to your entries. Scout will auto­mat­i­cal­ly keep your search index­es in sync with your entries.”

Entries and Tem­plates #

For the most basic set­up, I need­ed a way to cre­ate and dis­play posts. To get start­ed, I went to Settings > Sections and cre­at­ed a new sec­tion called Posts. The sec­tion type was left as Channel and I updat­ed the Entry URI For­mat to {slug} and the tem­plate to posts/_entry.

Next, I need­ed to cre­ate a field for this sec­tion to store my post con­tent. Back we go to set­tings and then Fields to click New Field. I gave it the name of Post Content which gen­er­at­ed the han­dle postContent which I’ll use in the tem­plates to get the con­tent. After this, I set the field type as Doxster to use Markdown.

Final­ly, I go back to Settings > Sections and add an entry type to Posts. From here I used the drag and drop edi­tor to assign my postContent field to the section.

After adding some posts from my old set­up, it was then time to dig into the tem­plate. Remem­ber when I added the posts/_entry infor­ma­tion to the tem­plate field for the sec­tion? Craft maps this to your tem­plates direc­to­ry, so cre­at­ing the fold­er posts and the tem­plate _entry.twig inside it will work to dis­play a sin­gle post. At it’s most basic, it looks like this:

{% extends 'layouts/default' %}

{% block content %}
  <article>
    <h1>{{ entry.title | typogrify }}</h1>

    <time datetime="{{ entry.postDate.date }}">{{ entry.postDate | date('d M Y') }}</time>

      {{ entry.postContent | typogrify }}
  </article>
{% endblock %}

The layouts/default file is essen­tial­ly our html, head and body tags which sur­round our post tem­plate. With­in the body, you’ll have {% block content %}{% endblock %} which will sig­nal to Twig to drop the above in that spot.

Next up, I need­ed to cre­ate a list­ing of those posts on my home­page, so I cre­at­ed the file index.twig in the root of the tem­plates fold­er and added the following:

{% extends 'layouts/default' %}

{% block content %}

  {% paginate craft.entries.section('posts').limit(6) as pageInfo, pageEntries %}

  <ul>
  {% for entry in pageEntries %}
    <li>
          <h2>
            <a href="/{{ post.slug }}">{{ post.title | typogrify }}</a>
          </h2>
          <time datetime="{{ post.postDate.date }}">{{ post.postDate | date('d M Y') }}</time>

          <p>
                {{ post.postContent | striptags | slice(0, 360) | raw }}&hellip;
          </p>
    </li>
  {% endfor %}
  </ul>

  {% if pageInfo.prevUrl %}
        <a href="{{ pageInfo.prevUrl }}">Previous Page</a>
  {% endif %}

  {% if pageInfo.nextUrl %}
        <a href="{{ pageInfo.nextUrl }}">Next Page</a>
  {% endif %}

{% endblock %}

I added in some fil­ters like striptags, slice and raw for the post pre­view to dis­play a lit­tle excerpt from the post con­tent. With that, the basic site was up and running.

Lar­avel Mix #

Alright, the data is flow­ing through the tem­plates like the life-blood that it is. Next I need­ed to inject some styling into the site, pep­pered with some JavaScript for a few cool inter­ac­tive features.

You could argue that for some­thing sim­ple, web­pack just isn’t need­ed, and you’d be absolute­ly right. There’s noth­ing wrong with a sin­gle CSS file and a few script tags since that’s what it all boils down to any­way. I want­ed to use some fea­tures of JavaScript that need­ed some­thing extra for them to work across mul­ti­ple browsers. I felt it would be con­ducive to a more scal­able code­base when things get tacked-on down the line. I could be wrong, but I’m will­ing to give it a go.

Lar­avel Mix makes it easy to get start­ed in any web project, as seen in the instal­la­tion docs it’s not just for Laravel.

For exam­ple, if I want to have my JavaScript & Less tran­spiled I can do the fol­low­ing in my webpack.mix.js file:

const mix = require('laravel-mix')

mix
  .setPublicPath('web/')
    .js('web/src/js/main.js', 'assets/js')
    .less('web/src/less/app.less', 'assets/css')

It kin­da reminds me of Gulp a lit­tle bit, and you can always extend it fur­ther with plu­g­ins or oth­er con­fig­u­ra­tion options.

With that, I can run npm run watch to watch my files for changes. In my deploy­ment script I have npm run production for an opti­mised build.

Just Keep Swim­ming #

So with that, I had a Craft instal­la­tion set up with my posts, tem­plates were set up to dis­play them, and I had a build process for my assets.

There’s still more to do, such as fine-tun­ing for per­for­mance, which I’ll cov­er in a lat­er arti­cle. For now though, we have a pret­ty good start!

Read Part III: Fine Tuning