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

Josh Susser talked about how he’d abandoned rails generate in favor of maintaining an exemplar project in subversion. After tweaking acts_as_authenticated and acts_as_taggable I think that’s not a bad idea.

Chris Wanstrath talked about how CNet is using Rails to build Chow.com and Chowhound.com. They use microformats to syndicate content from one site to another. I’m know that’s not the first production use of microformats but it’s definitely the first time I’ve heard someone outside of the microformats website talking about a real world use. Chris just released mofo, a microformats parser for ruby.

Michael Kovacs showed his new get_sorted_objects plugin for creating sortable HTML data tables.

Coda Hale talked about the importance of a staging environment and how effective Wesabe’s integration of campfire (group chat) and continuous integration is. I’ve done continuous integration with breakages going out over email and the group chat way is definitely more effective. I never check in code without waiting in the chatroom to see that the tests didn’t break. Looking bad in front of your coworkers is an ok deterrent. But knowing that they’re going to start talking smack about you behind your back, that’s a great deterrent. Also the company that Coda and I have been working on might launch very very soon. Look out for Wesabe!

Evan Henshaw-Plath talked about the caboo.se documentation project. It looks awesome. That sparked a discussion about how the rails core team needs more support.

Florian Weber, who’s on Rails core, agreed, but thought there was some confusion caused by people who were complaining without offering constructive advice. He also pointed out that at least Rails is headed in the right direction, it’s filling a major need and it isn’t suffering from feature bloat.

There were also a few lighting talks and announcements.

My favorite was a round of people announcing that they were hiring. After about ten people made this announcement the question was flipped to “who’s looking for a job?” Nobody.

Tyler Kovacs from ZVents.com showed off his new custom_benchmarks plugin for adding your own information to the benchmark line logged at the end of each rails request.

Kongregate, a flash games community and marketplace gave a demo. They’re in private beta but you can request an invite from their home page. Special preference for people at the Ruby meetup. Here’s what TechCrunch had to say about them. If you don’t think flash games can be cool, check out Raiden-X.

Related Posts:

• Search Ruby Gem (rdoc) Documentation
• Writing Rails Engines #1: Getting Started
• YouTube API How-To
• Blaine’s Odeo Extractions
• ETel 2006: Day 1.

The YouTube API lets you search for videos and display them on your site. For example, I use the API to pull videos tagged dance and display them on Rate My Dance Moves. The YouTube API is currently the 10th most popular API on ProgrammableWeb with 46 mashups.

To get started you need to sign up for a developer account. That will give you the developer id required to use the API.

Using the API

The major API methods are for retrieving lists of videos, which you can do by tag, user, user favorites, and featured. The information returned from the list methods is usually enough to display a video on your site. All you have to do is plug the video id into the web snippit below.

<object width="425" height="350">
<param name="movie" value="http://www.youtube.com/v/ID&autoplay=1">
</param>
<embed src="http://www.youtube.com/v/ID&autoplay=1"
type="application/x-shockwave-flash" width="425" height="350"></embed>
</object>

Most of the information you need is in the video list methods. However, if you want a list of comments or channels for the video you’ll need to call the get_details method.

One complaint I had with list_by_tag is that the results come back ordered by relevance rather than recency. That means if you want to build a self-updating site you need to either regularly crawl the entire result set (results are paged) or sit on one of the RSS Feeds.

API Wrappers

There are good libraries for using the YouTube API with Perl, Ruby, and .NET. If you’re using another language, say Java, PHP or Python, you’ll have to write some code yourself. I’ve included links to example PHP and Python code and listed an example Ruby program that you can use as a template for whatever language you’re writing in.

There’s two competing Perl modules, but Hironori Yoshida’s WebService::YouTube and WebService::Youtube::Feeds seem best based on the recent development activity and strength of documentation. His is the only wrapper which includes support for the feeds, nice since the feeds have functionality thats not in the API (namely list by recency).

Shane Vitarana released a YouTube Ruby Gem after I’d built RateMyDanceMoves. Too bad, since it seems like the most polished of all the wrappers.

Eamonn Flynn has a .NET wrapper for the YouTube API.

