Why Engines?
As an example, let me show you two screen shots. The first is the content management system from CrowdVine. I like a lot of the ideas inside of the CrowdVine version, but hate the implementation (I can say that because I wrote most of it). The second screen shot is from Yak, a simple programmer friendly CMS service that we’re working on. It has a near identical feature set but a cleaner implementation and much better UI. I want this new CMS to exist within CrowdVine. And whenever I make an upgrade to it, in Yak or CrowdVine, I want it that update available in my other app. This is what Engines are for.

Engines let you keep your feature together intact: models, controller, and views. It opens up a world of code libraries where the thing you’re trying to DRY up is UI heavy. Think about authentication, isn’t there a best practice for the design of a login screen with Twitter/Facebook options that you can just copy? YES! And in fact there are engines for that already, see omnisocial.

Creating an Engine

1. How do you create the boilerplate? Engines are just Gems with an /app directory, so you could use whatever method you already use for creating Gems. There’s also an application called enginex that will give you the basics, but I found I needed much more. So I started with a more robust engine example, omnisocial, and edited it. This isn’t optimal, but it only takes about 15 minutes and is a good way to learn how other people do it. After you’re done you should end up with a structure like this:

# Your typical Rails application structure
app
app/models
app/views
app/controllers
app/helpers
app/mailers

# Many people embed a rails application here in order
# to make mocking up a test environment easier.
test

# Engines are just Ruby gems and a lot of the setup lives
# here, as well as your migration and asset files.
lib
lib/my_engine.rb
lib/my_engine
lib/my_engine/engine.rb
lib/generators
lib/generators/my_engine
lib/generators/my_engine/templates
lib/generators/my_engine/templates/assets
lib/generators/my_engine/my_engine_generator.rb

# Having these two directories allows access to
# rails generate
script
script/rails
config
config/routes.rb # Yes, your engine has it's own routes.

# If you generate your migrations they'll be created here
# and you'll need to move them into your assets dir.
db
db/migrate/

VERSION # Example: 0.1.13
Gemfile # Just like any other Gemfile
LICENSE # Apache is a good choice.
README.rdoc
my_engine.gemspec

2. How can I have access to the Rails generator? Sometimes it’s helpful to be able to generate migrations or scaffolding. If you approach this like a Gem you’re not going to have any of the Rails app structure that allows you to call rails generate. But I also learned, through trial and error, that having too much of the structure causes conflicts with the main application, in particular you can’t have config/initializers. I’m not sure yet what the minimum is, but you’ll need script/rails and most of config/.

3. How do you develop your engine while developing your main app? Generally during development you want your main application to include a local development copy of your engine and in production to include a public version, for example one sitting on Github. Easy right? You should be able to add gem groups for each Rails environment to your Gemfile, like this:

group :development do
  gem "my_engine", :path => "../my_engine"
end
group :production do
  gem "my_engine", :git => "git://github.com/yourname/my_engine.git"
end

In Bundler 1.0 and earlier, that generates this error message: "You cannot specify the same gem twice coming from different sources." The work around, which I found from Cowboy Coded, is to use an environment variable. Seriously. This is supposed to be fixed in Bundler 1.1, but I haven’t been able to confirm this. Here’s the work around, which involves adding an ENV variable to your .bashrc and using that to control which library gets loaded from your Gemfile.

# Put this in your .bashrc
# export MY_BUNDLE_ENV="dev"
if ENV['MY_BUNDLE_ENV'] == "dev"
  gem "big_library", :path => "../big_library"
else
  gem "big_library", :git => "git://github.com/tonystubblebine/big_library.git"
end

4. How do I run migrations or use other assets like CSS files and images? You can’t do anything useful unless you can run migrations from your engine and include some basic CSS. You need two things, a generator file that tells your main app what to do when you run rails generate my_module and template files that your generator copies into place.

Your asset files will live in lib/generators/my_engine/templates. Your generator, lib/my_engine/big_cms/my_engine_generator.rb, should look like this:

