ramaze 2011.12.28 → 2012.03.07

data/guide/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2006 - 2012, Michael Fellinger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/guide/general/contributing.md

@@ -4,6 +4,10 @@ Everybody is welcome to contribute to Ramaze and/or the guide. This guide is
 meant to be a starting point for those interested in contributing code, writing
 documentation or advertising Ramaze.
 
+A small guide containing details about the general workflow of Github projects
+can be found [here][workflow]. If you're new to Github/Git it's recommended to
+read this guide (as well as the various Github help pages).
+
 ## Coding Standards
 
 * 2 spaces per indentation level for Ruby code.
@@ -64,11 +68,22 @@ request][pull requests] page on Github.
 
 ## Writing Documentation
 
-The documentation (both the guides and the API documentation) use
+The documentation (both the guides and the API documentation) uses
 [Markdown][markdown] as its markup engine. All the text should be written in
 English. Try writing as clear as possible and remove as much spelling/grammar
 errors as you can find before submitting it to Ramaze.
 
+When writing guides (or modifying existing ones) make sure that each line is no
+longer than 80 characters and that there is no trailing whitespace in the file.
+If you're using Vim you can configure it to automatically insert
+characters/words on new lines using the following settings:
+
+    set nowrap
+    set tw=80
+
+Other editors will have different settings so refer to the documentation of your
+editor for more information.
+
 Linking to classes and methods can be done by wrapping the namespace/method in
 ``{}``:
 
@@ -79,11 +94,68 @@ instead:
 
     {file:path/to/file Title}
 
+<div class="note todo">
+    <p>
+        Keep in mind that the above syntax for linking to files does not work
+        for files located outside of the guide/ directory.
+    </p>
+</div>
+
 Markdown files should be lower cased, spaces should be replaced with
 underscores. Examples of this are ``ramaze_command.md`` and
 ``special_thanks.md``. Just like the Ruby code the text for the guide should be
 wrapped at 80 characters.
 
