ramaze 2012.04.14 → 2012.12.08b

data/guide/general/cache.md

@@ -1,3 +1,4 @@
+# @title Caching Data
 # Caching Data
 
 Caching data such as API responses, compiled templates or database results can

data/guide/general/configuration.md

@@ -1,3 +1,4 @@
+# @title Configuration
 # Configuration
 
 Ramaze provides two ways of setting configuration options, using
@@ -132,7 +133,7 @@ value, etc:
 
 While Ramaze is a very flexible framework it requires some basic information
 about the location of your views, layouts and so on. Ramaze does not
-automatically tries to locate these but instead uses a set of defined locations
+automatically try to locate these but instead uses a set of defined locations
 to look for. These paths are set using ``Ramaze::Optioned`` and can be found in
 the following options:
 

data/guide/general/contributing.md

@@ -1,3 +1,4 @@
+# @title Contributing to Ramaze
 # Contributing To Ramaze
 
 Everybody is welcome to contribute to Ramaze and/or the guide. This guide is

data/guide/general/controllers.md

@@ -1,3 +1,4 @@
+# @title Controllers
 # Controllers
 
 When developing web applications controllers are the elements that are called
@@ -12,7 +13,7 @@ instead it will merely tell the cooks to make the dinner and bring it to you onc
 it's done. The waiter is our controller, the cook is our model and our meal can
 be seen as the view.
 
-In a typical application the entire flow of a request is as following::
+In a typical application the entire flow of a request is as following:
 
     Request --> Server (Thin, Unicorn, etc) --> Rack --> Ramaze --> Controller
 
@@ -30,10 +31,10 @@ most basic controller looks like the following:
     end
 
 Let's walk through this snippet step by step. The first line declares a new
-class that extends Ramaze::Controller. Extending this base class is very
+class that extends {Ramaze::Controller}. Extending this base class is very
 important, without it we won't be able to call controller specific methods such
-as the map() method. This method, which is called on line 2, is used to instruct
-Ramaze what controller is bound to what URI(Uniform Resource Identifier). The
+as the `map()` method. This method, which is called on line 2, is used to instruct
+Ramaze what controller is bound to what URI (Uniform Resource Identifier). The
 argument of this method should be a string starting with a /. The reason for
 this is that the URIs are relative to URL the application is running on. For
 example, if our application was running at ramaze.net a URI of "/blog" would
@@ -42,12 +43,12 @@ mean the controller can be found at ramaze.net/blog.
 Let's move to the next lines of code. The next lines of code define a new method
 called "index". By default Ramaze will try to call this method if no URI after
 the mapped URI is given. In our /blog example a call to ramaze.net/blog would
-call BlogController#index but a call to ramaze.net/blog/entry/10 would call
-BlogController#entry(10).
+call `BlogController#index` but a call to `ramaze.net/blog/entry/10` would call
+`BlogController#entry(10)`.
 
 All methods that are declared as public can be accessed by a user and by default
-the index() method is called if no other method is specified. Don't like the
-index() method? No problem, you can specify a different default method to call
+the `index()` method is called if no other method is specified. Don't like the
+`index()` method? No problem, you can specify a different default method to call
 as following:
 
     class ControllerName < Ramaze::Controller
@@ -60,10 +61,104 @@ as following:
 
 We're not going to cover Traits too much in this chapter as there's a dedicated
 chapter for them but in short they're a way of setting configuration options. In
-this case we're using the trait "default_action_name" to specify what the name
+this case we're using the trait `default_action_name` to specify what the name
 of the default method should be. By default this is set to "index" but in the
 above example it was changed to "default".
 
