georgi-kontrol 0.1 → 0.1.1

data/README.md

@@ -2,22 +2,50 @@ Kontrol - a micro framework
 ===========================
 
 Kontrol is a small web framework written in Ruby, which runs directly
-on Rack. It provides a simple pattern matching algorithm for routing
+on [Rack][5]. It provides a simple pattern matching algorithm for routing
 and uses GitStore as data storage.
 
+All examples can be found in the [examples folder][3] of the kontrol
+project, which is hosted on [this github page][4].
+
 ## Quick Start
 
-Create a config.ru file and try this little "Hello World" app:
+Create a file named `hello_world.ru`:
 
     require 'kontrol'
-
-    run Kontrol::Application.new do
-      get '/' do
-        "Hello World!" 
+    
+    class HelloWorld < Kontrol::Application
+      map do
+        get '/' do
+          "Hello World!" 
+        end
       end
     end
+        
+    run HelloWorld.new
+    
+Now run:
+
+    rackup hello_world.ru
+
+Browse to `http://localhost:9292` and you will see "Hello World".
 
-Now run `rackup` and browse to `http://localhost:9292` you will see the "Hello World".
+
+## Features
+
+Kontrol is just a thin layer on top of Rack. It provides a routing
+algorithm, a simple template mechanism and some convenience stuff to
+work with [GitStore][1].
+
+A Kontrol application is a class, which provides some context to the
+defined actions. You will probably use these methods:
+
+* request: the Rack request object
+* response: the Rack response object
+* params: union of GET and POST parameters
+* cookies: shortcut to request.cookies
+* session: shortcut to `request.env['rack.session']`
+* redirect(path): renders a redirect response to specified path
 
 
 ## Routing
@@ -25,51 +53,82 @@ Now run `rackup` and browse to `http://localhost:9292` you will see the "Hello W
 Routing is just as simple as using regular expressions with
 groups. Each group will be provided as argument to the block.
 
-Some examples:
+Create a file named `routing.ru`:
 
     require 'kontrol'
-
-    run Kontrol::Application.new do
-      get '/pages/(.*)' do |name|
-        "This is the page #{name}!"
-      end
-
-      get '/(\d*)/(\d*)', :content_type => 'text/html' do |year, month|
-        "Archive for #{year} #{month}"
+    
+    class Routing < Kontrol::Application
+      map do
+        get '/pages/(.*)' do |name|
+          "This is the page #{name}!"
+        end
+    
+        get '/(\d*)/(\d*)' do |year, month|
+          "Archive for #{year}/#{month}"
+        end
       end
     end
+    
+    run Routing.new
+    
+Now run this application:
+
+    rackup routing.ru
 
-The second route has the requirement, that the `content-type` header
-should be 'text/html'.
+
+You will now see, how regex groups and parameters are related. For
+example if you browse to `localhost:9292/2008/12`, the app will
+display `Archive for 2008/12`.
 
 
 ## Nested Routes
 
-You may nest your routes like you want:
+Routes can be nested. This way you can avoid repeating patterns and
+define handlers for a set of HTTP verbs. Each handler will be called
+with the same arguments.
 
     require 'kontrol'
-
-    run Kontrol::Application.new do
-      map '/blog' do
-        get '/archives' do
-          "The archives!"
+    
+    class Nested < Kontrol::Application
+      map do
+        map '/blog' do
+          get '/archives' do
+            "The archives!"
+          end
+        end
+        
+        map '/(.*)' do
+          get do |path|
+            "<form method='post'><input type='submit'/></form>"
+          end
+          
+          post do |path|
+            "You posted to #{path}"
+          end
         end
       end
     end
+    
+    run Nested.new
 
-This app can be reached at '/blog/archives'.
+Now run this app like:
 
+    rackup nested.ru
+    
+The second route catches all paths except the `/blog` route. Inside
+the second route there are two different handlers for `GET` and `POST`
+actions.
 
-## Storing your data in a git repository
+So if you browse to `/something`, you will see a submit button. After
+submitting you will see the result of the second handler.
 
-Using GitStore for your code and data is a convenient way for
-developing small scale apps. The whole repository is loaded into the
-memory and any change in the repository is reflected immediately in
-you in-memory copy.
+## Templates
 
-Just init a new repo: `git init`
+Rendering templates is as simple as calling a template file with some
+parameters, which are accessible inside the template as instance
+variables. Additionally you will need a layout template.
 