require 'rails/generators'
require 'rails/generators/migration'
class MyEngineGenerator < Rails::Generators::Base
  include Rails::Generators::Migration

  def self.source_root
    File.join(File.dirname(__FILE__), 'templates')
  end

  # Implement the required interface for Rails::Generators::Migration.
  # taken from http://github.com/rails/rails/blob/master/activerecord/lib/generators/active_record.rb
  def self.next_migration_number(dirname) #:nodoc:
    if ActiveRecord::Base.timestamped_migrations
      Time.now.utc.strftime("%Y%m%d%H%M%S")
    else
      "%.3d" % (current_migration_number(dirname) + 1)
    end
  end   

  def create_migration_files
    %w{create_dummy_table add_foo_fields_to_dummy_table}.each do |migration|
      migration_template "#{migration}_migration.rb", "db/migrate/#{migration}.rb"
      sleep(1) # cheap hack to make sure migration numbers end up being different
    end
  end

  def copy_assets
    copy_file 'assets/stylesheets/my_module.css',  'public/stylesheets/my_module.css'
  end

  def copy_config_files
    copy_file 'my_module_initializer.rb',  'config/initializers/my_module.rb'
  end
end

There are a couple of oddities above, most notably the handling of migrations. It seems like you have to implement next_migration_number yourself in order to get migration files with timestamps. Then, because Rails wants migration timestamps to be unique, I needed a delay after each migration to force different timestamps for each migration file. Talk about hacky. I assume that this stuff will just get cleaned up over time.

5. Where can I get more help? For now, these are the best two tutorials I could find, both from The Modest Rubyist, Rails 3 Plugins: Writing an engine and Rails 3 Plugins: Rake tasks, generators, and initializers

This looks like a black art, right? Either that or I'm doing things the wrong way (please let me know if there are better ways). This is supposed to be the easy part and we're already resorting to cheap hacks. We haven't even started talking about the magic parts--how to customize the engine from within your main application.

Related Posts:

• ETel 2006: Day 1.
• Online Ruby Training
• Ruby/Rails/Fedora/Apache2
• Ubuntu on Rails: Getting up to speed with Ruby on Rails and Ubuntu
• Rails XSS Filter

Looking around I saw two approaches for Rails. Run Safe ERB and force yourself to validate each individual input or run Rick Olson’s white list plugin.

I decided to use the white_list plugin to clean all values in params. It required a little bit of tweaking. Here’s the details.

Install the white list plugin:

script/plugin install -x http://svn.techno-weenie.net/projects/plugins/white_list/

Edit vendor/plugins/white_list/init.rb so that white_list is available in the Controller:

require 'white_list_helper'
ActionController::Base.send :include, WhiteListHelper

Add a filter to application.rb in order to walk the params hash:

before_filter :sanitize_params

def sanitize_params
# TODO: 2007-06-20  -- I found that this didn't
# work when called with params instead of @params. I assume
# I'm clueless in some important regard. (Many important regards?)
@params = walk_hash(@params) if @params and !site_owner?
end

def walk_hash(hash)
hash.keys.each do |key|
if hash[key].is_a? String
hash[key] = white_list(hash[key])
elsif hash[key].is_a? Hash
hash[key] = walk_hash(hash[key])
elsif hash[key].is_a? Array
hash[key] = walk_array(hash[key])
end
end
hash
end

def walk_array(array)
array.each_with_index do |el,i|
if el.is_a? String
array[i] = white_list(el)
elsif el.is_a? Hash
array[i] = walk_hash(el)
elsif el.is_a? Array
array[i] = walk_array(el)
end
end
array
end

Does this look right to people? Is there a more idiomatic ruby/rails way to do this? I’m a bit worried about how this will perform on very large chunks of data or on deeply nested hashes.

Related Posts:

• Rate My Dance Moves
• Uplifting News About an Obvious Partnership
• Writing Rails Engines #1: Getting Started
• Social Workshop — A lifetime of products
• Squatting on Unfulfilled Dreams

