Following on from my broader world view on future of the CMS, I thought it would be helpful to take a short, simple and practical stroll through how all this starts to work together.
So, I'm going to dive right in. Our case in point will be the current Hammer website, whereby we will update our static Hammer Template Gallery section, so that instead of rendering Template items from the hardcoded source html, we're going to pull them from our Content as a Service and build them statically.
Even with the use of the Hammer clever tags, the markup is weighty and hard to read. It gets even bigger once it's compiled by Hammer, you'll be familiar with that if you ever downloaded an HTML theme from Themeforest!
We're going to change this, but first let's consider what we need to do. Each Template is listed and displayed in the grid layout. For now, we'll just stick with replicating this, an index of Templates driven by our content API from Contentful.
We can add specific detail view pages later if we so choose and will likely be the subject of a follow on tutorial.
Let's head over to Contentful and get our content setup.
1. Sign in or register for an account and Create a Space.
2. Now we need to add a Content Type. Click the blue button. Create a content type called "Template"
3. We can now add some fields to our Template. These are the attributes that describe our Template, things like the name, description or the downloadable template file itself.
4. Here's our first couple of fields added. We added a name as a short text field, and a description as a long text field. There's lot's of other field types we can add.
5. As you can see here, we now have all the basic attributes in place for creating our Template.
6. So now if you head back to the Entries area, you can create your first Template entry.
7. And when you're done adding all the templates, you're ready to head back to Hammer to setup your code.
In order to use the contentful integration in Hammer for Mac (while it's in BETA), you need to download the compiler version and install it. You can do this easily by using the following command in your Terminal.
Note: Check your ruby version first before running it, you should be on system ruby (2.0.0)
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/RiotHQ/hammer-gem/contentful-gem/scripts/update.rb)"
You need to add a file to the root of your Hammer project, called (you guessed it) "hammer.json". This simple json file will handle the basic configuration of your Contentful integration. Here's what ours would look like for this project.
Finally, we need to update our view so that it will use the Contentful data at Build time to generate our HTML. We're going to make this even better, by moving our current HTML template to the Slim templating language, which Hammer now supports.
As you can now see, it's much neater, easier to read, concise and gives us access to useful ruby helpers in our slim views.
So, aside from shrinking down the template code, we've replaced that long list of <article> elements with this code:
- for template in contentful.templates <!-- @include _template -->
That's right, we've then taken our individual template out into an included partial, which looks like this.
Now, best thing is to enter the Hammer for Mac app and cmd+R (or hit Rebuild button) to refresh the cache and Build your site.
Your page should now display all of the entries from your Contentful space, rendered into your Templates.
You could export the Build folder and upload it to Forge now, but that wouldn't be very good. Who wants to do that after each change to the template or with the addition of a new Entry? No-one, right? So instead, let's go through the one-time setup process for a continuous integration / deployment workflow, using Forge, Github, our new Hammer Cloud build service and Contentful.
1. Commit and Push your site to Github. Create a new repository if you need to.
If you're new to Git and Github, I recommend reading these 2 articles:
And also, taking this very short interactive course by Codeschool.
2. Sign into your Forge account and create your site.
3. Connect your Forge site to your Github repository
Select the root folder of your hammer project (not the Build folder, if you've also committed that to the repo - actually it's best practise not to commit that to the repo as it'll take longer to upload and build, add it to your .gitignore file).
Another tip is to select a deployment branch, which could be master or if you are used to using Github pages, you could select a "pages" branch or for less service-specific, call it "production", "staging" etc. Up to you, just to say, you don't have to use master.
4. Enable Auto-sync for Github
5. Enable Hammer Cloud Service
Head to your Forge project Settings.
Enable the Hammer Cloud service
It's best to test the successful integration, by doing an initial Deployment of your site using the "Deploy from Github" button in the Site Version view.
6. Grab your Deployment Webhook from your Forge site settings
You'll want to add a couple of additional params to your Webhook url.
This will prevent Forge from creating a new version for each content change, which can easily and quickly fill up your Forge deployment timeline. Only changes to your code from github will cause a new Version in your timeline.
We did some tests and found that a 5 second delay on the webhook gave Contentful enough time to complete their response, before Forge commences your build using the Hammer cloud service.
So, your entire webhook will look like this:
7. Head over to Contentful and create a new Webhook.
Login to your Contentful account, and make sure you are in the correct Space.
Go to Settings > Webhooks.
Click "+ New Webhook"
Add your webhook url from the previous step in the URL field. Leave the others blank.
Try it out!
Now, whenever you update your github repository - save if you want to change your template code or styles, add new content types and new templates etc. it will automatically trigger a rebuild and redeployment of your Forge site, creating a new version so you can easily roll-back if things go wrong.
You could then use our Outgoing Webhooks to ping your Slack Team channel or integrate through Zapier to send an email - as you like - with information about your latest site update.
Whenever you add or save a piece of content, an Entry on Contentful, we'll rebuild and redeploy your site on the current version, and in a matter of a few seconds your fresh content will be served via our global CDN to your users browsers.
In the next tutorial on this subject, I'm going to walk you through exactly how we recently built our new Nuwe website using this exact process and a little more complex content models, templates and options. It's just getting started.