-Now we create a template named `templates/layout.rhtml`:
+Create a template named `templates/layout.rhtml`:
 
     <html>
       <body>
@@ -82,32 +141,86 @@ And now another template named `templates/page.rhtml`:
     <h1><%= @title %></h1>
     <%= @body %>
 
-Now we create a Markdown file name `pages/index.md`:
+Create a templates.ru file:
 
-    Hello World from **Markdown** !
+    require 'kontrol'
+    
+    class Templates < Kontrol::Application
+      map do
+        get '/(.*)' do |name|
+          render "page.rhtml", :title => name.capitalize, :body => "This is the body!"
+        end
+      end
+    end
+    
+    run Templates.new
 
+Now run this example:
 
-Create a config.ru file:
+    rackup templates.ru
 
-    require 'kontrol'
+If you browse to any path on `localhost:9292`, you will see the
+rendered template. Note that the title and body parameters have been
+passed to the `render` call.
+
+
+## Using GitStore
+
+[GitStore][1] is another library, which allows you to store code and
+data in a convenient way in a git repository. The repository is
+checked out into memory and any data may be saved back into the
+repository.
+
+Install [GitStore][1] and [Grit][2] by:
+
+    $ gem sources -a http://gems.github.com (you only have to do this once)
+    $ sudo gem install mojombo-grit georgi-git_store
 
-    run Kontrol::Application.new do
-      get '/(.*)' do |name|
-        body = store["pages/#{name}.md"]
-        render "page.rhtml", :title => name.capitalize, :body => body
+We create a Markdown file name `pages/index.md`:
+
+    Hello World
+    ===========
+
+    This is the **Index** page!
+
+We have now a simple page, which should be rendered as response. We
+create a simple app in a file `git_app.ru`:
+
+    require 'kontrol'
+    require 'bluecloth'
+    
+    class GitApp < Kontrol::Application
+      map do
+        get '/(.*)' do |name|
+          BlueCloth.new(store['pages', name + '.md']).to_html
+        end
       end
     end
+    
+    run GitApp.new
 
 Add all these files to your repo:
 
-    git add templates/layout.rhtml
-    git add templates/page.rhtml
+    git init
     git add pages/index.md
-    git add config.ru
-    git commit -m 'added templates and config.ru'
+    git commit -m 'init'
+
+Run the app:
+
+    rackup git_app.ru
+
+Browse to `http://localhost:9292/index` and you will see the rendered
+page generated from the markdown file.
 
-Now just run `rackup` and browse to `http://localhost:9292/index`
+This application runs straight from the git repository. You can delete
+all files except the rackup file and the app will still serve the page
+from your repo.
 
-You will see the rendered template with the inserted content of the
-Markdown file.
 
+[1]: http://github.com/georgi/git_store
+[2]: http://github.com/mojombo/grit
+[3]: http://github.com/georgi/kontrol/tree/master/examples
+[4]: http://github.com/georgi/kontrol
+[5]: http://github.com/chneukirchen/rack
+[6]: http://github.com/chneukirchen/rack/tree/master/lib/rack/request.rb
+[7]: http://github.com/chneukirchen/rack/tree/master/lib/rack/response.rb

data/examples/git_app.ru

@@ -0,0 +1,12 @@
+require 'kontrol'
+require 'bluecloth'
+
+class GitApp < Kontrol::Application
+  map do
+    get '/(.*)' do |name|
+      BlueCloth.new(store['pages', name + '.md']).to_html
+    end
+  end
+end
+
+run GitApp.new

data/examples/hello_world.ru

@@ -0,0 +1,11 @@
+require 'kontrol'
+
+class HelloWorld < Kontrol::Application
+  map do
+    get '/' do
+      "Hello World!" 
+    end
+  end
+end
+
+run HelloWorld.new

data/examples/nested.ru

@@ -0,0 +1,23 @@
+require 'kontrol'
+
+class Nested < Kontrol::Application
+  map do
+    map '/blog' do
+      get '/archives' do
+        "The archives!"
+      end
+    end
+    
+    map '(.*)' do
+      get do |path|
+        "<form method='post'><input type='submit'/></form>"
+      end
+      
+      post do |path|
+        "You called #{path}"
+      end
+    end
+  end
+end
+
+run Nested.new

data/examples/pages/index.md

@@ -0,0 +1,5 @@
+Hello World
+===========
+
+This is the **Index** page!
+

