Getting started with AlchemyCMS

Often times we need jus a simple website, a few pages that can help us promote our business’ services. It’s main purpose in life is to improve the visibility of a business, and very often, with a minimum investment.

There are of course many types and variations of simple sites (also known as marketing sites), some smarter than others but the purpose of a marketing site remains the same; promote the products and/or services that a business has to offer.

So why am I talking about that here you ask… Well because there is an awesome tool to help you build sites like that or even sections like that in your Rails application. That tool is called AlchemyCMS and it’s awesome!

What is AlchemyCMS

First of all, let’s talk a bit about what a CMS is. CMS is the abbreviation for Content Management System which is a fancy name for saying: “a website designed to be updated by people who do not know how to write code”. That means that the content of a website can be easily changed by someone who is not concerned with the technical aspects, usually a person responsible in the marketing department. A popular example of a CMS is Wordpress which is mostly used for building blogs, but a CMS is not limited to building blogs. You can build all sorts of content with a CMS, for example AboutUs pages or ContactUs, Services, Terms and Conditions, Privacy Policy, etc. Almost any page that is composed of mostly static content.

Now that the terminology is out of the way, let’s see how AlchemyCMS fits into this picture.

In my opinion AlchemyCMS’s selling point is the fact that it adds just enough flexibility to the end user (the marketing person that uses the CMS) to add or update content while leaving all the technical details to the developer. In other words, it saves the developer the most time while giving the marketing department all the flexibility it needs to add and update the website’s content.

The way it does that is by splitting up the content into reusable pieces that you can assemble to build pages full of content. Each reusable piece of editable content is set up by the developer and added to a pool of elements from where the user can pick and choose. That way the end user cannot and should not be concerned with the structure and design of the website, he’s only allowed to edit the content while the rest is handled by the developer and designer. I really think that is a very nice concept.

Getting started with AlchemyCMS

We now know what AlchemyCMS is so it’s time to see it in action. For that we’re going to install the gem and create a new alchemy site from scratch.

Installing the gem

Installing AlchemyCMS on your system is simply a matter of installing the AlchemyCMS gem. I’m also going to separate the gems from my global gemset by creating a dedicated gemset (using rvm) just for this project.

The alchemy_cms gem provides a nice application generator which creates a new rails app and adds the alchemy_cms gem and it’s dependencies to the Gemfile.

rvm use ruby-2.1.2@alchemytest --create
gem install alchemy_cms
alchemy new alchemy_test
cd alchemy_test

Setting everything up

There’s not much else you need to do to get AlchemyCMS up and running, the generator does all of the work for you. One last step is to fire up the rails server with bin/rails server and load the website (at http://localhost:3000/admin).

You will see a welcoming message and a form to create your first user.

Next up, you will be prompted to create your language tree (the English tree in my case). So just hit the “Create English as a new language tree” button and you’re done.

Congratulations, you’ve just installed and set up AlchemyCMS. Here’s where the actual fun begins :)

You should see a dashboard like the one in the screenshot below where you can add and edit your default content elements. This is what the end user will see and use.

Core concepts

Before you can go ahead and start configuring what the user can do with the CMS, you need to understand a few of the core concepts that AlchemyCMS uses as they are not intuitive.

The way AlchemyCMS works is it splits the content pages into smaller and smaller components and then it lets the end user assemble them to build the final page. These components are (from top to bottom): Layouts, Cells, Elements and Essences. Together they are used to construct a Page.

Layouts

Layouts are at the top of the hierarchy. A layout is made up of smaller components like cells and elements (which we’ll talk about in a minute). Layouts offer a way to group those smaller components in a template that you can reuse to define your pages.

For example you can define a blog listing page from a blog listing layout to have a sidebar on the right that contains a subscription widget while the left column holds multiple blog articles (see the example image).

Cells

Cells are (optional) structural containers that describe where the elements could be placed on the layout. They are also unique in the sense that you cannot place the same cell multiple times on the same layout. So, imagine a cell to be the sidebar for example, or maybe the left, middle and right columns. The important distinction between cells and elements is that cells define structure, not content.

I had some trouble understanding why you would need to use cells at first but as it turns out, you can limit the elements that go into a cell so basically you can have a sidebar cell that only accepts a form element and nothing else. That it’s a nice way of preventing people from adding elements all over the place.

Elements

Elements are not quite where the content goes, they are containers for essences. They are reusable components that you can place into other containers like layouts and/or cells. You don’t have to add your elements inside cells but you can.

An example of element can be a form that you can place in a sidebar cell or maybe a blog post summary that you can place multiple times on a page.

Essences

The smallest piece of content and the only one that is editable by the end user is called an essence and it is used to create elements. Essences are input fields, content areas, images or anything else that represents editable content. AlchemyCMS provides a few out of the box but you can also add your own if you find that the default ones are not sufficient.

Pages

A page is a real page, something that visitors to your website can see. It has a layout which describes how the elements will fit on the page and of course the bulk of it is made up of cells and elements.

Pages also have a few properties that you can specify, like visibility on the global navigation (if you want the page to be a part of the menu bar), SEO tags like description and keywords.

One gotcha is that pages are structured in a tree like fashion which means you can only have one root page (per site and language) and all the other pages you create will be descendants of that root page.

Create your first element

The first thing you’ll want to do after playing for five minutes with the default AlchemyCMS options is going to be creating new elements so you can build your own content pages. That’s very easy to do in AlchemyCMS. You need to go to the config/alchemy/elements.yml file and add your own element in there.

When you’re done describing your new content element, you need to tell AlchemyCMS to generate the necessary files. It will create two files, one it’s the view (the html that is rendered) and the other is the edit form (the one that is used to edit the content of the element).

So let’s build an example element for a blog post. We open up config/alchemy/elements.yml and add the following snippet to the end of the file.

- name: blog_post
  contents:
  - name: blog_post_title
    type: EssenceText
  - name: blog_post_image
    type: EssencePicture
  - name: blog_post_content
    type: EssenceRichtext

Now, you need to run rails g alchemy:elements -s to generate the view and edit files. I’ve added the -s option to skip existing files, otherwise it asks you if you want to overwrite them. You should see something like the following:

$ rails g alchemy:elements -s
       exist  app/views/alchemy/elements
        skip  app/views/alchemy/elements/_article_editor.html.erb
        skip  app/views/alchemy/elements/_article_view.html.erb
      create  app/views/alchemy/elements/_blog_post_editor.html.erb
      create  app/views/alchemy/elements/_blog_post_view.html.erb

That’s all good but it’s not enough for you too be able to add your blog post element to the page just yet. That is because the default page layout has a constraint, it only allows article elements on the page. So you need to edit that constraint and add the blog post element to the allowed array.

So open up config/alchemy/page_layouts.yml and change the contents of the file to look like the following.

- name: index
  unique: true
  elements: [article, blog_post]
  autogenerate: [article]

Save the config/alchemy/page_layouts.yml file and restart your rails server. Now reload your AlchemyCMS dashboard and try adding a new element (see the screenshot).

Conclusion

I’m looking forward to using AlchemyCMS in my future projects because of it’s awesome architecture and flexibility. I no longer have to worry about how to restrict users from doing unwanted/unexpected things.

I’ve barely scratched the surface here of what AlchemyCMS can do so let me know if you’ve tried AlchemyCMS and what your experiences were with it. Also drop me a line if you like to learn more about it in future articles.