b a d p o p c o r n

How to Quickstart Merb Slice Development

Written by Ben on November 2, 2008 | 6 Comments

What are Merb Slices?

Merb Slices are a kind of mini Merb Application that can be packaged up as gems and used as is (or with customizations) within actual Merb Applications. They are full Model-View-Controller stacks to support a large feature within a larger application. Examples could be a full blogging system, user management system or a file upload system.

Where else can I find good overview information about Merb Slices?

There are a few places, but you should start with the MerbCamp 2008 MerbSlices talk by Daniel Neighman aka hassox. His slides are found here and here. Watch the other MerbCamp videos for more Merb info.

So what does this article cover?

This just provides some missing details for a developer to immediately get a slice working. The above material gives a great overview of slices in general and the why/how to use/install them in main Merb applications.

Let’s start by creating our slice.

$ merb-gen slice myslice
Generating with slice generator:
     [ADDED]  app/controllers/application.rb
     [ADDED]  app/controllers/main.rb
     [ADDED]  app/helpers/application_helper.rb
     [ADDED]  app/views/layout/myslice.html.erb
     [ADDED]  app/views/main/index.html.erb
     [ADDED]  config/init.rb
     [ADDED]  config/router.rb
     [ADDED]  lib/myslice.rb
     [ADDED]  Rakefile
     [ADDED]  README
     [ADDED]  spec/myslice_spec.rb
     [ADDED]  spec/controllers/main_spec.rb
     [ADDED]  spec/spec_helper.rb
     [ADDED]  stubs/app/controllers/application.rb
     [ADDED]  stubs/app/controllers/main.rb
     [ADDED]  TODO
     [ADDED]  public/javascripts/master.js
     [ADDED]  public/stylesheets/master.css
     [ADDED]  LICENSE
     [ADDED]  lib/myslice/merbtasks.rb
     [ADDED]  lib/myslice/slicetasks.rb
     [ADDED]  lib/myslice/spectasks.rb
$ cd myslice

Our goal here is to set up our slice so we can actually do development without needing to install it within a Merb application, and to give an example run through of creating a resource.

Let’s start by editing the slice’s init.rb file. This file is solely used in your slice development cycle; it is omitted from the final packaged gem; it is NOT used in production. If you look at the slice’s Rakefile, you will see that NO file in the config/ directory is included in the gem.

$ vi config/init.rb
# Add the following to the top of the slice's config/init.rb file.
# USE THE CORRECT GEM VERSIONS.
merb_gems_version = "0.9.12"
dm_gems_version   = "0.9.6"

# Uncomment the following two lines to develop with haml instead of erb.
# dependency "merb-haml", merb_gems_version
# use_template_engine :haml

dependency "dm-core", dm_gems_version
dependency "dm-aggregates", dm_gems_version
dependency "dm-migrations", dm_gems_version
dependency "dm-timestamps", dm_gems_version
dependency "dm-types", dm_gems_version
dependency "dm-validations", dm_gems_version

use_orm :datamapper

What we did above is to declare a dependency on the DataMapper ORM. You can use whatever ORM you wish, but I’ll be using DataMapper as the example in this article.

Also, I have included commented lines to show how one would use Haml instead of Erb as the templating engine. I highly suggest that developers write views for BOTH Erb and Haml when developing slices. This gives the users of such slices a choice.

Since we’re editing files in the config/ directory, we’ll go ahead and create the database.yml file we’ll need.

$ vi config/database.yml
# This is a sample database file for the DataMapper ORM
development: &defaults
  # These are the settings for repository :default
  adapter:  sqlite3
  database: sample_development.db

Next, we go ahead and try creating a resource as most developers will be doing. It’s just the same merb-gen command as one would do for any regular Merb application.

$ merb-gen resource article
     [ADDED]  spec/models/article_spec.rb
     [ADDED]  app/models/article.rb
     [ADDED]  spec/requests/articles_spec.rb
     [ADDED]  app/controllers/articles.rb
     [ADDED]  app/views/articles/index.html.erb
     [ADDED]  app/views/articles/show.html.erb
     [ADDED]  app/views/articles/edit.html.erb
     [ADDED]  app/views/articles/new.html.erb
     [ADDED]  app/helpers/articles_helper.rb

When we edit the articles controller, we’ll see that it looks exactly like a generated resource that one would get in a Merb application. In fact that’s probably the whole point since we want our slices to be full MVC stacks to implement our subsystem features. But if we tried to use this resource right now, we’ll find that our slice just won’t work. The main reason is how we define a slice’s controller versus a controller in a full Merb application. The whole issue is about namespacing.

$ vi app/controllers/articles.rb

We need to change the following class declaration:

