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.
Ok, now we'll add a nice header image, and a little more styling:
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.
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):
Requirements
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
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_VERSIONrequire 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 belowrequire "#{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')
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.