There doesn’t seem to be a packaged PHP library but these two tutorials from waxjelly should be enough to get you started.
Simple PHP Script Using the YouTube API with Pagination
A More Complex PHP Script Using the YouTube API with Pagination.

ThinkHole labs has some example YouTube API code for Python users. Apparently using the API can be as simple as passing a dictionary to YouTube’s XML-RPC interface.

Code Example

I’d written my own code before the Ruby library came out. I want to show it here so you can see how simple writing your own code would be.

#!/usr/bin/env ruby
require 'open-uri'

tag = "dancing"
per_page = "100"
def_id = "YOUR_DEV_ID_HERE"
url = "http://www.youtube.com/api2_rest?" \
+ "method=youtube.videos.list_by_tag" \
+ "&tag=#{tag}&per_page=#{per_page}&dev_id=#{dev_id}&page=1"

open(url) do |f|
xml = f.read
end

doc = REXML::Document.new(xml)

elements = doc.root.get_elements("//video")
elements.each do |v|
puts v.get_elements("id").first.get_text.to_s
puts v.get_elements("title").first.get_text.to_s
puts v.get_elements("tags").first.get_text.to_s
puts v.get_elements("thumbnail_url").first.get_text.to_s
end

More Info

The Amazing YouTube Tools Collection has a long collection of YouTube tools, mashups, and plugins.

Related Posts:

• Using the Salesforce API
• Introduction to Salesforce AppExchange
• Quotes On Your Phone
• Online Ruby Training
• Writing Rails Engines #1: Getting Started

FakeWeb
A test helper that makes it simple to test HTTP interaction

WeightedSelection
A simple library for obtaining weighted randomized selections (like for web AB testing perhaps).

Related Posts:

• Writing Rails Engines #1: Getting Started
• The Real Lessons From Twitter
• My Favorite Podcast Episodes
• Odeo Gets New Life
• Putting Rails to Work

Itch scratched. Now ruby is as good as perl (for me at least). I can’t make heads or tails of a library module unless I can read the API documentation.

So I put up GemJack.com as a place to host the rdoc documentation for every ruby gem. It updates once a day based on polling the ruby gems repository.

Other features like deep search, ratings, comments, RSS feeds, and better meta-data can come later.

Related Posts:

• Putting Rails to Work
• Writing Rails Engines #1: Getting Started
• YouTube API How-To
• Blaine’s Odeo Extractions
• ETel 2006: Day 1.

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

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

Software and software techniques have solidified. An agile, keep it simple, release as soon as you have value development methodology is emerging from the bureaucratic promise everything and deliver crap, marketing driven dot-com mess. There’s also a much better understanding of how to get and keep users and how to market your company on the cheap.

Here’s the list of reading material that everyone starting a web company should be familiar with.

Ruby
Ruby on Rails is a web framework that lets you get web sites out fast. Very fast. And it has all the flexibility and robustness that you hope you’ll need down the road when your site becomes popular.
www.rubyonrails.com/

KISS Development
Ruby’s brought to you by 37 Signals, the company behind Basecamp. They’re also on the cutting edge of low overhead development methods. It’s worth following their blog (although they’ve watered down their content with generic blog entries).
37signals.com/svn/
37signals.com/svn/archives2/scoble_wonders_if_37signals_is_influencing_microsoft.php
37signals.com/svn/archives2/entrepreneurs_angels_and_the_cost_of_launch.php

Passion
Kathy Sierra, who created O’Reilly’s Head First Series, has great writing on what’s going to make your users enjoy their experience and come back for more.
headrush.typepad.com/creating_passionate_users/
headrush.typepad.com/creating_passionate_users/2005/06/building_a_succ.html

Blogvertising
Hugh Macleod’s blog, gapingvoid.com, teaches blogvertising by example. You think he’s talking explicitly about blogvertising or maybe making crass commentary on society. Then you realize that you want to buy some stormhoek wine and a english cut $3000 tailored suit. You just got sold to. I’m still not sure how I feel about that. All I do know is that I want a new suit.
www.gapingvoid.com/

Related Posts:

• Writing Rails Engines #1: Getting Started
• Experiments in Software Services
• Using the Salesforce API
• Wesabe Launched [updated]
• Putting Rails to Work

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