ramaze 2011.07.25 → 2011.10.23

data/guide/general/controllers.md

@@ -0,0 +1,115 @@
+# Controllers
+
+When developing web applications controllers are the elements that are called
+by a browser. When visiting a page a request is made that is processed by Rack
+and sent to Ramaze. Ramaze in turn will determine what controller to call.
+
+To make understanding controllers a bit easier will use a real world example.
+Let's say we're in a restaurant and want to order some food. The waiter of the
+restaurant can be seen as a controller. We'll talk to it and tell him what we
+want to have for dinner but the waiter itself won't actually prepare our dinner,
+instead it will merely tell the cooks to make the dinner and bring it to you once
+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::
+
+    Request --> Server (Thin, Unicorn, etc) --> Rack --> Ramaze --> Controller
+
+## Ramaze & Controllers
+
+In Ramaze controllers are plain Ruby classes that extend Ramaze::Controller. The
+most basic controller looks like the following:
+
+    class ControllerName < Ramaze::Controller
+      map '/uri'
+
+      def index
+
+      end
+    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
+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
+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
+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).
+
+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
+as following:
+
+    class ControllerName < Ramaze::Controller
+      trait :default_action_name => 'default'
+
+      def default
+
+      end
+    end
+
+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
+of the default method should be. By default this is set to "index" but in the
+above example it was changed to "default".
+
+## Registering Controllers
+
+By now you might be thinking "How does Ramaze know what controller to call? I
+didn't initialize the controller!". It's true, you don't have to manually
+initialize the controller and save it in a hash or somewhere else. The entire
+process of registering a controller is done by the map() method and thus is one
+of the most important methods available. When calling this method it will store
+the name of the class that invoked it and bind it to the given URI. Whenever a
+request is made Ramaze simply creates an instance of the matching controller
+for a given URI.
+
+The basic process of the map() method is as following:
+
+1. Call map().
+2. Validate the given URI.
+3. Store the controller constant.
+4. Done.
+
+## Base Controllers
+
+In many applications you'll have separate areas such as an admin panel and the
+frontend. Usually you want to authenticate users for certain controllers, such
+as those used for an admin panel. An easy way of doing this is by putting the
+authentication call in a controller. By creating a base controller and extending
+it you don't have to call the method that authenticates the user over and over
+again. Because Ramaze is just Ruby all you have to do to achieve this is the
+following:
+
+    class AdminController < Ramaze::Controller
+
+    end
+
+    class Users < AdminController
+
+    end
+
+If your base controller has an initialize() method defined you should always
+call the parent's initialize() method to ensure everything is working properly.
+This can be done by calling super():
+
+    class AdminController < Ramaze::Controller
+      def initialize
+        # Calls Ramaze::Controller#initialize
+        super
+
+        # Custom calls can be placed here...
+        # ...
+      end
+    end

data/guide/general/helpers.md

@@ -0,0 +1,76 @@
+# Helpers
+
+Helpers are simple modules that can be used in controllers to prevent developers
+from having to write the same code over and over again. There's no actual
+definition of how helpers should be used and what they should do but the general
+idea is quite simple, all logic that may be shared among controllers should go
+in a helper. For example, Ramaze ships with it's own layout helper that adds a
+method ``set_layout()`` (see the {file:general/views Views} chapter).
+
+In order to use a helper there are a few guidelines it should follow. The most
+important guideline (or rule) is that it should be declared under the
+Ramaze::Helper namespace. Say your helper is called "Cake" this would result in
+Ramaze::Helper::Cake as the full name. The second rule/guideline is that helpers
+should be placed in the "helper" directory of your Ramaze application (or any
+other directory added to the list of helper paths). This is required in order to
+load helpers the ramaze way, otherwise you'll have to manually load each helper.
+
+## Loading Helpers
+
+Loading helpers the Ramaze way is pretty easy and can be done using the method
+helper():
+
+    class Blogs < Ramaze::Controller
+      helper :cake
+    end
+
+This method can load multiple helpers in a single call as well:
+
+      class Blogs < Ramaze::Controller
+        helper :cake, :pie, :candy
+      end
+
+If you have your helper located somewhere else or don't want to use the helper()
+method you can just include each helper the regular way:
+
+    class Blogs < Ramaze::Controller
+      include Ramaze::Helper::Cake
+      include Ramaze::Helper::Pie
+      include Ramaze::Helper::Candy
+    end
+
+As you can see this requires more lines of code and thus it's recommended to
+load all helpers the Ramaze way.
+
+## Available Helpers
+
+* {Ramaze::Helper::Auth}: basic authentication without a model.
+* {Ramaze::Helper::Bench}: basic benchmarking of your code.
+* {Ramaze::Helper::BlueForm}: makes building forms fun again.
+* {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}
+* {Ramaze::Helper::Gestalt}: helper for {Ramaze::Gestalt}.
+* {Ramaze::Helper::Gravatar}: easily generate Gravatars.
+* {Ramaze::Helper::Identity}: helper for OpenID authentication.
+* {Ramaze::Helper::Layout}: easily set layouts for specific actions.
+* {Ramaze::Helper::Link}
+* {Ramaze::Helper::Localize}
+* {Ramaze::Helper::Markaby}
+* {Ramaze::Helper::Maruku}
+* {Ramaze::Helper::Paginate}: easily paginate rows of data.
+* {Ramaze::Helper::Remarkably}
+* {Ramaze::Helper::RequestAccessor}
+* {Ramaze::Helper::SendFile}
+* {Ramaze::Helper::SimpleCaptcha}: captches using simple mathematical questions.
+* {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}

