In almost every web app project that we do, we end up needing to create some informational pages, such as a home page, features page, or an FAQ. Deciding where and how to build these pages always seems to be a double edged sword. One option is to build them directly into the Rails app. Doing it this way allows us to develop the page in our local development environment, making it faster to develop and ensuring the code is tracked in version control. But it presents a major downside in that our clients cannot edit the copy on the page at will. Any changes they want to make need to go through our development team -- obviously an inefficient setup.

The second option is to build them as traditional CMS pages, so that they can be edited on the production server. This solves the editing problem, but it introduces other issues. Developing the HTML and CSS for the page in the CMS editor is slow and cumbersome. Should you develop the page locally, on staging, or on the production server? How do you move the page content between these environments? You also introduce the potential for someone to accidentally break the HTML/CSS for a page when they are editing the content. When that happens, you have to dig up a backup to restore the content, since the page isn't in version control.

To help solve these issues and preserve the best of both options, we built a concept called text snippets into our open source Rails CMS, Storytime. In this post, I'm going to walk through the process of building a page using text snippets.

A mockup of the page we're building

To start, we create a normal page in our Rails app that is hosting the Storytime instance. You can either use something like PagesController, or use a gem like High Voltage. In this page, we build out the HTML structure of the page:

# app/views/pages/home.html.erb

<div class="row">
  <div class="col-md-8">
    <h1>Crowdsourced Forecasting</h1>
    <h2>Tap the wisdom of your crowd.</h2>
    <div class="explanation-copy">
       Use Inkling Markets to capture hundreds or thousands of forecasts about important business events and metrics, resulting in a probabilistic outcome. It’s like your own internal weather report.
    </div>
  </div>

  <div class="col-md-4">
    <%= image_tag "screenshot.png" %>
  </div>
</div>

Now, let's take this page and swap the copy to use text snippets:

# app/views/pages/home.html.erb
<div class="row">
  <div class="col-md-8">
    <h1><%= Storytime.snippet("header-text") %></h1>
    <h2><%= Storytime.snippet("sub-header-text") %></h2>
    <div class="explanation-copy">
       <%= Storytime.snippet("explanation-text") %>
    </div>
  </div>

  <div class="col-md-4">
    <%= image_tag "screenshot.png" %>
  </div>
</div>

And then add the text snippets to Storytime:

Now, the page's html and css are part of our normal app. They're checked into version control and can be easily and consistently deployed across environments, but we've preserved the ability of non-technical users to edit the page's copy as needed. 

If you have any questions about using text snippets or Storytime, let us know on Twitter: @flyoverworks or @bcroesch