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!