happy 0.1.0.pre9 → 0.1.0.pre10

data/README.md

@@ -1,29 +1,136 @@
-# Happy
+# Happy Ruby
 
-TODO: Write a gem description
+**The Happy Web Application Toolkit for Ruby.**
 
-## Installation
+## Introduction
 
-Add this line to your application's Gemfile:
+Happy is a toolkit for developing web applications using Ruby. Inspired by both Sinatra and Rails, it sits somewhere in the middle, trying to offer the super-light-weight attitude and flexibility of Sinatra, the comfort and power of Rails, and adding a big chunk of extensibility and modularity that any lover of object-oriented application design will enjoy.
 
-    gem 'happy'
+Furthermore, the way Happy handles incoming requests is vastly different from how most of the other frameworks do it, offering a new, extremely flexible and, yes, fun way of building your application.
 
-And then execute:
+### Examples
 
-    $ bundle
+"Hello world" with Happy:
 
-Or install it yourself as:
+```ruby
+# config.ru
+require 'happy'
 
-    $ gem install happy
+class MyApp < Happy::Controller
+  route do
+    'Hello world'
+  end
+end
 
-## Usage
+run MyApp
+```
 
-TODO: Write usage instructions here
+How about something a little bit closer to reality?
 
-## Contributing
+``` ruby
+# config.ru
+require 'happy'
 
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+class MyApp < Happy::Controller
+  route do
+    # Set a default layout for all responses!
+    layout 'application.erb'
+
+    # Happily deal with sub-paths!
+    path 'hello' do
+      # Let's use a different layout here.
+      layout 'hello_layout.erb'
+
+      # Happily deal with parameters contained in paths!
+      path :name do
+        # Just return a string to happily render it!
+        "Hello, #{params['name']}"!
+      end
+
+      "Silly user, didn't provide a name!"
+    end
+
+    # Now let's do something a little bit more exciting!
+    #
+    # How about passing control to another controller? In this instance,
+    # we're invoking an instance of ResourceMounter, a controller class
+    # that serves a model resource RESTful-Rails-style. We'll save a 
+    # reference to the controller for later.
+
+    articles = ResourceMounter.new(:class => Article)
+    articles.perform
+
+    # Or use the shortcut: invoke :resource_mounter, :class => Article
+
+    # This block of code is executed for every request, so you can do
+    # some crazy stuff here, including only defining specific paths
+    # when certain conditions are given. Just write Ruby! :)
+    
+    if context.user_is_admin?
+      path 'delete_everything' do
+        Article.delete_all
+
+        # How about rendering a view template and passing
+        # variables to it?
+        render 'admin_message.erb',
+          :message => 'You just deleted everything. Grats!'
+      end
+    end
+
+    # If we reach this point, the request still hasn't been handled, so
+    # the user must by trying to access the root URL. How about a redirect
+    # to the URL of the previously invoked controller?
+    
+    redirect! articles.root_url
+  end
+end
+
+# It's just a Rack app, so let's run it.
+run MyApp
+```
+
+
+### The Basic Building Blocks
+
+Each and every web application built with Happy revolves around two core building blocks: the **context** and one or more **controllers**.
+
+The **context** is a wrapper around the request currently being handled by your application. It holds information about the request itself, the response being rendered, and any piece of application logic that's scoped to individual requests (like authentication or authorization related code.) Happy doesn't have view helpers (like Rails); instead, view templates are rendered within the scope of the current context.
+
+**Controllers** are building blocks that mostly deal with routing and acting on request URLs. Unlike controllers in Rails, instead of deciding on what controller to run depending on the requested URL, each request is immediately passed to a **root controller** which then decides how to continue. Controllers can serve content, parse the URL for paths, or even pass on control over the request to a different controller.
+
+Controllers are the magic behind Happy; they're essentially **re-useable, self-contained, easily testable** web application classes that can be mounted at any URL you require. They can be as simple as serving a single response or as complex as a complete admin backend or blog engine. And finally, Happy Controllers are also **Rack applications**, so you can even use them anywhere you can mount Rack apps!
+
+
+### More Happy Features
+
+In addition to its fun and flexible approach to writing web applications, Happy boasts the following features, and more:
+
+* Run-time permission management provided by [Allowance](https://github.com/hmans/allowance).
+* A set of Happy Controllers making you super-productive, from serving static files to minifying JavaScript assets or even serving complete RESTful resources.
+* A set of view helpers including [simple_form](https://github.com/plataformatec/simple_form) inspired forms on auto-pilot, with full support for translations and localization through [I18n](https://github.com/svenfuchs/i18n).
+* Happy _loves_ Rack. You can mount Rack Middleware as well as pass control to another Rack application, just like that. Or use Happy Controllers from within other applications -- they're just Rack apps. And, of course, serve your Happy application through any Rack-compliant Rack server.
+
+
+### Happy is Opinionated Software
+
+Happy is opinionated software. Its design and functionality follow a certain set of opinions, a few of which are:
+
+* **The core framework should be very simple**. As described above, the entire framework revolves around two important classes (Happy::Controller and Happy::Context). Everything that's not directly related to the core framework should be provided by additional gems. (For example, anything that is view helper related has been moved to the [HappyHelpers](https://github.com/hmans/happy-helpers) gem, and the permission management code has been extracted to the [Allowance](https://github.com/hmans/allowance) gem.) Happy isn't trying to be a kitchen sink framework.
+* **Full-stack is boring**. Sure, it's nice if your framework of choice is holding your hands almost every step you go, but it's when you get to that point where you want to do something _differently_ from what your framework provides to you that you'll start hitting walls. For example, Happy doesn't generate data layer code for you; you're expected (and free to) simply use any ORM (or whatever) you desire, if any. For example, adding [Mongoid](http://mongoid.org/) to your Happy project is just two lines of code. Don't worry, we'll provide recipes; you don't need generators for that kind of stuff.
+* **Routing sucks**. Pretty much all other Ruby web application frameworks go to great lengths to map incoming requests to code through regular expressions (or DSLs allowing you to specify routes that are then compiled to regular expressions behind the scenes.) It's a very fast, but somewhat inflexible approach.
+* **Objects are awesome**. Frameworks like Rails are, technically speaking, object-oriented, but really only use classes mostly as containers for code. Requests are mapped (through the aforementioned routes) to controller classes, which are then instantiated and passed control to. It works, but it's also really boring. Objects are fun! Happy uses the request URL as a roadmap through your application's object graph. It allows you to think of your application as a nested tree of _things_.
+
+If you find that you agree with these, you're going to _love_ building Happy web applications.
+
+
+## Current Status
+
+Happy is being extracted from a web application that I've been working on. I'm trying to get a first, hopefully somewhat stable release out of the door some time during June 2012.
+
+FWIW, here's a list of important things still missing right now:
+
+* Nicer error pages for 404s, 401s etc.
+* Better logging.
+* Improved view engine compatibility.
+
+Hendrik Mans, hendrik@mans.de

data/happy.gemspec

@@ -17,7 +17,7 @@ Gem::Specification.new do |gem|
 
   gem.add_dependency 'activesupport', '~> 3.1'
   gem.add_dependency 'rack', '~> 1.4'
-  gem.add_dependency 'happy-helpers', '~> 0.1.0.pre6'
+  gem.add_dependency 'happy-helpers', '~> 0.1.0.pre8'
   gem.add_dependency 'allowance', '>= 0.1.1'
 
   gem.add_dependency 'happy-cli', '>= 0.1.0.pre1'

data/lib/happy/context.rb

@@ -5,7 +5,7 @@ module Happy
   class Context
     include Helpers
 
-    attr_reader   :request, :response, :remaining_path
+    attr_reader   :request, :response, :previous_path, :remaining_path
     attr_accessor :layout, :controller
     delegate      :params, :session, :to => :request
 
@@ -13,6 +13,7 @@ module Happy
       @request    = request
       @response   = response
       @remaining_path = @request.path.split('/').reject {|s| s.blank? }
+      @previous_path = []
       @layout     = nil
       @controller = nil
     end

data/lib/happy/controller/routing.rb

@@ -31,7 +31,7 @@ module Happy
               name.scan(/:(\w+)/).flatten.each do |var|
                 request.params[var] = path_match.captures.shift
               end
-              remaining_path.shift
+              previous_path << remaining_path.shift
             end
 
             serve! instance_exec(&blk)

data/lib/happy/controller.rb

@@ -8,15 +8,22 @@ module Happy
     include Actions
     include Rackable
 
-    attr_reader :options, :env
+    attr_reader :options, :env, :root_path
 
-    delegate :request, :response, :remaining_path, :params, :session,
+    delegate :request, :response, :params, :session,
+      :previous_path, :remaining_path,
       :render, :url_for,
       :to => :context
 
     def initialize(env = {}, options = {}, &blk)
       @env = env
       @options = options
+
+      # Save a copy of the current path as this controller's root path.
+      @root_path = context.previous_path.dup
+
+      # Execute block against this instance, allowing the controller to
+      # provide a DSL for configuration.
       instance_exec(&blk) if blk
     end
 
@@ -26,6 +33,16 @@ module Happy
       end
     end
 
+  protected
+
+    def url(extras = nil)
+      url_for(previous_path, extras)
+    end
+
+    def root_url(extras = nil)
+      url_for(root_path, extras)
+    end
+
   private
 
     def context

data/lib/happy/ext/resources.rb

@@ -10,6 +10,10 @@ module Happy
       end
 
       class ResourceMounter < Happy::Controller
+        def root_url
+          super(options[:plural_name])
+        end
+
         def render_resource_template(name)
           render "#{options[:plural_name]}/#{name}.html.haml"
         end
@@ -95,10 +99,14 @@ module Happy
             :plural_name   => options[:class].to_s.tableize.pluralize
           }.merge(@options)
 
+        puts url
+
           path options[:plural_name] do
+        puts url
             get('new') { do_new }
 
             path :id do
+        puts url
               get         { do_show }
               post        { do_update }
               get('edit') { do_edit }

data/lib/happy/version.rb

@@ -1,3 +1,3 @@
 module Happy
-  VERSION = "0.1.0.pre9"
+  VERSION = "0.1.0.pre10"
 end

data/spec/controller_spec.rb

@@ -32,5 +32,82 @@ module Happy
         last_response.body.should == 'yay!'
       end
     end
+
+    describe '#url' do
+      it "returns the current URL" do
+        def app
+          build_controller do
+            path 'foo' do
+              path 'bar' do
+                "My URL is #{url}"
+              end
+
+              "My URL is #{url}"
+            end
+
+            "My URL is #{url}"
+          end
+        end
+
+        response_for { get '/' }.body.should == 'My URL is /'
+        response_for { get '/foo' }.body.should == 'My URL is /foo'
+        response_for { get '/foo/bar' }.body.should == 'My URL is /foo/bar'
+      end
+
+      it "appends extra paths to the URL if provided" do
+        def app
+          build_controller do
+            path 'foo' do
+              url('bar')
+            end
+          end
+        end
+
+        response_for { get '/foo' }.body.should == "/foo/bar"
+      end
+    end
+
+    describe '#root_url' do
+      it "returns the controller's root URL" do
+        def app
+          root_url_printer = build_controller do
+            path 'bar' do
+              "My root URL is still #{root_url}"
+            end
+
+            "My root URL is #{root_url}"
+          end
+
+          build_controller do
+            path 'foo' do
+              run root_url_printer
+            end
+
+            run root_url_printer
+          end
+        end
+
+        response_for { get '/' }.body.should == 'My root URL is /'
+        response_for { get '/foo' }.body.should == 'My root URL is /foo'
+        response_for { get '/foo/bar' }.body.should == 'My root URL is still /foo'
+      end
+
+      it "appends extra paths to the root URL if provided" do
+        def app
+          some_controller = build_controller do
+            root_url('bar')
+          end
+
+          build_controller do
+            path 'foo' do
+              run some_controller
+            end
+          end
+        end
+
+        response_for { get '/foo' }.body.should == "/foo/bar"
+      end
+    end
+
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: happy
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre9
+  version: 0.1.0.pre10
   prerelease: 6
 platform: ruby
 authors:
@@ -13,7 +13,7 @@ date: 2012-06-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
-  requirement: &70100544312640 !ruby/object:Gem::Requirement
+  requirement: &70168378480640 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,10 +21,10 @@ dependencies:
         version: '3.1'
   type: :runtime
   prerelease: false
-  version_requirements: *70100544312640
+  version_requirements: *70168378480640
 - !ruby/object:Gem::Dependency
   name: rack
-  requirement: &70100544261560 !ruby/object:Gem::Requirement
+  requirement: &70168378479020 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -32,21 +32,21 @@ dependencies:
         version: '1.4'
   type: :runtime
   prerelease: false
-  version_requirements: *70100544261560
+  version_requirements: *70168378479020
 - !ruby/object:Gem::Dependency
   name: happy-helpers
-  requirement: &70100544255780 !ruby/object:Gem::Requirement
+  requirement: &70168378476360 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 0.1.0.pre6
+        version: 0.1.0.pre8
   type: :runtime
   prerelease: false
-  version_requirements: *70100544255780
+  version_requirements: *70168378476360
 - !ruby/object:Gem::Dependency
   name: allowance
-  requirement: &70100544253560 !ruby/object:Gem::Requirement
+  requirement: &70168378462860 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,10 +54,10 @@ dependencies:
         version: 0.1.1
   type: :runtime
   prerelease: false
-  version_requirements: *70100544253560
+  version_requirements: *70168378462860
 - !ruby/object:Gem::Dependency
   name: happy-cli
-  requirement: &70100544251160 !ruby/object:Gem::Requirement
+  requirement: &70168378462140 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -65,10 +65,10 @@ dependencies:
         version: 0.1.0.pre1
   type: :runtime
   prerelease: false
-  version_requirements: *70100544251160
+  version_requirements: *70168378462140
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &70100544249920 !ruby/object:Gem::Requirement
+  requirement: &70168378461380 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -76,10 +76,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70100544249920
+  version_requirements: *70168378461380
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70100544248940 !ruby/object:Gem::Requirement
+  requirement: &70168378460640 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -87,10 +87,10 @@ dependencies:
         version: '2.8'
   type: :development
   prerelease: false
-  version_requirements: *70100544248940
+  version_requirements: *70168378460640
 - !ruby/object:Gem::Dependency
   name: rspec-html-matchers
-  requirement: &70100544247880 !ruby/object:Gem::Requirement
+  requirement: &70168378459800 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -98,10 +98,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70100544247880
+  version_requirements: *70168378459800
 - !ruby/object:Gem::Dependency
   name: rack-test
-  requirement: &70100544246800 !ruby/object:Gem::Requirement
+  requirement: &70168378458420 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -109,10 +109,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70100544246800
+  version_requirements: *70168378458420
 - !ruby/object:Gem::Dependency
   name: watchr
-  requirement: &70100544245520 !ruby/object:Gem::Requirement
+  requirement: &70168378454200 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -120,7 +120,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70100544245520
+  version_requirements: *70168378454200
 description: A happy little toolkit for writing web applications.
 email:
 - hendrik@mans.de