Introduction

This guide is based on GettingStarted guide, but extends it with templating changed to HAML. The Rack::Reloader is used for reloading development environment.

Local installation

It's important to understand that development environment for the appengine and the Jruby contain 3 different places of ruby gems:

• system ruby gems. These gems come with your MRI Ruby. You should definitely use MRI ruby. Current appengine-jruby doesn't work with jruby. Gems here contain minimum for development environment.

• application gems. This is the .gems folder in your application directory. These gems installed by bundler and used for caching only.

• deployment gems. This is copy of the application gems packed into the gems.jar file in ./WEB-INF/lib directory. The appengine has limitation on amount of files but jruby can read gems from jar archive. So, for deployment, application gems are packed to gems.jar.

System ruby gems installation

First, make sure that you have the latest version of gem installed

$ gem --version
1.3.5
$ # If you have the older version perform upgrade
$ gem update --system
$ # Install the required system gems
$ gem install --no-rdoc --no-ri google-appengine

Application gems installation

Create the folder for application. In this guide it's assumed to be ~/guestbook/.

$ mkdir guestbook
$ cd guestbook

In order to manage gems one need to create the Gemfile control file. Ours will be pretty simple.

$ cat >Gemfile <<EOF

disable_system_gems
disable_rubygems
bundle_path ".gems/bundler_gems"

gem "sinatra"
gem "dm-core"
gem "dm-appengine"
gem "haml"

EOF

Creating application

First let's create the config.ru, which will configure application and reloading for development environment. The simple use Rack::Reloader will not work as we need to reload the Sinatra framework.

$ cat >config.ru <<EOF 
require 'appengine-rack'
require 'guestbook'

AppEngine::Rack.configure_app(:application => "guestbook", :version => 1)

configure :development do
  class Sinatra::Reloader < ::Rack::Reloader
    def safe_load(file, mtime, stderr)
      if File.expand_path(file) == File.expand_path(::Sinatra::Application.app_file)
        ::Sinatra::Application.reset!
        stderr.puts "#{self.class}: reseting routes"
      end
      super
    end
  end
  use Sinatra::Reloader
end

run Sinatra::Application
EOF

The reloader example, above, assumes that application is Sinatra traditional style application and all routes defined in the 'guestbook.rb' file, or main file of the application.

If application has a separate file for routes, for example 'route.rb', then ::Sinatra::Application.app_file should be replaced with './route.rb' or similar. What is meant here is that you need to do .reset! only in case when file with routes changes. If you routes scattered in different files you need to write more complex reloading strategy.

If you are using 'sinatra/base' instead of the traditional Sinatra application, you, probably, already found out, that you should take care about everything yourself. And the reloader is no exception. Everywhere, where ::Sinatra::Application mentioned, you need to replace it with your class. Assume following example:

require 'sinatra/base'
class Simple < Sinatra::Base
  get '/' do
     'Hello World!'
  end
end

then your reloader should do Simple.reset! for file with routes. And, of course, you need to change run Sinatra::Application to run Simple.new.

Now, let's get back and put the application itself

$ cat >guestbook.rb <<EOF 
require 'sinatra'
require 'dm-core'
require 'haml'

# Configure DataMapper to use the App Engine datastore 
DataMapper.setup(:default, "appengine://auto")

# Create your model class
class Shout
  include DataMapper::Resource

  property :id, Serial
  property :message, Text
end

# Set Haml output format and enable escapes
set :haml, {:format => :html5 , :escape_html => true }

# Main board
get '/' do
  # Just list all the shouts
  @shouts = Shout.all
  haml :index
end

post '/' do
  # Create a now shout and redirect back to the list
  shout = Shout.create(:message => params[:message])
  redirect '/'
end
EOF

Let's add some templates as well

$ mkdir views

First, the above-mentioned index.haml

$ cat >views/index.haml <<EOF
%h2 Messages
- for shout in @shouts
  %p<
    Someone wrote,
    %q= shout.message

%form{:method => :post}  
  %textarea{:name => :message}  
  %br/
  %input{:type => :submit, :method => :Shout}
EOF

And the layout for the application

$ cat >views/layout.haml <<EOF
!!!
%html
  %head
    %title Guestbook
  %body
    != yield
EOF

Running servers

Now, finally we are ready to run the development with Sinatra reloading.

$ dev_appserver.rb .

The Rack::Reloader uses mtime on your system, so if the reloader is not doing its job try touch guestbook.rb.

Enjoy!

all question and improvements are welcome in the google group