Butter CMS for Rails

www.buttercms.com

**Why Butter?**

Butter makes setting up a professional company blog on Rails insanely easy. It’s built for developers to save us from hosting, DB setup, themeing, maintaining yet another Wordpress install. It’s designed to be quickly integrated to an existing Rails project.

Butter provides a user friendly blogging UI, hosted on buttercms.com, and exposes content created via an API.

This package provides a Rails Engine that interacts with the Butter API to get you up and running in seconds.

Installation

Add buttercms gem to your Gemfile and install it.

.. code-block

ruby

# In Gemfile
gem 'buttercms'

.. code-block

bash

$ gem install buttercms

Now run the Butter install generator. This will setup a ‘butter.rb` initializer, which provides many customization options, and defines a route in `config/routes.rb`. By default, your blog will live at “/blog”.

.. code-block

bash

$ rails g buttercms:install

Grab your API token from buttercms.com/api_token and throw it in ‘config/initializers/butter.rb` or set it on your ENV like so `$ export BUTTER_TOKEN=yourtokenhere“`

That’s it! You’ve now got a blog running natively in your Rails project.

Check it out: localhost:3000/blog

Log into buttercms.com/ to start blogging!

Customizing your blog

Open ‘initializers/butter.rb` to see the full set of options available for customizing your blog.

Specify the Blog Layout

---

We’ve provided a default layout but we expect you’ll want the blog to appear your branded layout so we’ve made this as simple as defining ‘config.layout` in `initializers/butter.rb`

.. code

ruby

# In initializers/butter.rb
config.layout = "<your_blog_layout>"

Note that an ideal layout simply defines the header and footer for the page and ‘<%= yields %>` the main body. Restart the server and go to localhost:3000/blog and you’ll see your new branded blog!

Customizing the view templates

---

You can customize any view of your blog. Here is full list of page types + settings:

.. code

ruby

# In initializers/butter.rb
config.home_template = "blog/home"
config.post_template = "blog/post"
config.author_template = "blog/author"
config.category_template = "blog/category"

We recommend putting any custom templates in ‘views/blog/<template>.html.erb`

Below is a specific example of how to customize your blog post view to include Discus comments.

Add comments to blog post template

---

If you want to customize the blog post template (for example to add ‘Disqus <disqus.com/>`_ comments at the bottom), it’s simple:

First create your template: ‘views/blog/post.html.erb`

.. code

html

<div class="post">
    <h2 class="title">
        <%= @post['title'] %>
    </h2>

    <p class="meta">
    Posted by 
    <%= link_to("#{@post['author']['first_name']} #{@post['author']['last_name']}", blog_author_path(:author_slug => @post['author']['slug'])) %>
     on <%= @post['created'] %>

    <% @post['categories'].each do |category| %>
    <span class="label">
    <%= link_to(category['name'], blog_category_path(:category_slug => category['slug'])) %>
    </span>
    <% end %>
    </p>

    <p class="body">
        <%= @post['body'].html_safe %>
    </p>
</div>

<hr>

<!-- Paste your Disqus embed code here --->

Then tell Butter about this template:

.. code

ruby

# In initializers/butter.rb
config.post_template = "blog/post"

That’s it. Reload the server and you’ll see your new customized blog post with comments!

Overview of key blog views

The Butter gem implements several actions for your blog and provides a default view+layout for each of them. The gem also talks to an API that resides on buttercms.com to retrieve your blog content and makes that content easily available in each view.

Here’s an overview each action+view and the available content:

home: /blog

---

.. code

ruby

@next_page # Integer used for blog post pagination (i.e. 2)
@previous_page # Integer used for blog post pagination (i.e. 1)
@recent_posts # Array of blog posts

post: /blog/:post-slug

---

.. code

ruby

@post # All content for a blog post

=begin
@post has the following structure
"url": "https://buttercms.com/blog/the-state-of-company-blogs",
"created": "05/16/2015",
"author": {
"first_name": "Butter",
"last_name": "Cms",
"slug": "butter-cms"
},
"categories": [
{
"name": "blogs",
"slug": "blogs"
},
{
"name": "butter",
"slug": "butter"
}
],
"slug": "the-state-of-company-blogs",
"title": "The State of Company Blogs",
"body": "<h3>The problem</h3><p>Countless people and essentially every...</p>",
"summary": <h3>The problem</h3><p>Countless people and essentially...</p>,
"status": "published"
=end

author: /blog/author/:author-slug

---

.. code

ruby

@first_name # First name of author
@last_name # Last name of author
@recent_posts # Array of blog posts

category: /blog/category/:category-slug

---

.. code

ruby

@name # Name of the category
@recent_posts # Array of blog posts