I really like dance, especially hip hop, and especially if I am standing near the wall and somebody else is doing the dancing. I aspire to be a Poppin’ Pete but I have a closer relation to this guy.

The dance videos ended up being really good. There’s a little too much teenage craziness (or worse six-year-old boys dancing to “I’m In Love Wit A Stripper”) but there’s also plenty of great dancing from Dance2XS, crazy Japanese game show contestants, and even cowboys in sequins.

I check the YouTube for more every day so there should always be recent entries.

Related Posts:

• Rails XSS Filter
• Great Comments on Rate My Dance Moves
• Uplifting News About an Obvious Partnership
• Writing Rails Engines #1: Getting Started
• Social Workshop — A lifetime of products

What is Web 2.0?

What is Web 2.0: Design Patterns and Business Models for the Next Generation of Software

O’Reilly Media first popularized the term Web 2.0. This is Tim O’Reilly’s essay on the trends and companies defining the second generation of web development.

Wikipedia Entry on Web 2.0

Wikipedia’s entry on Web 2.0 with links to major resources. Wikipedia is itself an example of the Web 2.0 idea, “architecture of participation,” where the entire content of the encyclopedia is voluntarily contributed, editited and maintained by its readers. For example, the history page for their entry on Web 2.0 shows hundreds of updates from scores of users over the course of the last 16 months.

All Things Web 2.0 – The List

Need examples? This page lists several hundred companies that are built around the ideas of Web 2.0.

Design

Current Style in Web Design

Overview and examples of the designs that define web 2.0, like simplicity and effective use of whitespace, color, and big text.

Yahoo’s User Interface Design Patterns

Solutions to the most common design problems with descriptions. Great starting place for the fundamentals of web design. Includes when, why and how to use auto-complete, breadcrumbs, tabs, pagination, and ratings.

Yahoo’s UI Components

Downloadable UI Widgets and Ajax libraries including a calendar, slider, and tree view.

A List Apart

Articles on web design, graphic design, and user interface design.

Digital Web Design Articles
More articles on web design.

Programming

Ruby on Rails
Plenty of people are still building websites with Java, PHP, Perl, Python, and .NET. But plenty of other people are finding Ruby on Rails to be a platform that makes the common things trivial while staying out of your way when you want to do the hard things. This is the official Rails site with links to tutorials and documentation.

Rolling with Ruby on Rails

Great tutorial on how to get started with Rails. Takes you from installation to a simple cookbook application

Javascript Tutorial
Before you get too far with AJAX you’re going to have to learn some basic javascript. This is a decent tutorial along with very good documentation.

Getting Started with AJAX

Tutorial that takes you from beginning to end of a simple AJAX page.

script.aculo.us and Dojo
Getting AJAX to work correctly across browsers is hard. So it’s always better to start with somebody elses code. These are two of the best AJAX libraries.

Markup

Learning XHTML

Short and simple explanatioin of the differences between HTML and XHTML.

Learning CSS

Great starting point for learning CSS.

Head First HTML with CSS and XHTML
Great book for learning HTML and CSS.

What is RSS?

RSS is a formt for sharing and subscribing to feeds of site updates. Blogs are the most common sites to produce RSS feeds for their sites.

Bloglines

Even if you’re not producing RSS, subscribing to other people’s feeds can be very convenient. Signup for bloglines, a website that specializes in managing subscriptions, put a subscription link on your browser toolbar, and start subscribing.

Microformats
These are easy ways for you to provide semantic information about the data in your pages so that other people can programmatically parse and process the information. These are just starting to get mainstream traction.

Software

Blogger

Blogger is a blog hosting company. They let you create your own blog and start blogging in a matter of minutes. Odeo’s blog is run by bloggger.

MovableType

They offer free blog software (the paid versions are for extra support) and have an active community of developers creating add on products. Also their comment spam blocking is very good. That’ll come in handy if you become popular.

