ramaze 2011.07.25 → 2011.10.23

data/guide/general/models.md

@@ -0,0 +1,78 @@
+# Models
+
+Unlike other frameworks Ramaze does not ship with a database toolkit. One of the
+ideas of Ramaze is that it allows you to choose your own set of tools, you're
+not forced to use what we think is best. Ramaze allows you to use
+[ActiveRecord][ar], [Sequel][sequel] or anything else. For the simplicity of
+this user guide we'll use Sequel. In short, Sequel is a database toolkit that
+allows you to write SQL statements using Ruby methods as well as providing an
+ORM (Object Relationship Mapper).
+
+Let's say we're creating a simple blog application. Each blog has posts,
+comments, users and perhaps some categories. We're not going to create a model
+for each of these entities in this guide but instead we'll focus on the Post
+model. The most basic form of a model looks like the following:
+
+    class Post < Sequel::Model
+
+    end
+
+From this point on we can load our model (given we have established a database
+connection) and call methods from it. For example, if we want to retrieve the
+post with ID #1 we'd do the following:
+
+    Post[1] # => SELECT * FROM posts WHERE id = 1
+
+Performing a WHERE clause and retrieving a single record can be done by passing
+a hash to the [] method:
+
+    Post[:title => 'Ramaze is Great'] # => SELECT * FROM posts WHERE title = 'Ramaze is Great'
+
+## Controllers And Models
+
+Of course using a model on its own isn't really going to work. Let's combine
+our Post model mentioned earlier with a controller called "Posts".
+
+    require 'ramaze'
+    require 'model/post'
+
+    class Posts < Ramaze::Controller
+      map '/'
+
+      def index
+        @posts = Post.all
+      end
+
+      def edit(id)
+        # Arguments are passed as strings so it's a good idea to convert them
+        @post = Post[id.to_i]
+      end
+    end
+
+This is a somewhat more advanced example of how to use controllers and models.
+However, it's nothing ground breaking and shouldn't be too hard to understand.
+In the index() method we're simply retrieving all posts by calling Post#all and
+storing them in an instance variable. In the edit() method we're retrieving the
+post based on the given ID.
+
+In the edit() method the "id" variable is also converted to an integer. The
+reason for this is that Ramaze doesn't know what types the URI segments should
+be and thus passes them as a string to the called method. While Sequel itself
+won't have any trouble handling this it's a good practice to send the correct
+types as other database toolkits might trigger errors when they receive a string
+value while expecting an integer.
+
+## Supported Toolkits
+
+* [ActiveRecord][ar]
+* [M4DBI][m4dbi]
+* [Sequel][sequel]
+* [DataMapper][datamapper]
+
+Besides these listed toolkits Ramaze should work with any other toolkit, these
+however are the ones that have been confirmed to work just fine with Ramaze.
+
+[sequel]: http://sequel.rubyforge.org/
+[ar]: http://ar.rubyonrails.org/
+[m4dbi]: https://github.com/Pistos/m4dbi
+[datamapper]: http://datamapper.org/

data/guide/general/principles.md

@@ -0,0 +1,53 @@
+# Principles
+
+There are some basic principles that Ramaze tries to follow:
+
+* KISS (Keep It Super Simple)
+
+  Ramaze doesn't introduce any major change of paradigm for everyone familiar
+  with Ruby and the basics of Web-development.
+
+* POLS (Principle Of Least Surprise)
+
+  Ramaze tries to be intuitive and easy to learn. Most functionality is built in
+  a way to help, not to obfuscate or confuse.
+
+* Modular design
+
+  Use what you want and how you want it.Through Ruby Ramaze provides one of the
+  most powerful programming-languages available, giving you full control over
+  your system.
+
+  Even the most essential parts of Ramaze can easily be replaced and/or modified
+  without losing the advantage of the whole framework.
+
+* Minimal dependencies
+
+  Nothing besides Ruby is required for the basic features.
+  Of course you can take advantage of several wonderful libraries, but Ramaze is
+  built in a way to be run on any basic setup.
+
+* Documentation
+
+  Document everything, classes, modules, methods, configuration
+  and so on. Through 100% documentation Ramaze gives the developer easy and
+  solid understanding of the underlying concepts and functionality.
+
+* Open development
+
+  Everyone is welcome to contribute to Ramaze in the easiest
+  way possible. The repository is open for patches passing the Test-suite.
+
+* Examples
+
+  Everyone learns different, some only read the source, others browse
+  documentation, but everyone loves examples for a quick and painless start.
+  Ramaze addresses this need and offers a wide variety of examples of usage,
+  basic functionality, project-layout and more advanced applications.
+
+* Fully BDD (Behaviour Driven Design)
+
+  Ramaze has a very complete set of so-called specifications built by RSpec.
+  These specs define the way Ramaze has to behave. The specs are checked every
+  time a new patch is pushed into the repository, deciding whether the changes
+  the patch applies are valid and don't break the framework.