+### Testing Documentation
+
+After you've made some changes you'll have to test it. Building the
+documentation can be done in two different ways, either by building the Ramaze
+only documentation or the documentation of both Ramaze and Innate.
+
+Lets assume that you don't have a local copy of Ramaze' Git repository yet, you
+can add such a copy by running the following Git command:
+
+    $ git clone git://github.com/Ramaze/ramaze.git
+
+Once the cloning process has been completed you'll have to ``cd`` into the
+"ramaze" directory. If you happen to have RVM installed doing this will most
+likely trigger a warning about an untrusted .rvmrc file being detected. If you
+decide to trust this file RVM will load it and automatically install all the
+required gems (these can be found in the .gems file in the root directory of the
+repository).
+
+If you don't have RVM installed you'll have to install the dependencies of
+Ramaze yourself, but fear not for it is very easy and only requires you to run
+the following command:
+
+    $ rake setup
+
+Similar to using RVM this command installs all required gems with a small
+difference: it only installs what is supported by your platform. For example, on
+OS X the "localmemcache" gem is not installed since it doesn't support this
+operating system.
+
+Once installed you can build the documentaton using the command ``rake yard``.
+This command optionally takes a parameter that can be used to specify the path
+to the **lib** directory of Innate. When specifying this path Innate's
+documentation will be included as well (this is what we use for
+<http://ramaze.net/>).
+
+Of course for this to work you'll need to have a local copy of Innate as well.
+Assuming you're still in the "ramaze" directory you can get a local copy of
+Innate by running the following commands:
+
+    $ cd ..
+    $ git clone git://github.com/Ramaze/innate.git
+    $ cd ramaze
+
+Now run the ``rake yard`` task as following:
+
+    $ rake yard[../innate/lib]
+
+Once the documentation has been built (either by including or excluding Innate)
+you can simply point your browser to the "doc" directory to view it.
+
 ## Spreading The Word
 
 Maybe you're not familiar with Git or perhaps you just don't have the time to
@@ -106,3 +178,4 @@ file and a PNG of which both are displayed below.
 [cc license]: http://creativecommons.org/licenses/by-sa/3.0/
 [logo svg]: _static/logo.svg "The logo in SVG format"
 [logo png]: _static/logo.png "The logo in PNG format"
+[workflow]: https://github.com/thessaloniki/rb/wiki/Workflow

data/guide/general/helpers.md

@@ -74,3 +74,17 @@ load all helpers the Ramaze way.
 * {Ramaze::Helper::Upload}: uploading files made easy.
 * {Ramaze::Helper::UserHelper}: authenticate users using a model.
 * {Ramaze::Helper::XHTML}
+
+## Innate Helpers
+
+Note that you may also find some popular helpers, that are used by default in 
+Ramaze, under the Innate project.
+
+* {Innate::Helper::Aspect}: provides before/after wrappers for actions.
+* {Innate::Helper::CGI}: gives shortcuts to some CGI methods.
+* {Innate::Helper::Flash}: gives simple access to session.flash. 
+* {Innate::Helper::Link}: provides the path to a given Node and action.
+* {Innate::Helper::Redirect}: provides the request redirect, raw_redirect 
+and respond convenience methods. 
+* {Innate::Helper::Render}: provides variants for partial, custom, full 
+view rendering.

data/guide/general/middlewares.md

@@ -1,10 +1,12 @@
 # Rack Middlewares
 
-Ramaze is a Rack based framework and thus allows you to create so called
-middlewares. Middlewares are basically classes that can be used to intercept the
-communication between Rack, Ramaze and the visitor as well as providing common
-functionality such as logging of requests. The flow of a Rack request (including
-middlewares) looks as following::
+Ramaze is a Rack based framework and thus allows you to create so called Rack
+middlewares. Middlewares are basically objects that are stacked together
+in order to intercept and process sequentially each incoming request and outgoing
+response between Rack and Ramaze. You can think of a collection of middlewares
+as a stack at whose bottom lies your Ramaze app.
+
+The flow of a Rack request (including middlewares) looks as following::
 
     Request --> Server (Thin, Unicorn, etc) --> Rack --> Middleware(s) -->
     Ramaze  --> Controller
@@ -81,20 +83,37 @@ banned". Our final middleware looks like the following:
 ## Using Middlewares
 
 Now it's time to tell Ramaze to actually use the middleware. This can be done
-by calling Ramaze#middleware!. This method takes a block that defines what
-middlewares to use for what environment. Assuming we're dunning in "dev" mode
-our call will look like the following:
+by calling Ramaze#middleware!. This method accepts a block in which one defines
+which middlewares to use for a specific mode and the name for this Ramaze mode
+(Ramaze comes with "live" and "dev").
+
+In the block you can call two Innate#MiddlewareCompiler methods
+```use()``` and ```run()```. The ```use()``` method is used in order to add and
+configure a middleware, while ```run()``` is used to determine what class is used
+to run our Ramaze application. Unless you're using a custom class this should
+always be set to {Ramaze::AppMap}.
+
+Assuming we're running in "dev" mode our call will look like the following:
 
     Ramaze.middleware! :dev do |m|
       m.use(Banlist)
       m.run(Ramaze::AppMap)
     end
 
-When calling the ``middleware!()`` method it's first argument should be a
-development mode to use (Ramaze comes with "live" and "dev"), the method also
-accepts a block which is used to determine what middlewares to use and to run
-Ramaze ({Ramaze::AppMap}). In this block you can call two methods, use() and
-run(). The first method is used to add a middleware and configure it, the run()
-method is used to determine what class is used to run our Ramaze application.
-Unless you're using a custom class this should always be set to
-{Ramaze::AppMap}.
+Note that when you use Ramaze#middleware! you also replace the previously setup
+stack of middlewares. Therefore in order to add your new middleware on top of
+the existing ones you either have to read-in each one using
+``Innate#MiddlewareCompiler#middlewares`` and re-add it to the newly created
+middleware stack or simply copy (lets say in your app.rb) what has been setup
+inside ``lib/ramaze.rb``.
+
+	current_mw = Ramaze.middleware(:dev).middlewares
+	Ramaze.middleware! :dev do |mode|
+  	  current_mw.each do |mw|
+	    mode.use(mw[0],*mw[1], &mw[2]) # middleware, args, block
+	  end
+	
+	  mode.use(Banlist)
+	  mode.run(Ramaze::AppMap)
+	end
+	

data/guide/general/sessions.md

@@ -19,6 +19,36 @@ session until the client's session is destroyed (or the data is removed) it's
 best to use session, if you only want to store something until the client is
 redirected to another page (or just visits a page himself) you should use flash.
 
+## Changing Drivers
+
+Out of the box Ramaze uses the driver {Ramaze::Cache::LRU}. This driver
+stores all session related data in the memory of the current process. While this
+is fine during development it's something you most likely don't want to use in a
+multi process based environment as data stored in a process' memory isn't
+shared. To work around this you can use an alternative driver, such a driver can
+be set as following:
+
+    Ramaze::Cache.options.session = Ramaze::Cache::MemCache
+
+This particular example tells Ramaze to use Memcached for storing session
+related data. Where you set this doesn't really matter as long as it's done
+before calling ``Ramaze.start``. Generally you'd want to put this in a
+configuration file that's loaded in your app.rb file, if your application is a
+small one you can just put it in the app.rb file directly.
+
+## Available Drivers
+
+* {Ramaze::Cache::Sequel}
+* {Ramaze::Cache::LRU}
+* {Ramaze::Cache::MemCache}
+* {Ramaze::Cache::Redis}
+* {Ramaze::Cache::LocalMemCache}
+* {Innate::Cache::FileBased}
+* {Innate::Cache::DRb}
+* {Innate::Cache::Marshal}
+* {Innate::Cache::Memory}
+* {Innate::Cache::YAML}
+
 ## The Session Object
 
 As mentioned earlier session is used for data that should be stored until the
@@ -61,7 +91,7 @@ has a few extra methods besides [] and []=. These methods are delete(), clear(),
 flush(), resid!() and sid(). We're not going to cover all methods but we will
 look at the delete() and resid() methods.
 
-## Session.delete
+### session.delete
 
 The method Session.delete can be used to remove a chunk of data from the
 client's session. In order to delete our amount of visits all we'd have to do
@@ -72,7 +102,7 @@ is the following:
 From this point on the "visits" key is set to nil until the user visits the
 index page again.
 
-## Session.resid!
+### session.resid!
 
 Session.resid! can be used to regenerate the client's session ID without
 destroying the session data. This method is extremely useful for authentication
@@ -83,16 +113,14 @@ following to be done:
 
     session.resid!
 
-## The Flash
+## Flashdata
 
-First of all, this has nothing to do with Adobe's Flash or
-[The Flash][the flash]. Flashdata is a form of session data that is removed as
-soon as the client requests a new resource. This means that if something is
-stored in the flash and the user is redirected the data will be automatically
-removed. One of the things the flash data can be used for is storing
-notifications that are displayed if a blog post has been saved successfully.
-Storing data in the flash works similar to storing data in the session and can
-be done by calling the flash object:
+Flashdata is a form of session data that is removed as soon as the client
+requests a new resource. This means that if something is stored in the flash and
+the user is redirected the data will be automatically removed. One of the things
+the flash data can be used for is storing notifications that are displayed if a
+blog post has been saved successfully.  Storing data in the flash works similar
+to storing data in the session and can be done by calling the flash object:
 
     flash[:message] = "Hello, Ramaze!"
 
@@ -137,5 +165,3 @@ displayed because the flash data isn't there yet. As soon as the client visits
 "Hello, Ramaze!" would be displayed. Refreshing the page would clear the flash
 data and the message would no longer be displayed until the client visits
 /set\_message again.
-
-[the flash]: http://en.wikipedia.org/wiki/The_Flash_(comic_book)

data/lib/proto/layout/default.xhtml

@@ -45,7 +45,7 @@
 
             <footer id="footer">
                 <p>
-                    Ramaze is free software and is licensed under the Ruby license.<br />
+                    Ramaze is free software and is licensed under the MIT license.<br />
                     All textual content is licensed under a 
                     <a href="http://creativecommons.org/licenses/by-nc-sa/3.0/">
                         Creative Commons license.

data/lib/ramaze.rb

@@ -1,5 +1,5 @@
 #          Copyright (c) 2009 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
+# All files in this distribution are subject to the terms of the MIT license.
 
 # Namespace for Ramaze
 #

data/lib/ramaze/cache.rb

@@ -1,5 +1,5 @@
 #          Copyright (c) 2009 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
+# All files in this distribution are subject to the terms of the MIT license.
 require 'innate/cache'
 
 module Ramaze

data/lib/ramaze/cache/localmemcache.rb

@@ -1,5 +1,5 @@
 #          Copyright (c) 2009 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
+# All files in this distribution are subject to the terms of the MIT license.
 
 require 'localmemcache'
 

data/lib/ramaze/cache/lru.rb

@@ -1,5 +1,5 @@
 #          Copyright (c) 2009 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
+# All files in this distribution are subject to the terms of the MIT license.
 
 module Ramaze
   class Cache

data/lib/ramaze/controller.rb

@@ -1,5 +1,5 @@
 #          Copyright (c) 2009 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
+# All files in this distribution are subject to the terms of the MIT license.
 
 module Ramaze
   ##

data/lib/ramaze/dependencies.rb

@@ -13,7 +13,7 @@ module Ramaze
   # Array containing the names and versions of all the gems required by Ramaze
   # along with the name of how the gem should be required.
   DEPENDENCIES = [
-    {:name => 'innate', :version => ['>= 2011.12']}
+    {:name => 'innate', :version => ['>= 2012.03']}
   ]
 
   # Array containing all the development dependencies.
@@ -40,7 +40,8 @@ module Ramaze
     {:name => 'tenjin'      , :version => ['>= 0.6.1']},
     {:name => 'yard'        , :version => ['>= 0.7.2']},
     {:name => 'redis'       , :version => ['>= 2.2.2']},
-    {:name => 'rdiscount'   , :version => ['>= 1.6.8']}
+    {:name => 'rdiscount'   , :version => ['>= 1.6.8']},
+    {:name => 'slim'        , :version => ['>= 1.1.0']}
   ]
 
   # Lokar requires Ruby >= 1.9