+### Method Arguments
+
+As mentioned above methods are bound to URLs given they're declared as public
+methods. The same applies to the arguments of such methods, if the method is
+public these arguments can be set from the URL. This means that you don't have
+to use a special DSL just to bind methods to certain URLs while taking various
+parameters into account. An example is the following:
+
+    class Pages < Ramaze::Controller
+      map '/pages'
+
+      def index
+        # Overview of all pages
+      end
+
+      def edit(id)
+        # Edit the page for the given ID
+      end
+    end
+
+This controller would allow users to navigate to `/pages/edit/10` which would
+invoke `Pages#edit("10")`. There's no restriction on the values of parameters
+(as long as they don't include slashes), they are however always passed as
+strings to the method.
+
+One thing to keep in mind is that if a method takes a set of required parameters
+that are *not* specified Ramaze will *not* call the method, it will instead show
+a message that the request could not be executed due to a missing
+method/controller (unless your application has a custom handler for this).
+
+Using the code above navigating to `/pages/edit/10` would work but navigating to
+`/pages/edit` would not since the "id" parameter is specified as a required
+parameter but wasn't given in the URL. Don't worry, working around this is as
+easy as specifying a default value for your parameters:
+
+    class Pages < Ramaze::Controller
+      map '/pages'
+
+      def index
+        # Overview of all pages
+      end
+
+      def edit(id = nil)
+        # Edit the page for the given ID
+      end
+    end
+
+With this modification the `edit` method will be called for URLs such as
+`/pages/edit`, `/pages/edit/10` and so on.
+
+### Catch-all Methods
+
+Sometimes you want to create a controller in which a single method handles all
+the requests. This can be done by creating an `index` method that takes a
+variable amount of parameters:
+
+    class Pages < Ramaze::Controller
+      map '/pages'
+
+      def index(*args)
+
+      end
+    end
+
+In this example `Pages#index` would be called for URLs such as `/pages`,
+`/pages/example`, `/pages/edit/10` and so on. The exception to this is URLs that
+point to existing methods. An example:
+
+    class Pages < Ramaze::Controller
+      map '/pages'
+
+      def index(*args)
+        return 'index'
+      end
+
+      def example
+        return 'example'
+      end
+    end
+
+If a user were to browse to `/pages/hello` the index method would be called and
+"index" would be displayed, when the user instead goes to `/pages/example` the
+text "example" would be displayed as there's an existing method for this URI.
+However, if the user would request `/pages/example/10` the index method would
+again be called, this is because the example method does not take any
+parameters. Below is a list of various URLs and what method calls they'd result
+in.
+
+    /pages            # => Pages#index
+    /pages/index      # => Pages#index
+    /pages/edit/10    # => Pages#index("edit", "10")
+    /pages/example    # => Pages#example
+    /pages/example/10 # => Pages#index("example", "10")
+
 ## Registering Controllers
 
 By now you might be thinking "How does Ramaze know what controller to call? I
@@ -77,7 +172,7 @@ for a given URI.
 
 The basic process of the map() method is as following:
 
-1. Call map().
+1. Call `map()`.
 2. Validate the given URI.
 3. Store the controller constant.
 4. Done.

data/guide/general/helpers.md

@@ -1,3 +1,4 @@
+# @title Helpers
 # Helpers
 
 Helpers are simple modules that can be used in controllers to prevent developers
@@ -50,7 +51,6 @@ load all helpers the Ramaze way.
 * {Ramaze::Helper::Cache}: caching of entire actions and custom values in your
   controllers.
 * {Ramaze::Helper::CSRF}: protect your controllers from CSRF attacks.
-* {Ramaze::Helper::Disqus}
 * {Ramaze::Helper::Email}: quick and easy way to send Emails.
 * {Ramaze::Helper::Erector}
 * {Ramaze::Helper::Flash}
@@ -70,21 +70,20 @@ load all helpers the Ramaze way.
 * {Ramaze::Helper::Stack}
 * {Ramaze::Helper::Tagz}
 * {Ramaze::Helper::Thread}
-* {Ramaze::Helper::Ultraviolet}
 * {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 
+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::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 
+* {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/installation.md

@@ -1,3 +1,4 @@
+# @title Installation
 # Installation
 
 Ramaze can be installed by using [Rubygems][rubygems], direct download or by
@@ -23,7 +24,7 @@ install all required gems and optionally set up an RVM environment in case
 you're using RVM:
 
     $ cd ramaze
-    $ rake setup
+    $ bundle install
 
 Once installed you can build a gem manually or just require the local
 installation manually:

data/guide/general/logging.md

@@ -1,3 +1,4 @@
+# @title Logging
 # Logging
 
 Similar to the caching system Ramaze makes it easy to log information using a
@@ -86,14 +87,10 @@ whatever you want.
 
 ## Available Loggers
 
-* {Ramaze::Logger::Analogger}
-* {Ramaze::Logger::Growl}: uses Growl for log messages (requires Mac OS).
 * {Ramaze::Logger::LogHub}
 * {Ramaze::Logger::Informer}
-* {Ramaze::Logger::Knotify}
 * {Ramaze::Logger::Logger}: wrapper around the Logger class from the Stdlib.
 * {Ramaze::Logging}: basic skeleton for your own loggers.
 * {Ramaze::Logger::RotatingInformer}: logger that rotates log files based on the
   current date.
 * {Ramaze::Logger::Syslog}: logger that uses syslog.
-* {Ramaze::Logger::Xosd}

data/guide/general/middlewares.md

@@ -1,3 +1,4 @@
+# @title Rack Middlewares
 # Rack Middlewares
 
 Ramaze is a Rack based framework and thus allows you to create so called Rack
@@ -6,7 +7,7 @@ in order to intercept and process sequentially each incoming request and outgoin
 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::
+The flow of a Rack request (including middlewares) looks as following:
 
     Request --> Server (Thin, Unicorn, etc) --> Rack --> Middleware(s) -->
     Ramaze  --> Controller
@@ -83,7 +84,7 @@ 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 accepts a block in which one defines
+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").
 
@@ -91,29 +92,20 @@ 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}.
+always be set to `Ramaze.core`.
 
 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)
+    Ramaze.middleware :dev do
+      use Banlist
+      run Ramaze.core
     end
 
-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
-	
+<div class="note todo">
+    <p>
+        The method <code>Ramaze.middleware</code> can no longer be used to
+        retrieve the used middleware, instead it can only be used to set
+        these. The method <code>Ramaze.middleware!</code> also no longer
+        exists.
+    </p>
+</div>

data/guide/general/models.md

@@ -1,3 +1,4 @@
+# @title Models
 # Models
 
 Unlike other frameworks Ramaze does not ship with a database toolkit. One of the

data/guide/general/principles.md

@@ -1,3 +1,4 @@
+# @title Principles
 # Principles
 
 There are some basic principles that Ramaze tries to follow:

data/guide/general/ramaze_command.md

@@ -1,4 +1,5 @@
-## Ramaze Command
+# @title Ramaze Command
+# Ramaze Command
 
 Ramaze ships with a relatively simple command, named "ramaze". This command can
 be used to create new applications as well as starting them. To make reading
@@ -25,39 +26,6 @@ directory name. If the application was named "blog" there would now be a
 directory called "blog" in the current one. This directory will contain all
 basic files that can be used for a Ramaze powered application.
 
-Each new application has the following structure:
-
-    .__ app.rb
-    |__ config.ru
-    |__ controller
-    |   |__ init.rb
-    |   |__ main.rb
-    |
-    |__ layout
-    |   |__ default.xhtml
-    |
-    |__ model
-    |   |__ init.rb
-    |
-    |__ public
-    |   |
-    |   |__ css
-    |   |   |__ screen.css
-    |   |
-    |   |__ dispatch.fcgi
-    |   |__ favicon.ico
-    |   |__ js
-    |   |   |__ jquery.js
-    |   |
-    |   |__ ramaze.png
-    |
-    |__ spec
-    |   |__ main.rb
-    |
-    |__ start.rb
-    |__ view
-        |__ index.xhtml
-
 ## Application Prototypes
 
 Due to Ramaze's nature it's very easy to create your own application prototype
@@ -109,7 +77,6 @@ This is only a basic example of the flexibility of Ramaze, I highly recommend
 you playing around with your own prototypes as it's a great way to learn the
 basics of Ramaze and to really understand how flexible Ramaze is.
 
-
 <div class="note todo">
     <p>
         <strong>Note</strong>: This prototype does not come with Ramaze, it's
@@ -121,19 +88,12 @@ basics of Ramaze and to really understand how flexible Ramaze is.
 
 When you've created an application there are three ways of running it. You can
 either use your server's command such as `thin` or `unicorn` but you can also
-use bin/ramaze. When starting your application with bin/ramaze it will use the
-appropriate server according to the settings set in "config.ru" or "star.rb".
-An example of using this command is as simple as the following:
-
-    $ ramaze start
-
-On top of these two ways you can also start your Ramaze application by calling
-the "start.rb" file using the ruby binary:
+use a supplied Rake task:
 
-    $ ruby start.rb
+    $ rake ramaze:start
 
-If you want to stop the running application you can simply close it by using the
-key combination Ctrl+C.
+If you want to stop the running application you can simply close it by using
+the key combination Ctrl+C.
 
 <div class="note todo">
     <p>
@@ -145,11 +105,6 @@ key combination Ctrl+C.
 
 ## Ramaze Console
 
-The bin/ramaze command allows you to run an interactive Ramaze session just
-like IRB. In fact, Ramaze actually uses IRB. To invoke the Ramaze console simple
-execute `ramaze console` and you're good to go. This console gives you full
-access to your application and thus can be very useful for debugging purposes.
-
-An example of a Ramaze console session can be seen in the image below.
-
-![Ramaze Console](_static/ramaze_console.png)
+By default Ramaze allows you to start a console using either IRB or Pry. These
+consoles can be started by running `rake ramaze:irb` and `rake ramaze:pry`
+respectively.

data/guide/general/routes.md

@@ -1,3 +1,4 @@
+# @title Routes
 # Routes
 
 While in many cases the default route system that comes with Ramaze is good

data/guide/general/sessions.md

@@ -1,3 +1,4 @@
+# @title Sessions
 # Sessions
 
 The term sessions is used for data associated to a specific client. The easiest
@@ -61,7 +62,7 @@ simple and works a bit like you're storing data in a hash:
     session[:logged_in] = true
 
 In the above example we stored a boolean with a value of "true" in the current
-client's session under the name ":logged_in". If we want to retrieve this data
+client's session under the name `:logged_in`. If we want to retrieve this data
 somewhere else in the application all we'd have to do is the following:
 
     session[:logged_in] # => true
@@ -161,7 +162,7 @@ application:
 
 If a client were to visit the index method for the first time nothing would be
 displayed because the flash data isn't there yet. As soon as the client visits
-/set_message he would be redirected back to the index method and the message
+`/set_message` he would be redirected back to the index method and the message
 "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.