data/guide/general/installation.md

@@ -0,0 +1,58 @@
+# Installation
+
+Ramaze can be installed by using [Rubygems][rubygems], direct download or by
+using Git. Installing Ramaze via Rubygems only needs a single command:
+
+    $ gem install ramaze
+
+Optionally you can specify ``-v`` to install a specific version:
+
+    $ gem install ramaze -v 2011.07.25
+
+## Git
+
+If you're interested in hacking on Ramaze or you just want to browse the source
+you can use Git to install a local copy of Ramaze. For this you'll need to have
+Git installed (refer to your package manager for details on installing Git).
+When installed you can clone the Ramaze repository with the following commnad:
+
+    $ git clone git://github.com/ramaze/ramaze.git
+
+Once the cloning process has completed you should ``cd`` into the directory to
+install all required gems and optionally set up an RVM environment in case
+you're using RVM:
+
+    $ cd ramaze
+    $ rake setup
+
+Once installed you can build a gem manually or just require the local
+installation manually:
+
+    require '/path/to/ramaze/lib/ramaze'
+
+Building a gem can be done using the command ``rake gem:build``, if you want to
+also install the gem after it's built you should run ``rake gem:install``
+instead.
+
+Another way of loading Ramaze is to add it to your ``$RUBYLIB`` variable. It's
+best if you put this in your ``.bashrc`` file so that you don't have to run the
+command manually every time you open up a new terminal:
+
+    export RUBYLIB="/path/to/ramaze/lib"
+
+This approach allows you to load Ramaze like you'd normally would instead of
+having to specify the full path.
+
+## Direct Download
+
+In case you don't have Git installed but still want to have a local copy you can
+download a tarball from Github. If you want to download the latest copy you can
+go to the [Downloads][downloads] page, if you want to download a specific tag
+instead you should navigate to the [Tags][tags] page.
+
+Once downloaded and extracted the setup process is the same as when installing
+Ramaze via Git.
+
+[rubygems]: http://rubygems.org/
+[downloads]: https://github.com/Ramaze/ramaze/downloads
+[tags]: https://github.com/Ramaze/ramaze/tags

data/guide/general/logging.md