Word Press

Offers both blog hosting and free blog software.
MediaWiki

Software for collaborative writing where any visitor can add or edit content. This is the software that runs Wikipedia. There’s lots of other software that you could choose from, but I think this is the most polished.

PBwiki

Hosted Wiki. You can signup and get started in a matter of minutes.

Related Posts:

• Upcoming Talk: Web 2.0 Making It Big While Keeping It Small
• ETel 2006: Day 1.
• Writing Rails Engines #1: Getting Started
• Rails XSS Filter
• Obvious Trends

RAGI
Every O’Reilly ‘emerging tech’ conference comes up with one technology that is suddenly very easy and very accessible. I think RAGI, a Rails to Asterisk interface, wins this time. I managed to miss the presentation but heard great buzz afterwards. Here’s an O’Reilly introduction. An anonymous Odeo engineer asked about scaling issues in Rails and got back a response that Rails scales well as evidenced by sites like Odeo =)

AstLinux – HA
This is a linux distro tweaked for running Asterisk (mostly the same tweaks that real-time apps get). He’s working on adding in High Availability support which would give people an N+1 architecture. Too buzz-wordy? Key detail was that HA would work better and be impemented sooner for VOIP.

Zork on Asterisk.
Awesome! Coolest demo of the day goes to Zasterisk, a project to let you play Zork over the phone. It’s does Asterisk to speech recognition (Sphinx) to Zork to text-to-speech (Festival) and back out.

Imagine playing Zork while on hold or playing a MUD during your commute (VMUD).

VC Fireside Chat.
Sort of dreading this one but the others in the time slote didn’t look good. Turns out Marc Hedlund was on the panel. Point was start off with a product for yourself, but know when to make the switch to a product for others.

Other VC talking about the types of people he sees in early stage investing (spore stage). Two. One with a plan and no product. The other with a hack but no plan. He’s especially interesting if someone has already payed for the hack.

I think the key concept in those two points is that it’s extremely important to prove that someone likes the product (important if you’re trying to get investment).

Favorite phrase of the day was along the lines of: vc’s blog in order to ‘chum the waters’

Marc gave more advice, be plain spoken. Common theme in his engineering management. Complexity is a sign that you don’t understand the problem. Plain speech also gives people the impression that you know what you’re doing. Convoluted speech just gives people the impression that _they_ don’t know what’s going on.

More Marc. Hit it where they ain’t. Find a need that nobody is talking about and go after that. It’s not that you’ll be the only person in the space, but that you’ll be in the first wave.

Quinn Weaver. Open Source is viral marketing. If you create software that is used my millions you can create a company after. Another example of having proven customers. MySQL is a good example of a funded company and 37Signals of a private company. His company Fairpath is planning to give away a Perl to Asterisk software, Dido. Release tomorrow. I like Quinn.

Usability.
A YakPak guy asked who did not have a microphone on their computer. Several Mac people raised there hands. My hand went straight to my forehead.

Favorite Encounter.
Cooper Marcus of Spark Parking. He’s got a nice clear business model, pragmatic goals, and cool tech that involves phones and gluing wireless devices to the ground. He’s also Lowell ’90.

Related Posts:

• Writing Rails Engines #1: Getting Started
• Getting Started With Web 2.0
• 10 Steps to a Hugely Successful Web 2.0 Company
• Online Ruby Training
• Ruby/Rails/Fedora/Apache2

He’s CEO of Ionami, an 8-person web consultancy. He’s still an entrepeneur and doing big things with Rails. I’m so happy to run into old friends who are doing well.

Related Posts:

• Writing Rails Engines #1: Getting Started
• Rails XSS Filter
• Rate My Dance Moves
• Getting Started With Web 2.0
• Identity Aggregation at Feedication

I started with Learning PHP. The class is self-paced, you read lab material and type code into an integrated programming sandbox. Then at the end of the lab you take a short test or do a short programming assignment. A grader looks over your work and gives you feedback.

