ramaze 0.3.9.1 → 2023.01.06

data/guide/general/controllers.md

@@ -0,0 +1,210 @@
+# @title Controllers
+# 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".
+
+### 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
+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,89 @@
+# @title Helpers
+# 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::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::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/installation.md

@@ -0,0 +1,59 @@
+# @title Installation
+# 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
+    $ bundle install
+
+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,96 @@
+# @title Logging
+# 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::LogHub}
+* {Ramaze::Logger::Informer}
+* {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.

data/guide/general/middlewares.md

@@ -0,0 +1,111 @@
+# @title Rack Middlewares
+# Rack Middlewares
+
+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
+
+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 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.core`.
+
+Assuming we're running in "dev" mode our call will look like the following:
+
+    Ramaze.middleware :dev do
+      use Banlist
+      run Ramaze.core
+    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

@@ -0,0 +1,79 @@
+# @title Models
+# 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/