data/guide/general/ramaze_command.md

@@ -0,0 +1,155 @@
+## 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
+this guide easier we'll call this command "bin/ramaze" from now on.
+
+<div class="note deprecated">
+    <p>
+        <strong>Warning</strong>: bin/ramaze is not a scaffolding application.
+        It can merely be used for some basic application management and creating
+        a basic Ramaze application.
+    </p>
+</div>
+
+## Creating Applications
+
+As mentioned earlier bin/ramaze can be used to create new applications. In order
+to create a new application in the current directory all you have to do is
+executing the following command:
+
+    $ ramaze create APPNAME
+
+APPNAME is the name of your new application and will also be used as the
+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
+if you dislike the default one. For example, I've made some small modifications
+to the default prototype so that it looks like the followng:
+
+    .__ app.rb
+    |__ config
+    |   |__ config.rb
+    |   |__ database.rb
+    |   |__ middlewares.rb
+    |   |__ requires.rb
+    |
+    |__ config.ru
+    |__ controller
+    |__ layout
+    |   |__ default.xhtml
+    |
+    |__ log
+    |__ public
+    |__ spec
+    |__ start.rb
+    |__ view
+
+This prototype is basically a minimal version of the default one but with a
+special directory for all configuration files. In order to use this prototype I
+had to make some small changes to app.rb, the look like the following:
+
+    require 'ramaze'
+
+    # Load the file that in turn will load all gems, keeps this file clean
+    require __DIR__('config/requires')
+
+    # Configure our application
+    require __DIR__('config/config')
+
+    # Load our database settings
+    require __DIR__('config/database')
+
+    # Load all Rack middlewares
+    require __DIR__('config/middlewares')
+
+    # Load all controllers
+    Dir.glob(__DIR__('controller') + '/**/*.rb').each do |f|
+      require f
+    end
+
+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
+        just an example of what you could make yourself.
+    </p>
+</div>
+
+## Running Applications
+
+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:
+
+    $ ruby start.rb
+
+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>
+        <strong>Note</strong>: There are many different ways to start your
+        application depending on the server you're using. Fore more information
+        it's best to look at the documentation of your favorite webserver.
+    </p>
+</div>
+
+## 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)

data/guide/general/routes.md

@@ -0,0 +1,81 @@
+# Routes
+
+While in many cases the default route system that comes with Ramaze is good
+enough there will be times when you want pretty URLs (or just different ones).
+Ramaze allows you to do all this using the class Ramaze::Route (it's an alias
+of Innate::Route). This class allows you to create routes using simple strings,
+regular expressions and lambdas. Let's say we have the following URLs:
+
+* /users/index
+* /users/profile/yorickpeterse
+* /users/edit/yorickpeterse
+
+Our goal is to rewrite these URLs to the following:
+
+* /users/list
+* /users/yorickpeterse
+* /users/yorickpeterse/edit
+
+In order to fully explain the routing system will use the three available
+possibilities: strings, regular expressions and lambdas.
+
+## String Routes
+
+Routes that use a string are the most basic form of routing. You simply specify
+a request URI and the action to call instead of the normal one:
+
+    Ramaze::Route['/foobar'] = '/baz/bar'
+
+This route tells Ramaze that every request to /foobar should be sent to /baz/bar
+instead. While string based routes are the easiest to use they're also the most
+limited one, they can merely be used to redirect A to B. If we look at our list
+of URLs the only one we can rewrite using this form of routing is the first one:
+
+    Ramaze::Route['/users/list'] = '/users/index'
+
+This forwards all requests that were sent to /users/list to /users/index.
+
+## Regular Expression Routes
+
+Using regular expressions in routes makes it possible to have more dynamic
+routes. Routes that use regular expressions look like the following:
+
+    Ramaze::Route[/user-([0-9]+)/] = '/users/%d'
+
+This route forwards requests such as /user-10 and /user-1234 to /users/10 and
+/users/1234. As you can see there's a "%d" in the value which is replaced with
+the value of the group ([0-9]+). When using regular expressions for your routes
+you can use sprintf characters in the value (%s, %d, etc).
+
+So what about our list of URLs? Let's rewrite the second URL:
+
+    Ramaze::Route['/users/([\w]+)'] = '/users/profile/%s'
+
+And there we go, all calls to /users/NAME (where NAME is the name of a user)
+will be routed to /users/profile/NAME.
+
+## Lambda Routes
+
+The last method of routing calls can be done using lambdas. The key of the []=
+method will be the name of a route (can be anything really) and the value a
+lambda that takes two parameters, the request path and a variable containing the
+request data:
+
+    Ramaze::Route['my funky lambda route'] = lambda do |path, request|
+
+    end
+
+In this lambda you're free to do whatever you want as long as you either return
+a new path or nil (anything else will result in an error). Say we wanted to
+route our last URL we'd do it as following:
+
+    Ramaze::Route['edit users'] = lambda do |path, request|
+      if path =~ /users\/edit\/([\w]+)/
+        return "/users/#{$1}/edit"
+      end
+    end
+
+This route redirects everything from /users/NAME/edit to /users/edit/NAME.
+Everything else is unaffected by this route since it only returns a value when
+the path matches the given regular expression. Note that lambdas can actually
+contain a "return" statement so the code above is perfectly valid.