data/examples/routing.ru

@@ -0,0 +1,15 @@
+require 'kontrol'
+
+class Routing < Kontrol::Application
+  map do
+    get '/pages/(.*)' do |name|
+      "This is the page #{name}!"
+    end
+
+    get '/(\d*)/(\d*)' do |year, month|
+      "Archive for #{year}/#{month}"
+    end
+  end
+end
+
+run Routing.new

data/examples/templates.ru

@@ -0,0 +1,11 @@
+require 'kontrol'
+
+class Templates < Kontrol::Application
+  map do
+    get '/(.*)' do |name|
+      render "page.rhtml", :title => name.capitalize, :body => "This is the body!"
+    end
+  end
+end
+
+run Templates.new

data/examples/templates/layout.rhtml

@@ -0,0 +1,5 @@
+<html>
+  <body>
+    <%= @content %>
+  </body>
+</html>

data/examples/templates/page.rhtml

@@ -0,0 +1,2 @@
+<h1><%= @title %></h1>
+<%= @body %>

data/lib/kontrol.rb

@@ -3,7 +3,8 @@ require 'rack'
 require 'erb'
 require 'yaml'
 require 'logger'
-require 'git_store'
+
+begin; require 'git_store'; rescue LoadError; end
 
 require 'kontrol/helpers'
 require 'kontrol/template'

data/lib/kontrol/application.rb

@@ -18,7 +18,7 @@ module Kontrol
 
     config_reader 'assets.yml', :javascript_files, :stylesheet_files
 
-    def initialize(options = {}, &block)
+    def initialize(options = {})
       options.each do |k, v|
         send "#{k}=", v
       end
@@ -26,11 +26,14 @@ module Kontrol
       @mtime = {}
       @last_mtime = Time.now
       @path = File.expand_path('.')
-      
+
+      initialize_repo if defined?(GitStore)
+    end
+
+    def initialize_repo      
       @store = GitStore.new(path)
       @store.load
-      
-      map(&block) if block
+    rescue Grit::InvalidGitRepositoryError      
     end
 
     def assets
@@ -77,14 +80,14 @@ module Kontrol
       end
     end
 
-    def camelize(str)
-      str.gsub(/\/(.?)/) { "::" + $1.upcase }.gsub(/(^|_)(.)/) { $2.upcase }
-    end
-
     # Render template with given variables.
     def render_template(file, vars)
-      templates[file] or raise "template #{file} not found"
-      Template.render(templates[file], self, file, vars)
+      if store
+        template = templates[file] or raise "template #{file} not found"
+      else
+        template = ERB.new(File.read("#{path}/templates/#{file}"))
+      end
+      Template.render(template, self, file, vars)
     end
 
     def render_layout(vars)
@@ -154,21 +157,35 @@ module Kontrol
       MIME_TYPES[ext] || 'text/html'
     end
 
-    def map(&block)
-      @map = Builder.new(&block)
+    class << self
+
+      def map(&block)
+        @map = Builder.new(&block)
+      end
+
+      def get_map
+        @map
+      end
+      
+    end
+
+    def find_map
+      if store and store['map.rb']
+        store['map.rb']
+      else
+        self.class.get_map
+      end
     end
 
     def call(env)
       Thread.current['request'] = Rack::Request.new(env)
       Thread.current['response'] = Rack::Response.new([], nil, { 'Content-Type' => '' })
 
-      check_reload
+      check_reload if store
       
       env['kontrol.app'] = self
 
-      map = @map || store['map.rb'] or raise "no map defined"
-
-      status, header, body = map.call(env)
+      status, header, body = find_map.call(env)
 
       response.status = status if response.status.nil?
       response.header.merge!(header)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: georgi-kontrol
 version: !ruby/object:Gem::Version 
-  version: "0.1"
+  version: 0.1.1
 platform: ruby
 authors: 
 - Matthias Georgi
@@ -32,6 +32,16 @@ files:
 - lib/kontrol/router.rb
 - lib/kontrol/template.rb
 - test/application_spec.rb
+- examples/routing.ru
+- examples/pages
+- examples/pages/index.md
+- examples/git_app.ru
+- examples/templates.ru
+- examples/templates
+- examples/templates/page.rhtml
+- examples/templates/layout.rhtml
+- examples/nested.ru
+- examples/hello_world.ru
 has_rdoc: true
 homepage: http://github.com/georgi/kontrol
 post_install_message: