Best Practice: Create a blog template

A blog is an appropriate way to present information about formal and informal events or extraordinary experiences. In this guide you will learn how to:

  • Define blog layout and elements
  • Integration in your existing application

Conceptual page and content structuring

Imagine you like to have a simple blog template on your website. First of all as mentioned in The Alchemy approach you should identify required components in your blog layout. Common components are a headline, a blog post itself and sidebar blocks for category overview and featured posts.

Following the steps you will create blog template according to Foundation Zurb . (© ZURB, Inc)

We will build this template using the Blog sample.

1 Concept and structure

Visit the Blog sample page and have a deep look at the layout.

Let us start to divide the template. We can identify the following page elements:

  • blog post (multiple) contains title, date, author, image and text
  • categories block contains list of categories
  • featured block contains text block with link to favourite blog post

1.1 Prerequisites

At the beginning some preparation is required. First of all, follow these instruction provided by Zurb to Add Foundation to your Rails app.

Hence the necessary prepations are completed.

2 Define elements

First of all we define the elements we need in config/alchemy/elements.yml The individual page elements(see 1. Concept and structure) could be considered as an element.

2.1 Blog title

The blog should have a unique title. The title element contains a title and a text which represents a description or motto. In both cases we choose an EssenceText, due to the fact that the title and the textwill contain simple text.

The default attribut provides the preset value, if the user didn’t specify a motto or description (in Alchemys backend).


- name: blog_title
  unique: true
  contents:
  - name: title
    type: EssenceText
    default: Blog
  - name: text
    type: EssenceText
    default: This is my blog. It's awesome.

2.2 Blog post

A ‘blog post’ element has a title, date, author, image and text.

The title is represented by blog_post_title. Its just a text, so we took EssenceText as type. Below settings we use linkable: true, because the user should be able to choose a link for the title of the blog post.

The meta data like author and creation date corresponds to ‘blog_post_meta’.

The blog_post_intro_text text as well as the main content blog_post_content get the type EssenceRichtext, since the user likes to add multiline paragraphs.

The blog_post_image is of type EssencePicture. This will empower the user to add an image.


- name: blog_post
  contents:
  - name: blog_post_title
    type: EssenceText
    default: Blog Post Title
    settings:
      linkable: true
  - name: blog_post_meta
    type: EssenceText
    default: "Written by John Smith on August 12, 2012"
  - name: blog_post_intro_text
    type: EssenceRichtext
  - name: blog_post_image
    type: EssencePicture
  - name: blog_post_content
    type: EssenceRichtext

2.3 Categories Block

The ‘categories block’ has a headline and a list of available categories.

The categories_headline is represented by an EssenceText. In the backend the user should be able to add categories easily and dynamically. Thats the reason why we choose the available_contents option.

Its important to copy the definition of category below contents to available_contents. Besides this, we also make the EssenceText deletable and linkable via settings.


- name: categories_block
  contents:
  - name: categories_headline
    type: EssenceText
    default: Categories
  - name: category
    type: EssenceText
    settings:
      deleteable: true
      linkable: true
  available_contents:
  - name: category
    type: EssenceText
    settings:
      deletable: true
      linkable: true

The ‘featured block’ with a headline, text and a link.


- name: featured
  unique: true
  contents:
  - name: featured_headline
    type: EssenceText
    default: "Featured"
  - name: featured_text
    type: EssenceRichtext
  - name: featured_link
    type: EssenceText
    settings:
      linkable: true

Instead of EssenceText you could alternativly use EssenceLink for ‘featured_link’.

3 Define blog page layout

After the definition of the elements, you we will continue with the defintion of an appropriate page layout. Page layout are specified in config/alchemy/page_layouts.yml.

Add a new page layout for your blog template:


- name: blog
  elements: [blog_title, blog_post, categories_block, featured]
  autogenerate: [blog_title]

The autogenerate attribute allows to define elements which will be generated automatically, when the user creates a new page in backend.

4 Generate and customize the partials

The command


$ rails g alchemy:elements --skip

creates the view and editor partial according to the element definition in the elements.yml.

The partials are stored in app/views/alchemy/elements/.

e.g. the view partial for ‘blog_post’- element: _blog_post_view.html.erb and editor partial: _blog_post_editor.html.erb

4.1 Customize the partials

In order to adapt the output of the elements you have to change the view partial. The command above generates default partials. The _blog_post_view.html.erb might look like this:


<%- cache(element) do -%>
  <%= element_view_for(element) do |el| -%>
    <div class="blog_post_title">
      <%= el.render :blog_post_title %>
    </div>
    <div class="blog_post_meta">
      <%= el.render :blog_post_meta %>
    </div>
    <div class="blog_post_intro_text">
      <%= el.render :blog_post_intro_text %>
    </div>
    <div class="blog_post_image">
      <%= el.render :blog_post_image %>
    </div>
    <div class="blog_post_content">
      <%= el.render :blog_post_content %>
    </div>
  <%- end -%>
<%- end -%>

The blog post should match with the layout of the blog page in general, therefore we edit the view partial:


<%- cache(element) do -%>
  <%= element_view_for(element) do |el| -%>
    <article>
      <h3>
        <%= el.render :blog_post_title %>
      </h3>
      <h6>
        <%= el.render :blog_post_meta %>
      </h6>
      <div class="row">
        <div class="large-6 columns">
          <p>
            <%= el.render :blog_post_intro_text %>
          </p>
        </div>
        <div class="large-6 columns">
          <%= el.render :blog_post_image %>
        </div>
      </div>
      <p>
        <%= el.render :blog_post_content %>
      </p>
    </article>
    <hr/>
  <%- end -%>
<%- end -%>

The editor partial is used for the backend, so we keep this file untouched. Feel feel to edit this partial if you like.

For the remaining elements replace the content of the correspondig view partials with the following code snippets:

4.2 _blog_title_view.html.erb


<%- cache(element) do -%>
  <%= element_view_for(element, tag: 'h1') do |el| -%>
  <%= el.render :title %> <small><%= el.render :text %></small>
  <%- end -%>
<%- end -%>

4.3 _categories_block_view.html.erb


<%- cache(element) do -%>
  <%= element_view_for(element) do |el| -%>
  <h5>
    <%= el.render :categories_headline %>
  </h5>
    <% element.all_contents_by_name('category').each do |content| %>
    <p>
      <%= render_essence_view(content) %>
    </p>
    <%- end -%>
  <%- end -%>
<%- end -%>

<%- cache(element) do -%>
  <%= element_view_for(element) do |el| -%>
    <h5>
      <%= el.render :featured_headline %>
    </h5>
    <p>
      <%= el.render :featured_text %>
    </p>
    <p>
      <%= el.render :featured_link %>
    </p>
  <%- end -%>
<%- end -%>

5 Embed the elements into your page layout

Finally you have to integrate your elements into the page layout.

5.1 Create new page layout view

Create a new file called _blog.html.erb in app/views/alchemy/page_layouts and copy the plain html code from Foundation Zurb Blog Template Raw .

5.2 Edit blog page layout view

In app/views/alchemy/page_layouts/_blog.html search for (inside ‘Nav Bar’ comment)


<h1>Blog <small>This is my blog. It's awesome.</small></h1>

and replace with:


<%= render_elements only: 'blog_title' %>

The blog_title set in the backend is now visible in the blog page layout context.

Inside the commented ‘Main Blog Content’ replace the whole content of <div class="large-9 columns" role="content">

with


<%= render_elements only: 'blog_post' %>

to embed the blog_post elements into the page layout view.

Inside ‘Sidebar’ comment replace


<h5>Categories</h5>
<ul class="side-nav">
  <li><a href="#">News</a></li>
  <li><a href="#">Code</a></li>
  <li><a href="#">Design</a></li>
  <li><a href="#">Fun</a></li>
  <li><a href="#">Weasels</a></li>
</ul>

with


<%= render_elements only: 'categories_block'  %>

and replace the content of <div class="panel"> with


<%= render_elements only: 'featured' %>

Now you can run


$ rails server

to start the server.