data/lib/ramaze/gestalt.rb

@@ -1,5 +1,5 @@
 #          Copyright (c) 2009 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
+# All files in this distribution are subject to the terms of the MIT license.
 
 module Ramaze
   ##

data/lib/ramaze/helper.rb

@@ -1,5 +1,5 @@
 #          Copyright (c) 2009 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
+# All files in this distribution are subject to the terms of the MIT license.
 require 'innate/helper'
 
 module Ramaze

data/lib/ramaze/helper/auth.rb

@@ -1,5 +1,5 @@
 #          Copyright (c) 2009 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
+# All files in this distribution are subject to the terms of the MIT license.
 
 module Ramaze
   module Helper

data/lib/ramaze/helper/cache.rb

@@ -1,5 +1,5 @@
 #          Copyright (c) 2009 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
+# All files in this distribution are subject to the terms of the MIT license.
 
 module Ramaze
   module Helper

data/lib/ramaze/helper/csrf.rb

@@ -75,8 +75,6 @@ module Ramaze
     #       end
     #     end
     #
-    # @author Yorick Peterse
-    #
     module CSRF
       ##
       # Method that can be used to protect the specified methods against CSRF
@@ -84,7 +82,6 @@ module Ramaze
       # a field called "csrf_token". This method will then validate that token
       # against the current token in the session.
       #