The hands-on piece works! The programming sandbox is really useful and gives you a chance to immediately hack on whatever the lab is teaching you.

The Learning PHP class was geared towards people new to programming or new to the web, for instance there’s a “What is a variable” section. That got me thinking, how would I gear a Ruby on Rails tutorial, towards beginners or towards experts.

Rails has a real following among high level programmers because it abstracts a lot of menial details while also offering enough flexibility to override the defaults. It looks like a Java killer so it’s ending up in a lot of flame wars about how enterprise ready it is.

People haven’t explored how easy it is for designers or part-time programmers to use. Is it a PHP killer? Well, you don’t need to know any Ruby to get a Rails application up. That’s a good sign. You usually don’t need to know any SQL. That’s another good sign.

I wonder if the Model-View-Controller model is too abstract for most non-programmers? In my experience, people will do fine. Our web producers work with a much more abstracted system.

In any case, I think the online lab + sandbox model that UserActive offers would be a great introduction to people who probably aren’t going to go through the trouble of installing Rails themselves.

In the mean time, here’s the full UserActive catalog.

Related Posts:

• Writing Rails Engines #1: Getting Started
• YouTube API How-To
• ETel 2006: Day 1.
• Ruby/Rails/Fedora/Apache2
• Ubuntu on Rails: Getting up to speed with Ruby on Rails and Ubuntu

I started by trying to get packages with yum.
yum install ruby irb ruby-devel

That lead to a dependancy issue. I needed apxs, but what package is it in? Ended up being in the httpd-devel package.

Then I moved on to installing mod_ruby. Having the ruby interpreter run inside Apache seems like a good idea – at least from a performance standpoint. Here’s the guide I worked from.
http://www.modruby.net/en/doc/?InstallGuide

However, it turns out that mod_ruby comes with a slew of namespace complications. From the rails wiki, “considered unsafe to use mod_ruby and Rails with more than one application.”

FastCGI is a safer alternative. The rails wiki has good setup documentation:

http://wiki.rubyonrails.com/rails/show/RailsOnFedora

I did run into trouble with MySQL – I needed to tell Rails where the mysql.sock file was. Here’s a ticket explaining the problem.
http://dev.rubyonrails.com/ticket/200

Related Posts:

• Writing Rails Engines #1: Getting Started
• ETel 2006: Day 1.
• Online Ruby Training
• Ubuntu on Rails: Getting up to speed with Ruby on Rails and Ubuntu
• Rails XSS Filter

Install Ruby on Rails
The Ruby on Rails wiki provides a great tutorial. Basically, you apt-get install a bunch of ruby packages, manually install rubygems (a ruby module manager a la CPAN), and then use gems to install rails. I needed to have sudo to run most of the commands.

Read About Rails
You can start on page 2 of the O’Reilly Article, since the first page is all about installing on Windows. There’s more Windows-centricity to work around, see below.

The Webserver
The article recommends using the supplied webserver. I used that for now since I was more interested in getting a taste of Ruby than I was of Apache conf files. Initially I started the webserver in the background, but it spits a lot of output. You’ll probably want to redirect the output with a command like.

ruby script/server &> /tmp/rubylog

The Database
The article assumes a GUI MySQL admin interface. I prefer the command line. Here’s a sql file that handles all the table creations for you.

Gotchas
The database/model naming convention is goofy. Table names are plural, foreign keys singular, and models singular. That tripped me up. I’d much prefer the table names be singular so that they can match the foreign keys.

A lot of the commands in the article were written for a Windows server so some of the slashes are backwards.

Resources
Rolling on Rails, Part Two
Explanation of Minutae in the Rolling Articles
Programming Ruby, the book, online, for free.
Ruby on Rails site

Related Posts:

• Writing Rails Engines #1: Getting Started
• ETel 2006: Day 1.
• Online Ruby Training
• Ruby/Rails/Fedora/Apache2
• How to use a Verizon USB Card with Ubuntu