@@ -0,0 +1,99 @@
+# Logging
+
+Similar to the caching system Ramaze makes it easy to log information using a
+unified API, whether you're logging to a file, using Growl or something else.
+Ramaze itself only uses a single logger which logs to STDOUT by default. This
+logger is stored in ``Ramaze::Log``. While you can just use this particular
+logger it's recommended to create your own ones if you need to log specific
+types of data (such as API calls).
+
+Creating a custom logger works just like initializing a regular class. Say you
+want to rotate your log files based on the current date, in that case
+{Ramaze::Logger::RotatingInformer} should be used. To use this logger you'd
+simply do the following:
+
+    logger = Ramaze::Logger::RotatingInformer.new('./log')
+
+This creates a new instance of the logger and tells it to store it's log files
+in the ``./log`` directory. Each log file's name is the date on which it was
+created in the format of ``yyyy-mm-dd``.
+
+Once a logger has been created you can use the following logging methods:
+
+* warn: logs a warning message.
+* debug: logs a debugging message such as "Connected to the database".
+* error: logs an error message, useful for logging validation errors and the
+  like.
+* info: logging method for generic log messages that don't fit into a specific
+  category.
+
+You can call these methods on the instance of a logger just like any other
+method:
+
+    logger.info 'Logging data sure is easy to do!'
+
+## Creating Custom Loggers
+
+Ramaze provides an API that makes it easy to create your own logging class. Each
+log class should include the module {Ramaze::Logging}, this module provides the
+basic setup for every logger and stops you from having to re-invent the wheel
+every time.
+
+    class MyLogger
+      include Ramaze::Logging
+    end
+
+Each logger should respond to the instance method ``log()``. This method will be
+used by other methods such as ``error()`` and ``warn()``, therefor your logger
+is somewhat useless without this method. The ``log()`` method should take at
+least two parameters, the first one the logging level (such as "error") and the
+second (and all following parameters) should be messages to log. Lets add this
+method to the ``MyLogger`` class shown above:
+
+    class MyLogger
+      include Ramaze::Logging
+
+      def log(level, *messages)
+
+      end
+    end
+
+Now you no longer get nasty errors when trying to log data. However, your data
+is also completely ignored (after all, the method isn't doing anything yet).
+What the ``log()`` method does is really up to you, whether you're logging to
+STDOUT, to a file or to a database. A basic example of logging to STDOUT using
+this class can be seen below.
+
+    class MyLogger
+      include Ramaze::Logging
+
+      def log(level, *messages)
+        messages.each do |message|
+          $stdout.puts "#{level.upcase}: #{message}"
+        end
+      end
+    end
+
+When using this class the output will look like the following:
+
+    ruby-1.9.2-p290 :011 > logger = MyLogger.new
+     => #<MyLogger:0x00000101ae6328>
+    ruby-1.9.2-p290 :011 > logger.info 'Hello Ramaze!'
+    INFO: Hello Ramaze!
+
+Of course it doesn't stop here. You can add colors, timestamps and pretty much
+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

@@ -0,0 +1,100 @@
+# 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::
+
+    Request --> Server (Thin, Unicorn, etc) --> Rack --> Middleware(s) -->
+    Ramaze  --> Controller
+
+Say we want to ban a number of users by IP, there are two ways of doing this.
+The first way of doing this would be to validate the user's IP in all controllers
+(or in a base controller). However, this approach will eventually require quite
+a bit of code. The easier method, as you may have guessed, is using a Rack
+middleware. Since middlewares are executed for each request this means we'll
+only have to add our code once and we're good to go.
+
+## Building the Middleware
+
+Let's begin building our IP blacklist. For the sake of simplicity we'll hardcode
+the blocked IPs in an array stored inside our middleware. Go ahead and create a
+file called "banlist.rb" and save it somewhere in your application (and require
+it!). We'll begin with our basic skeleton that looks like the following:
+
+    class Banlist
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+
+      end
+    end
+
+First we declare a new class called "Banlist". Followed by this is our construct
+method that takes a single argument: an object containing the details of our
+Ramaze application. Next up is the call() method which also takes a single
+argument but this time it's an object containing our environment details such as
+the POST and GET data.
+
+Let's add a list of blocked IPs to our middleware. Modify the initialize()
+method so that it looks like the following:
+
+    def initialize(app)
+      @app    = app
+      @banned = ['189.3.0.116', '193.159.244.70', '193.46.236.*']
+    end
+
+We now have 3 blocked IPs. Time to actually implement the blocking mechanism in
+our call() method. Modify it as following:
+
+    def call(env)
+      if @banned.include?(env['REMOTE_ADDR'])
+        return "You have been banned!"
+      else
+        @app.call(env)
+      end
+    end
+
+So what did we do? Quite simple actually, we extracted the user's IP by calling
+``env['REMOTE_ADDR']`` and checked if it's stored in the @banned instance
+variable. If it is we'll block the user and show a message "You have been
+banned". Our final middleware looks like the following:
+
+    class Banlist
+      def initialize(app)
+        @app    = app
+        @banned = ['189.3.0.116', '193.159.244.70', '193.46.236.10']
+      end
+
+      def call(env)
+        if @banned.include?(env['REMOTE_ADDR'])
+          return "You have been banned!"
+        else
+          @app.call(env)
+        end
+      end
+    end
+
+## 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:
+
+    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}.