data/guide/general/sessions.md

@@ -0,0 +1,140 @@
+# Sessions
+
+The term sessions is used for data associated to a specific client. The easiest
+example of a session is a simple cookie containing some very basic data such as
+a user's name.
+
+## Initializing Sessions
+
+Ramaze lazy-loads the session system that it's ship with. This means that if you
+never use any session related data a session will not be created. As soon as you
+call the main object for working with sessions (simply called "session") or add
+data to the flash (more on that later) Ramaze will load the session adapter
+automatically. This prevents you from having to manually write code that invokes
+a session for all your projects.
+
+So how do we actually start a session? As mentioned earlier this can be done in
+two different ways, calling session or flash. If you want to store data in the
+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.
+
+## The Session Object
+
+As mentioned earlier session is used for data that should be stored until the
+client's session is destroyed or the data is removed. A good example of this
+sort of data is a  boolean that indicates if the user is logged in or not, you
+don't want the user to re-authenticate over and over again thus you store the
+data using the session object. Storing data using this method is incredible
+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
+somewhere else in the application all we'd have to do is the following:
+
+    session[:logged_in] # => true
+
+A better example would be a simple counter that tracks the amount of times a
+user has visited your application:
+
+    class Counter < Ramaze::Controller
+      map '/'
+
+      def index
+        # If no data was found for the given key session returns nil
+        if !session[:visits].nil?
+          session[:visits] = 0
+        else
+          session[:visits] += 1
+        end
+
+        "You have visitied this page #{session[:visits]} times."
+      end
+    end
+
+In this relatively basic controller a user's amount of visits to the index()
+method will be stored in the session and displayed afterwards. Now it's time
+for the true magic. The session object is an instance of Innate::Session and
+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
+
+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
+is the following:
+
+    session.delete(:visits)
+
+From this point on the "visits" key is set to nil until the user visits the
+index page again.
+
+## 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
+systems as it can be used to prevent session fixation attacks by generating a
+new session ID every N minutes or whenever a certain action is triggered (e.g.
+the user logs in). Using this method is very simple and only requires the
+following to be done:
+
+    session.resid!
+
+## The Flash
+
+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:
+
+    flash[:message] = "Hello, Ramaze!"
+
+If we want to remove something from the flash we can call Flash.delete similar
+to Session.delete:
+
+    flash.delete(:message)
+
+Note that due to the nature of the flash data you'd have to do this before the
+client requests a new resource as the data will be deleted automatically at
+that point.
+
+To integrate flash with your application views include {Ramaze::Helper::Flash}
+in your controller and call function ``flashbox`` inside the view.
+
+To change the markup of the flashbox generated HTML, use the following trait
+inside your controller:
+
+    trait :flashbox => "<div class=\"alert-message %key\"><p>%value</p></div>"
+
+Below is an example of how the flash data can be used in a typical Ramaze
+application:
+
+    class Blogs < Ramaze::Controller
+      map '/'
+      helper :flash
+
+      def index
+        flash[:message]
+      end
+
+      def set_message
+        flash[:message] = "Hello, Ramaze!"
+        redirect(Blogs.r(:index))
+      end
+    end
+
+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
+"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)