1. Technology
You can opt-out at any time. Please refer to our privacy policy for contact information.

Step 2: Integrating a Wordpress Theme

By

Adding Some Style
Step 2: Integrating a Wordpress Theme

Web design is a big topic, one that I won't even attempt to cover. If you're interested in web design, see The About.com Guide to Web Design. Instead of attempting to cover HTML document structure and CSS and all that, we're going to take the easy way out: we're going to adapt a Wordpress theme to use in our blog to spruce up the rather spartan pages the scaffold generator gave us.

Wordpress is an extremely popular blogging engine written in PHP. There are thousands and thousands of Wordpress blogs. And this means there's a very large ecosystem for Wordpress plugins and, lucky for us, themes. But these aren't drop-in add-ons for your blog, you'll have to adapt the theme to work with Ruby on Rails. This is not difficult though.

The finished code for this tutorial can be found on GitHub and the complete code (in whatever state that might be) in the main repository. In order to clone this specific version of the project, first clone the project, then switch to the tag called v0.2.


$ git clone https://github.com/mmorin/blogtutorial.git
…
$ cd blogtutorial
$ git checkout v0.2

And as usual, before attempting any task I create a new git branch.


$ git checkout -b wordpress_theme
Switched to a new branch 'wordpress_theme'

Picking a Theme

Simply Googling for free wordpress themes brings up so many choices it's dizzying. There are also paid themes, and many artists that will make themes on commission. It's also worth noting that many of these themes have very permissive licenses, if this is an issue for you. The included readme files usually elaborate on the license. For this article, we'll choose the Liquorice theme by Nudge Design, but any theme you choose will have the same structure, so feel free to choose one you like.

If you download the theme, you'll find a zip file with CSS, PHP and image files. If you don't know PHP, that's OK, we're going to read around it. The files we're really interested here are:

  • header.php - This, in a Wordpress theme, represents everything on the page from the beginning of the document all the way down to the content. This includes the HTML head tags, body tag and the header displayed at the top of every page.
  • single.php - This is where a single blog post is formatted. In most themes this is just a few divs for the title of the post, its author and then the blog post body.
  • sidebar.php - This is the component of the page to the right (usually) of the blog. Here we'll eventually be putting a list of links, login and log out, etc.
  • footer.php - The bottom of the page. This is both the footer of the page (the copyright notice, etc) and the end of the HTML document.

What do we do with all these? We need the structure of the document in order for it to play nice with the CSS from the theme. For that, we need to know what divs are nested in each other, what classes and IDs they have, and what tags generally go inside them. Remember that CSS doesn't only operate on classes and IDs, the CSS selectors are very diverse. They can say things like "the H1 tag inside a tag with the class header," so pay attention not only to the divs, but also the general structure of the tags within them.

Installing the CSS and Images

It's time to install the CSS now, and that means dealing with the asset pipeline. The asset pipeline is a relatively new addition to Ruby on Rails. It's meant to pre-compile all your CSS and Javascript files into single files which means CSS or Javascript take a single request and can be parsed faster and makes your site run that much faster. Assets are stored in app/assets.

If you open app/assets/stylesheets/application.css, you'll see a file with comments explaining a little bit about the asset pipeline, and these two lines.


 *= require_self
 *= require_tree .

