A CommunityEngine Tutorial: Building a Social Site (CommunityEngine - A Social Networking Plugin for Ruby on Rails)

A CommunityEngine Tutorial: Building a Social Site

UPDATE: the installation section of this tutorial is out of date, please refer to the README included in the CE source instead. The sections that deal with customizing CE are still applicable.

In this tutorial I'm going to describe the steps to building a social Web site using CommunityEngine (CE). I'll go through setting up your application, installing the CE plugin, and customizing the application using a theme. The source code for this sample application is hosted on GitHub (here). This tutorial assumes basic knowledge of Rails, the console, git, and some CSS.

Requirements

Rails 2.1.0
git (a distributed source-control application)
The gems required for CE, listed here

Setting up your application & Installing the CE plugin

You'll need to create a new rails application. I'm going to call this application 'ce-sample-app'. From the console, type:

rails ce-sample-app
cd ce-sample-app

Next, we'll need to install the Engines plugin:

script/plugin install git://github.com/lazyatom/engines.git

Now we need to get the CommunityEngine plugin installed:

script/plugin install git://github.com/bborn/communityengine.git

Unfortunately for now, the rails plugin install command creates the CE plugin directory with the name 'communityengine'. We need it to have an underscore, so:

mv vendor/plugins/communityengine vendor/plugins/community_engine

We're going to use the sqlite3 database, so we don't need to make any changes to our default config/database.yml file. We do, however, need to delete the public/index.html file that is generated by Rails:

rm public/index.html

Now we need to modify the generated config/environment.rb, adding the lines that make CommunityEngine go:

    ## environment.rb should look something like this:
    ===============================================================
    RAILS_GEM_VERSION = '2.1' unless defined? RAILS_GEM_VERSION
    require File.join(File.dirname(__FILE__), 'boot')
    require File.join(File.dirname(__FILE__), '../vendor/plugins/engines/boot')
 
    Rails::Initializer.run do |config|
      config.plugins = [:engines, :community_engine, :white_list, :all]
      config.plugin_paths += ["#{RAILS_ROOT}/vendor/plugins/community_engine/engine_plugins"]
  
      ... default rails stuff here ...
    end
    # Include your application configuration below
    require "#{RAILS_ROOT}/vendor/plugins/community_engine/engine_config/boot.rb"

We also need to add the APP_URL constant to our environments, so CE knows what the base application URL will be. In config/environments/development.rb and config/environments/test.rb, put at the bottom:

APP_URL = "http://localhost:3000"

If you'll be deploying this to a production server, in config/environments./production.rb, put at the bottom:

APP_URL = "http://www.yourdomain.com"

Now we're ready to add CE's routes to the blank Rails application. In config/routes.rb, add:

map.from_plugin :community_engine

at the bottom, before the default Rails routes, which should take lowest priority. If you have any existing routes in your application, make sure the CE routes come after those.

Almost done now. In the console, run:

script/generate plugin_migration
rake db:migrate

This will generate the CommunityEngine migrations, and migrate the database to the latest version.

Finally, let's make sure our tests are passing:

rake db:test:prepare
rake community_engine:test

If they all pass, we can get started! Start your local server:

ruby script/server

Check out your fresh community site by visiting http://localhost:3000 in your browser! You'll see this:

Customizing Your CommunityEngine Install

Before we start, I should point out that you now have a fully functioning community site, complete with user profiles, blogs, friend requests, activity feeds, and so much more. From here, all you need to do is customize the look and feel of the application, and make any additions you want for your particular situation.

First, let's load some fixture data:

rake community_engine:db:fixtures:load

