happy 0.1.0.pre28 → 0.1.0

data/README.md

@@ -8,13 +8,15 @@ Happy is a toolkit for developing web applications using Ruby. Inspired by both
 
 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 suspiciously fun way of building your application.
 
+**For an introduction, please check out the [The Happy Book of Happy](http://rdoc.info/github/hmans/happy/master/file/TUTORIAL.md).** For additional examples, check out the [example application](https://github.com/hmans/happy/tree/master/example).
+
 ## Installing
 
 Happy is available as a RubyGem, so just install it through `gem install happy` (or add it to your project's `Gemfile`. You know the drill.)
 
 ## Usage
 
-* [The Happy Book of Happy](https://github.com/hmans/happy/blob/master/TUTORIAL.md)
+* [The Happy Book of Happy](http://rdoc.info/github/hmans/happy/master/file/TUTORIAL.md)
 * [Reference Documentation](http://rdoc.info/github/hmans/happy/master/)
 
 ## Reporting Bugs & Contributing

data/TUTORIAL.md

@@ -1,3 +1,348 @@
 # The Happy Book of Happy
 
-Lorem to the ipsum.
+Welcome to the Happy Book of Happy, an introduction on how to develop web applications using Happy, a cute little web application toolkit for Ruby! Let's get straight to it, shall we?
+
+
+----
+
+## The Basics
+
+### "Hello World" with Happy
+
+So, without further ado, here's the Happy version of "Hello World":
+
+``` ruby
+# config.ru
+require 'happy'
+
+class MyApp < Happy::Controller
+  def route
+    "Hello World"
+  end
+end
+
+run MyApp
+```
+
+You can run this example (assuming it's inside a file called config.ru) by simply issuing the `rackup` command. Try `rackup --help` for available options.
+
+
+### Happy Controllers
+
+So, the previous chapter's "Hello World" example isn't terribly exciting, but there's a couple of interesting things to note here.
+
+First of all, note how you're creating a subclass of `Happy::Controller`. That class is central to how Happy works; pretty much everything you do in Happy revolves around controllers.
+
+Unlike your may know it from frameworks like Ruby on Rails, controllers are really self-contained applications that describe behaviour. They can be very simple (simply rendering a string, like the example above), but also very complex (for example, they could provide a complete blog engine, or admin backend.)
+
+So here's some of the things a Happy controller can do:
+
+* serve a simple string-like response
+* render a template
+* process URL paths
+* pass control over the request to another controller (or Rack app)
+
+*Note for friends of Rack:* Happy is a very Rack-friendly framework. Happy controllers are also just Rack apps, so you can mount them anywhere that you can mount Rack apps (like inside another Rails application). Happy also happily mounts non-Happy Rack apps, so it works both ways. Life is good.
+
+
+### The `route` method
+
+Pretty much the most important part of any Happy controller is the `route` method. In your own controller classes, you're expected to override this method to implement your controller's request handling logic.
+
+And this is where Happy is very different from most other web frameworks: instead of dispatching incoming requests among a set of controller classes or actions, Happy will route each and every request -- no exceptions -- through your application controller's `route` method. It is then up to this method to decide on how to deal with the request.
+
+Let's take a look at some examples in the following chapters.
+
+
+### Handling paths
+
+In most web applications, you will probably want to serve different responses depending on the URL accessed. In Happy, you use the `on` method to define the behavior for specific URL paths. Here's a simple example:
+
+``` ruby
+class MyApp < Happy::Controller
+  def route
+    # When /foo is accessed, respond with 'bar!'
+    on 'foo' do
+      'bar!'
+    end
+
+    # Paths can be nested, of course:
+    on 'one' do
+      on 'two' do
+        'one and two!'
+      end
+
+      'just one!'
+    end
+    
+    'Try /foo, /one or /one/two!'
+  end
+end
+```
+
+In other words, `on` lets you provide code blocks that are only executed when a certain path has been requested. Note that `on` calls can be nested; also note that if one of these blocks returns just a string value, it will be rendered as the response.
+
+
+### Reacting on specific HTTP verbs
+
+While the `on` command doesn't care about the HTTP verb being used to make the request, there's also `on_get`, `on_post`, `on_put` and `on_delete`. Note that these can also be called without a path argument. Here's an example:
+
+``` ruby
+class MyApp < Happy::Controller
+  def route
+    on 'resource' do
+      on_get    { 'You accessed /resource using GET!' }
+      on_post   { 'You accessed /resource using POST!' }
+      on_put    { 'You accessed /resource using PUT!' }
+      on_delete { 'You accessed /resource using DELETE!' }
+    end
+    
+    'Try /resource with any HTTP verb!'
+  end
+end
+```
+
+### Setting headers
+
+You can use the `header` method to set any type of HTTP header for your response. Example:
+
+``` ruby
+# Set the 'Content-type' header to 'text/css'
+header :content_type, 'text/css'
+```
+
+There's a couple of shortcut methods available to set certain headers directly. Examples:
+
+```ruby
+content_type 'text/css'
+cache_control 'public, max-age=3600, must-revalidate'
+```
+
+For a complete list, please check the documentation for [`Happy::Controller::Actions`](http://rdoc.info/github/hmans/happy/master/Happy/Controller/Actions).
+
+
+### Rendering view templates
+
+Obviously, just serving simple strings isn't really what you want in most applications, so Happy also allows you to render view templates through myriad of available template engines. (Happy uses the [tilt](https://github.com/rtomayko/tilt) gem, so any template engine supported by tilt is also supported by Happy.)
+
+All template rendering is done through the `render` method. Simply pass the name of a template file. For example:
+
+``` ruby
+class MyApp < Happy::Controller
+  def route
+    on('info') { render 'info.erb' }
+    on('help') { render 'help.erb' }
+
+    render 'home.erb'
+  end
+end
+```
+
+The default directory Happy will look for view templates in is the `views/` subdirectory of your application. This is configurable, of course; more on configuration alter.
+
+
+### Using layouts
+
+Happy allows you to define a view template as a layout template, applying it to every response generated. Use the `layout` command to set it. For example:
+
+``` ruby
+class MyApp < Happy::Controller
+  def route
+    layout 'layouts/default.erb'
+
+    # From a previous example...
+    on('info') { render 'info.erb' }
+    on('help') { render 'help.erb' }
+
+    on('admin') do
+      # use a different layout inside the admin section
+      layout 'layouts/admin.erb'
+      render 'admin.erb'
+    end
+
+    render 'home.erb'
+  end
+end
+```
+
+The layout file itself should contain an invocation of `yield` where the inner part of the response should appear.
+
+
+### Adding view helpers
+
+In Happy, view templates are rendered within the scope of your controller (as opposed to a specific view context object), so any method from your controller will also be available in your views.
+
+It is advised, however, that you specifically declare helper methods using the `helper` command so that they are available to _all_ controllers. This is necessary if you modularize your applications into several different controller classes that share view files.
+
+Here's an example:
+
+``` ruby
+class MyApp < Happy::Controller
+  # You can provide a block that contains method definitions.
+  #
+  helpers do
+    def some_helper
+      'something useful'
+    end
+  end
+
+  # Alternatively, you can provide a module that contains your
+  # helper methods
+  #
+  helpers MyHelpers
+
+  def route
+    # home.erb contains calls to helper methods
+    render 'home.erb'
+  end
+end
+```
+
+
+### Serving responses explicitly
+
+You will have noticed by now that if a path block (or the `route` method itself) returns a simple string, it will be used for the response body. However, you can also serve responses explicitly using the `serve!` method. Example:
+
+``` ruby
+class MyApp < Happy::Controller
+  def route
+    serve! 'my response', :content_type => 'text/plain'
+  end
+end
+```
+
+Note that calling `serve!` will finish processing of the current request.
+
+### Passing control over the request to another controller or Rack app
+
+Happy allows you to modularize your application into several separate controller classes. For example, you could put your admin backend's code into a separate controller and then invoke it within the `/admin` path. For this, you would use the `run` command. Kinda like this:
+
+``` ruby
+class MyAdminController < Happy::Controller
+  def route
+    on 'users' do
+      # ...
+      # do some user admin stuff here
+    end
+
+    on 'articles' do
+      # ...
+      # do some articles admin stuff here
+    end
+
+    render 'admin/home.erb'
+  end
+end
+
+class MyApp < Happy::Controller
+  def route
+    on 'admin' do
+      run MyAdminController
+    end
+
+    render 'home.erb'
+  end
+end
+```
+
+Yup, this also means that you can build reusable controllers that you can distribute within gems for other Happy developers to use.
+
+
+----
+
+## Permission Managament
+
+### Setting and querying permissions
+
+Happy contains a light-weight run-time permission management system powered by the [Allowance](https://github.com/hmans/allowance) gem. Using the `can` object, you can declare (and later query) permissions at runtime.
+
+Example:
+
+``` ruby
+class MyApp < Happy::Controller
+  def setup_permissions
+    if current_user
+      # Logged in users can submit new stuff
+      can.submit!
+
+      # But only admin users can edit and delete it.
+      if current_user.is_admin?
+        can.edit!
+        can.delete!
+      end
+    end
+  end
+
+  def route
+    setup_permissions    
+
+    on 'submit' do
+      if can.submit?
+        render 'submit.erb'
+      else
+        redirect! '/login'
+      end
+    end
+
+    # Paths are defined dynamically, so the following is possible, too:
+    if can.edit?
+      on('edit') { render 'edit.erb' }
+    end
+
+    if can.delete?
+      on('delete') { render 'delete.erb' }
+    end
+
+    render 'home.erb'
+  end
+
+  def current_user
+    # ...a method returning the current user.
+  end
+end
+```
+
+### Permissions for specific objects
+_TODO_
+
+### ActiveModel integration
+_TODO_
+
+----
+
+## Controller configuration
+_TODO_
+
+----
+
+## Happy Recipes
+
+### Writing & Reading Session Data
+_TODO_
+
+### Setting & Reading Cookies
+_TODO_
+
+### Using HAML (and other view engines) in Happy
+_TODO_
+
+### Serving assets (stylesheets, JavaScript files etc.)
+_TODO_
+
+### Caching
+_TODO_
+
+### Dealing with users and authentication
+_TODO_
+
+### Using `ResourceController`
+_TODO_
+
+### Using `ActiveModelResourceController`
+_TODO_
+
+### Authenticating against Twitter, Facebook etc. using OmniAuth
+_TODO_
+
+### Handling image uploads using DragonFly
+_TODO_

data/lib/happy/controller.rb

@@ -106,7 +106,7 @@ module Happy
     #       def my_little_helper
     #         "something useful"
     #       end
-    #      end
+    #     end
     #
     def self.helpers(*args, &blk)
       args.flatten.each do |arg|

data/lib/happy/version.rb

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

metadata

@@ -1,8 +1,8 @@
 --- !ruby/object:Gem::Specification
 name: happy
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre28
-  prerelease: 6
+  version: 0.1.0
+  prerelease: 
 platform: ruby
 authors:
 - Hendrik Mans
@@ -13,7 +13,7 @@ date: 2012-06-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
-  requirement: &70101332488280 !ruby/object:Gem::Requirement
+  requirement: &70249795375520 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,10 +21,10 @@ dependencies:
         version: '3.1'
   type: :runtime
   prerelease: false
-  version_requirements: *70101332488280
+  version_requirements: *70249795375520
 - !ruby/object:Gem::Dependency
   name: rack
-  requirement: &70101332487780 !ruby/object:Gem::Requirement
+  requirement: &70249795375020 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -32,10 +32,10 @@ dependencies:
         version: '1.4'
   type: :runtime
   prerelease: false
-  version_requirements: *70101332487780
+  version_requirements: *70249795375020
 - !ruby/object:Gem::Dependency
   name: allowance
-  requirement: &70101332487320 !ruby/object:Gem::Requirement
+  requirement: &70249795374560 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +43,10 @@ dependencies:
         version: 0.1.1
   type: :runtime
   prerelease: false
-  version_requirements: *70101332487320
+  version_requirements: *70249795374560
 - !ruby/object:Gem::Dependency
   name: tilt
-  requirement: &70101332486860 !ruby/object:Gem::Requirement
+  requirement: &70249795374100 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -54,10 +54,10 @@ dependencies:
         version: '1.3'
   type: :runtime
   prerelease: false
-  version_requirements: *70101332486860
+  version_requirements: *70249795374100
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &70101345428800 !ruby/object:Gem::Requirement
+  requirement: &70249795373720 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -65,10 +65,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70101345428800
+  version_requirements: *70249795373720
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70101345428260 !ruby/object:Gem::Requirement
+  requirement: &70249795373180 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -76,10 +76,10 @@ dependencies:
         version: '2.8'
   type: :development
   prerelease: false
-  version_requirements: *70101345428260
+  version_requirements: *70249795373180
 - !ruby/object:Gem::Dependency
   name: rspec-html-matchers
-  requirement: &70101345427840 !ruby/object:Gem::Requirement
+  requirement: &70249795372760 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -87,10 +87,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70101345427840
+  version_requirements: *70249795372760
 - !ruby/object:Gem::Dependency
   name: rack-test
-  requirement: &70101345427380 !ruby/object:Gem::Requirement
+  requirement: &70249795372300 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -98,10 +98,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70101345427380
+  version_requirements: *70249795372300
 - !ruby/object:Gem::Dependency
   name: watchr
-  requirement: &70101345426960 !ruby/object:Gem::Requirement
+  requirement: &70249795371880 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -109,7 +109,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70101345426960
+  version_requirements: *70249795371880
 description: A happy little toolkit for writing web applications.
 email:
 - hendrik@mans.de
@@ -179,9 +179,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
-  - - ! '>'
+  - - ! '>='
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.11