These two lines signal the asset pipeline to include all of the files in the current directory (in app/assets/stylesheets/ in the output CSS file. Any CSS file in there will automatically be included in the output CSS. In fact, you can see a few other files there already, including a scaffolds.css.scss file, something we'll need to edit in a moment. So, we copy our CSS file into this directory and give it a meaningful name.


$ cp ~/tmp/liquorice/style.css app/assets/stylesheets/liquorice.css

And now the images. These should go into app/assets/images.


$ cp ~/tmp/liquorice/images/* app/assets/images/

And now we need to make a small modification to the CSS file itself. If you open it, you'll notice that it expects to serve images from an images directory relative to the directory the CSS file is in. Since from the client's perspective the CSS file is in /assets/stylesheet.css and images are in /assets/image.png, this is a problem. This is a simple search and replace action though, simply replace all instances of the string images/ with /assets/. The "find and replace" feature of your text editor should help you here. An example of what the new path should look like is below.


body {
	background: url(/assets/bg-paper.jpg) repeat ; 
	color:#121212; 
…

A New Root

It's time to put in a root route in config/routes.rb. We want this to point to 'posts#index', so it'll display a list of blog posts. This is as simple as adding the following line.


Blogtutorial::Application.routes.draw do
  resources :posts
  
  root :to => 'posts#index'

And as always, if you're not sure or want to confirm a route, you can run the rake routes command and examine the output. Also, delete the public/index.html file, public files are served before any routes so this will prevent the root route from functioning.


$ rm public/index.html

A New Structure

It's time to extract the structure of the HTML from the PHP files as discussed above. Most of the work here goes into app/views/layout/application.html.erb. This is the application-wide layout, it's common to all pages (by default, it can be overridden) and it's where everything except the content itself should go. Also, since every theme has a different page structure, this part is really playing it by ear. Below is the structure the Liquorice theme wants, a different theme will most likely want something completely different. I've highlighted a few lines we'll talk about below.


<!DOCTYPE html>
<html>
<head>
<title>Blog</title>
<%= stylesheet_link_tag "application", :media => "all" %>
<link href='http://fonts.googleapis.com/css?family=Lobster&subset=latin' rel='stylesheet' type='text/css'>

<%= javascript_include_tag "application" %>
<%= csrf_meta_tags %>
</head>
<body>
<div id="canvas">
<div id="header-wrap">
<div id="header">
<h1 id="site-title"><span><%= link_to 'Blog', :root %></span></h1>
</div>
</div>

<div id="primaryContent">
<p class="notice"><%= notice %></p>
<p class="alert"><%= alert %></p>

<%= yield %>
</div>

<div id="secondaryContent">

</div>

<div id="footer">

</div>
</div>
</body>
</html>

First, you'll notice that we didn't change the stylesheet_include_tag from the default, this is because the asset pipeline handles this for us. Our view doesn't need to know what stylesheets it wants, it just gets whatever the asset pipeline hands it. The second line of interest is the "Rock Lobster" font we'll need for the header.

If you start up the server and look at the blog now, it'll look very different. Styling even. Still not formatted correctly though, the index page is just a table of blog posts and it doesn't look like a blog at all. We'll take care of that in the next article when we work on the views, but for now, we need to clean up a bit of CSS left by the scaffold generator. We do want a few things from app/assets/stylesheets/scaffolds.css.scss, but some of it interferes with the wordpress theme. So comment out or delete any block that does not begin with . or # (CSS selectors for ID and class), the rest of the things like styles on body and links interfere, and should be removed. The file should now look like this.


#notice {
  color: green;
}

.field_with_errors {
  padding: 2px;
  background-color: red;
  display: table;
}

#error_explanation {
  width: 450px;
  border: 2px solid red;
  padding: 7px;
  padding-bottom: 0;
  margin-bottom: 20px;
  background-color: #f0f0f0;
  h2 {
    text-align: left;
    font-weight: bold;
    padding: 5px 5px 5px 15px;
    font-size: 12px;
    margin: -7px;
    margin-bottom: 0px;
    background-color: #c00;
    color: #fff;
  }
  ul li {
    font-size: 12px;
    list-style: square;
  }
}

Merge

We're finished with this task, go back to the master branch and merge the branch to master.


$ git checkout master
$ git merge wordpress_theme
  1. About.com
  2. Technology
  3. Ruby
  4. Ruby on Rails
  5. Ruby on Rails 3 Tutorials
  6. A Full Featured Blog
  7. Step 2: Integrating a Wordpress Theme

©2014 About.com. All rights reserved.