-      # @author Yorick Peterse
       # @param  [Strings/Symbol] *methods Methods that will be
       #  protected/unprotected.
       # @param  [Block] Block that will be executed if the token is invalid.
@@ -101,7 +98,8 @@ module Ramaze
         if methods.include?(action.name) or methods.include?(action.name.to_sym)
           # THINK: For now the field name is hard-coded to "csrf_token". While
           # this is perfectly fine in most cases it might be a good idea
-          # to allow developers to change the name of this field (for whatever the reason).
+          # to allow developers to change the name of this field (for whatever
+          # the reason).
           yield unless validate_csrf_token(request.params['csrf_token'])
         end
       end
@@ -117,20 +115,13 @@ module Ramaze
       #
       # Note that this method will be automatically called if no CSRF token exists.
       #
-      # @author Yorick Peterse
-      # @param  [Hash] Additional arguments that can be set such as the TTL.
+      # @param [Hash] Additional arguments that can be set such as the TTL.
       #
       def generate_csrf_token(args = {})
-        # Default TTL is 15 minutes
-        ttl = args[:ttl] || (15 * 60)
-
-        # Get some good entropy
+        ttl    = args[:ttl] || (15 * 60)
         random = SecureRandom.random_bytes(512)
-        # and some not so good entropy
-        time = Time.now.to_f
-
-        # Hash it together
-        token = Digest::SHA512.hexdigest(random + time.to_s)
+        time   = Time.now.to_f
+        token  = Digest::SHA512.hexdigest(random + time.to_s)
 
         # Time to store all the data we want to check later.
         session[:_csrf] = {
@@ -142,14 +133,12 @@ module Ramaze
           :ttl   => ttl
         }
 
-        # Prevent this method from returning any value (it isn't needed anyway)
         return
       end
 
       ##
       # Retrieves the current value of the CSRF token.
       #
-      # @author Yorick Peterse
       # @return [String] The current CSRF token.
       # @example
       #  form(@data, :method => :post) do |f|
@@ -161,7 +150,6 @@ module Ramaze
           self.generate_csrf_token
         end
 
-        # Land ho!
         return session[:_csrf][:token]
       end
 
@@ -175,7 +163,6 @@ module Ramaze
       # If any of these checks fail this method will return FALSE. It's your
       # job to take action based on the results of this method.
       #
-      # @author Yorick Peterse
       # @param  [String] input_token The CSRF token to validate.
       # @return [TrueClass|FalseClass]
       # @example
@@ -194,12 +181,18 @@ module Ramaze
 
         _csrf = session[:_csrf]
 
-        # Mirror mirror on the wall, who's the most secure of them all?
-        session[:_csrf][:token] == input_token &&
+        valid = session[:_csrf][:token] == input_token &&
           (Time.now.to_f - _csrf[:time]) <= _csrf[:ttl] &&
           _csrf[:host]  == request.host &&
           _csrf[:ip]    == request.ip &&
           _csrf[:agent] == request.env['HTTP_USER_AGENT']
+
+        if valid
+          generate_csrf_token
+          return true
+        else
+          return false
+        end
       end
     end # CSRF
   end # Helper