class Articles < Application

to

class Myslice::Articles < Myslice::Application

This article class needs to inherit from the slice’s application class instead of whatever Merb app it is installed in. And the Articles class needs to be in the Myslice namespace so the slice router rules will actually be able to find the class.

The rest of the controller looks good. It’s got all the default DataMapper access code for its methods. NOTE: If one did not call “use_orm :datamapper” in the slice’s init.rb file, then all this ORM access code will be omitted; one would have a plain class whose methods just called `render`.

As a next step, one would generally verify that merb-gen would have updated the config/router.rb file with this new resource. WARNING! The config/router.rb file is NOT where routes are configured for slices. Everything is done in lib/myslice.rb, or whatever it is named in your real slice. In fact, this is also where we’ll find other configuration options.

$ vi lib/myslice.rb

Let’s go ahead and update our slice meta data. Replace the following code with your own stuff.

# All Slice code is expected to be namespaced inside a module
  module Myslice

    # Slice metadata
    self.description = "Myslice is a chunky Merb slice!"
    self.version = "0.0.1"
    self.author = "Engine Yard"

I won’t cover the other slice hooks in this file except for the “def self.setup_router(scope)” method. This is where you SHOULD to add your resource. Although the scope.default_routes line will correctly route to your resource, I find it cleaner to explicitly declare the slice’s routes. Watch the video mentioned above to understand why we setup routes in this hook instead of a slice’s router.rb file.

def self.setup_router(scope)
      # Add the following resource line
      scope.resources :articles
      # The lines that follow are the pre-generated ones.

      scope.match('/index(.:format)').to(:controller => 'main', :action => 'index').name(:index)
      # the slice is mounted at /myslice - note that it comes before default_routes
      scope.match('/').to(:controller => 'main', :action => 'index').name(:home)
      # enable slice-level default routes by default
      scope.default_routes
    end

I personally would delete the “scope.default_routes” line because I’m all about explicitly specifying routes.

At this point, we’ve got routes and a fixed up controller.

Now we look at the Article model. This model contains the code required to define it as a DataMapper resource.

$ cat app/models/article.rb
class Article
  include DataMapper::Resource

  property :id, Serial
end

Again, as with controllers, the DataMapper code would have been omitted without the “use_orm :datamapper” in the slice’s config/init.rb file. We would have had an empty class.

I will skip over how we develop Models for Datamapper in Merb. One should watch the other MerbCamp videos for that. Let’s just assume that you’ve added a few other properties to the Article model class.

Let’s create the model’s sqlite3 tables.

$ rake db:automigrate
Don't know how to build task 'db:automigrate'

Oops. We don’t have that kind of default support in our slice’s rake tasks. But no fear, we’ll just invoke the auto_migrate! directly:

$ echo 'DataMapper.auto_migrate!' | slice -i
Loading init file from /Users/notroot/projects/myslice/config/init.rb
 ~ Connecting to database...
 ~ Loaded slice 'Myslice' ...
 ~ Parent pid: 9145
 ~ Activating slice 'Myslice' ...
DataMapper.auto_migrate!
[Merb::DataMapperSessionStore, Article]

Be sure to use single quotes since the `!’ character is special in bash. But if you want to do it interactively, just start up the slice irb console.

$ slice -i

The only other thing to note is how slice sql tables are named. Our “articles” table in the slice’s development database becomes “myslice_articles” in a Merb application’s database.

And to finally get it all together, we need to start mogrel to serve up the slice… but NOT using the `merb` command. We use the `slice` binary.

$ slice
Loading init file from /Users/notroot/projects/myslice/config/init.rb
 ~ Connecting to database...
 ~ Loaded slice 'Myslice' ...
 ~ Parent pid: 9147
 ~ Activating slice 'Myslice' ...
merb : worker (port 4000) ~ Starting Mongrel at port 4000
merb : worker (port 4000) ~ Successfully bound to port 4000

And off to the browser you go; and off to developing your slice.
Example) http://localhost:4000/articles

So what’s next once I finish developing my slice?

Install your slice directly into your gem repository.

$ sudo rake install

Add your slice to the application’s list of dependencies.

$ cd ~/projects/myapp
$ vi config/dependencies.rb
# Add your slice dependency to the bottom of the file.
dependency "myslice", "0.0.1"

Install the Slice into your Merb Application.

$ rake -T slices
$ rake slices:myslice:install

And go ahead and add your slice to your application’s router.rb file.

$ vi config/router.rb
# Find the following method call and add your slice.
Merb::Router.prepare do
  # This mounts your slice to the default http://example.com/myslice/
  # "namespace". See Merb's rubydocs for more info about options.
  slice(:myslice)

  # other stuff omitted.
end

Now, you can run `merb` to start up mongrel for your application and
hit away under the /myslice url path namespace.

Example) http://localhost:4000/myslice/articles

Go forth and slice!


[del.icio.us] [Digg] [Google] [StumbleUpon] [Windows Live] [Yahoo!] [Email] More »

Posted in Ruby, Technology, Web

6 Comments

Installing Mysql with MacPorts for Rails on Leopard

Written by Moe on September 19, 2008 | 1 Comment

I just spent a hour going through this so you won’t have to. I thought I installed mysql using mac ports but I kept getting this error.

Errno::ENOENT (No such file or directory - /tmp/mysql.sock):

Below are the three steps you need to get Mysql running on Leopard for MacPorts.

sudo port install mysql5 +server
sudo launchctl load -w /Library/LaunchDaemons/org.macports.mysql5.plist
sudo ln -s /opt/local/var/run/mysql5/mysqld.sock /tmp/mysql.sock

[del.icio.us] [Digg] [Google] [StumbleUpon] [Windows Live] [Yahoo!] [Email] More »

Posted in Rails

1 Comment

Authentication and Authorization in Rails

Written by bill on September 16, 2008 | 4 Comments

Some say Rails is “missing” a lot of things you might expect to find in full-featured web development framework, but it doesn’t matter - what’s it’s NOT missing is a plugin system which allows you to add any functionality you need by pulling a few bits of code from other authors into your site. What I’ll be using in this example are the restful-authentication plugin for authentication and the role_requirement plugin for authorization. Both of these are hosted on github, which hosts loads of Rails plugins along with other open projects. As the name implies, they use git for their repositories, so you should install git to grab these plugins.

Setting up authentication

First, you’ll need to set up authentication. In the vendor/plugins folder of your project, run:

git clone git://github.com/technoweenie/restful-authentication.git restful_authentication

This will grab a copy of the restful_authentication plugin; you don’t need to mess with any of the code in the plugin itself. go back to your project’s root and run:

script/generate authenticated user sessions
rake db:migrate

This will set up the user model for you and insert the users table in your database. You can add arguments to the generate script such as –include-activation –aasm to enable activation emails but we’re not going to cover all of that right now.

Now, you’ll have two new controllers in your application, sessions_controller.rb and users_controller.rb. Go to each of these files and remove or comment out the line that says ‘include AuthenticatedSystem’, and copy this line to the top of the application controller instead, right at the beginning of the class definition:

class ApplicationController < ActionController::Base
  include AuthenticatedSystem

and so on. The generate script should have also added these lines to routes.rb:

map.logout '/logout', :controller => 'sessions', :action => 'destroy'
  map.login '/login', :controller => 'sessions', :action => 'new'
  map.register '/register', :controller => 'users', :action => 'create'
  map.signup '/signup', :controller => 'users', :action => 'new'
  map.resources :users

  map.resource :session

These give you some prettier URLs rather than, for example, /users/new to sign up and /sessions/new to login. Generally you want the first thing a user sees to be the login page, so if you want to you can make that the default by adding

map.root :controller => "sessions", :action => "new"

to your routes. You’ll also need to remove or rename index.html in the public folder.

At this point you have a basic authentication system, which is great considering how easy it is to set up, but alone it’s pretty useless. You’ll notice, no matter if you’re logged in or not, you still have full access to your app. So why did we even bother? Because now, you can add authorization to lock down actions based on roles you set up.

Setting up authorization

There are a few different ways to do this; if you want a very, very granular authorization system you can install padlock authorization which allows you to set roles per each object in your application. We decided this was probably overkill for our latest project, but I may touch on it in a later blog if we decide to use it after all. We’ll be using the aforementioned role_requirement plugin.

Back to github with us! Head back to your /vendor/plugins folder and run:

git clone git://github.com/timcharper/role_requirement.git role_requirement

Go back up to your application’s root, and run:

script/generate roles Role User
rake db:migrate

Now, you’ll have to make some manual database changes. You need to add one or more roles to the roles table, and if you have any users, assign them initial roles, if you want them to have roles, in the roles_users table. You can, of course, just add a new controller and view to make all this changeable from your application, but you’ll probably still be setting up one admin user by hand to start things off when you go live.

Now you can go about editing your controllers to make each one accept and reject your roles. For example, say I have a simple model with with a TV show, which can have one starting date. To allow only administrators to make changes, you can set up your Shows controllers like so:

class ShowsController < ApplicationController
  require_role "ADMIN", :for_all_except => [:index, :show]
  def index
    @shows = Show.find(:all)

(The rest is standard Rails boilerplate)

A later post will probably deal with setting/changing roles within your application.