(If you refresh your browser, you'll see the app looks a little nicer now with data in it).

Next we're going to create a config/application.yml file to override CE's default one. In config/application.yml, create a new file with the following in it:

community_name: "CE Sample App"
community_tagline: "A Sample Community using CommunityEngine"
community_description: "Tutorials are hard work!"
support_email: "support@example.com"
meta_description: 'A description of your community for use in META tags.'
meta_keywords: 'keywords for use in META tags'

I won't bother explaining each of these; they are application level configuration variables that CE uses throughout the site. Restart your server, refresh your browser, and you'll see your changes have taken effect.

Other application.yml variables can be modified (look in vendor/plugins/community_engine/engine_config/application.yml to get started), including the dimensions of resized photo thumbnails, and the storage backend for uploaded photos (Amazon S3 is supported, file system is used by default).

Creating a Theme

There are two ways to change the appearance of your CE site:

Override the views in your own app/views directory
Create a theme with your own views and css.

The first option is good if you don't plan on sharing your modifications. Creating a theme makes sense if you want to allow other CE developers to use your theme in their application. Both methods are pretty similar, but I'm only going to cover creating a theme in this tutorial.

First, create your themes directory with your theme folder inside it. My theme is going to be called 'beach', so I'll create a folder structure like this:

/ce-sample-app
   /themes
       /beach
           /views
           /images
           /stylesheets

In /config/application.yml, add this so CE know which theme to use:

theme: beach

(Restart your server)

Now we'll override CE's default application.html.haml template, copying it to themes/beach/views/layouts/application.html.haml. From now on, this template will be used instead of Ce's version:

/beach
   /views
       /layouts
           application.html.haml

In our new application layout, let's include our own stylesheet after the CE styles:

= render :partial => "shared/scripts_and_styles"
- if @rss_title && @rss_url
= auto_discovery_link_tag(:rss, @rss_url, {:title => @rss_title})
# Adding this below:
= stylesheet_link_tag 'theme/screen.css'

When referencing image, javascript, or stylesheet assets from within a theme, you just add 'theme' in front of the file name. This tells CE to grab the file from the active theme (as specified in application.yml).

In themes/beach/stylesheets/screen.css, let's change the background of the site:

body {
background: #fff url(/images/theme/sand_tile.jpg);
}

Notice how I reference the background image? Just put '/theme/' before the filename. Refresh your browser, and you get this:

Yuck! Let's give that main content area a background, and some padding:

body {
background: #fff url(/images/theme/sand_tile.jpg);
}

#doc2 {
background: #fff;
padding: 10px;
}

Better:

Ok, now we'll add a nice header image, and a little more styling:

body {
       background: #fff url(/images/theme/sand_tile.jpg);
   }

#doc2 {
       background: #fff;
       padding: 10px;
   }

#hd{
       background: url(/images/theme/header.jpg) no-repeat left;
   }
#hd h1 {
       background-color:#000;
       -moz-opacity: 0.6;
       opacity:.60;
       filter: alpha(opacity=60);
       margin: 1em;
   }
#hd h1 a {
  display: block;
  color:#fff;
  height: 37px;
padding: 0 10px 0 10px;
  outline: none;
   }
#hd h2 {
  color: #fff;
   background-color:#000;
   -moz-opacity: 0.6;
   opacity:.60;
   filter: alpha(opacity=60);
   padding: 10px;
   }
  #hd h2 a {
   color: #B59F6D;
}

#NavBar {
   margin-top: 100px;
   }

Weee!

Ok, you get the idea. I'm not a graphic designer; if you want a good one, Andres did the default CE theme and I'm sure he'd be happy to help you out.

Now, if you want to get really fine-grained, you can start overriding templates like crazy (for example, you can make a /shared/_header.html.haml partial to change the header navigation). That may be the best option, depending on your needs, but most of us can get by mainly on CSS changes, and CE's built-in localization support makes it easy to change text throughout the app.

Localization

Let's say you want to change that heading on the home page from 'Recent Posts' to 'Radical Curls' (this is a beach-site, after all, right?).

You could override the base/site_index.html.haml template, providing your own in your theme's views/base/ directory, but let's do it an easier way.

First, create a language folder and locale file in your root directory, like this:

/ce-sample-app
   /lang
       /ui
           en-US.yml

Inside of en-US.yml, put the following:

en:
recent_posts: "Radical Curls"

This tells CE to replace the locale token 'recent_posts' with the string 'Radical Curls':

But how do you know which tokens you can replace? Easy: put this in your environment.rb:

AppConfig.show_localization_keys_for_debugging = true if RAILS_ENV.eql?('development')

Restart your server, and then check out your site in Firefox, using the Firebug extension (you could also just view source, but that's less fun):

Strings that can be localized show up italicized and in red, and have a localization_key attribute added. All you have to do is look for the localization_key, and then add that key with your modified string to your en-US.yml file.

Conclusion

This tutorial shows you how easy-to-use and flexible CommunityEngine can be. If you want to get more advanced, you can also customize CE's model and controller functionality, giving you complete control over the way you social site looks and behaves.

If you get stuck, don't hesitate to ask for help on the CE Google Group, where friendly developers are standing by!

Additional Concepts

CommunityEngine is a plugin (and relies on the Engines plugin for additional functionality). As such, the idea is that you don't need to make changes to CE itself; rather, you overide its views, controllers, and even models in your own application.
CE's interface is built using YUI's CSS grid library. Familiarity with that library will help you make changes to the CSS.
CE uses attachment_fu for photo uploading and resizing. For attachment_fu to work, you'll need to install an image processor, covered here.

Navigation

Recent site activity