ramaze 0.3.9.1 → 2023.01.06

data/{doc/readme_chunks/principles.txt → guide/general/principles.md}

@@ -1,3 +1,6 @@
+# @title Principles
+# Principles
+
 There are some basic principles that Ramaze tries to follow:
 
 * KISS (Keep It Super Simple)
@@ -12,45 +15,40 @@ There are some basic principles that Ramaze tries to follow:
 
 * 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.
+  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. 
+  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...
-
-  Through 100% documentation Ramaze gives the developer easy and solid
-  understanding of the underlying concepts and functionality.
+  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.
+  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.
+  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,110 @@
+# @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
+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.
+
+## 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 a supplied Rake task:
+
+    $ rake ramaze:start
+
+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
+
+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

@@ -0,0 +1,82 @@
+# @title Routes
+# 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,210 @@
+# @title Sessions
+# 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.
+
+## 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
+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!
+
+## Flashdata
+
+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 make it easier to display flash based messages you can use
+{Ramaze::Helper::Flash#flashbox}. You can load this helper by calling
+``helper(:flash)`` inside your controller.
+
+Displaying the flashbox is then as simple as :
+
+    #{flashbox}
+
+anywhere in your layouts or views.
+
+To change the markup of the flashbox' HTML you can 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.
+
+In the above example, the content of the flash is returned by a method in the
+controller. However, the most common scenario is to address the flash object
+directly in the layouts or viems. You can display flash data (in your
+layout for instance), just like any other variable :
+
+    #{flash[:message]}
+
+and you can use any key in flash, and display in a view or in a layout
+afterwards (no just :message of course).
+
+For instance, let's say you want to display information boxes at the top of your
+layout page. This information is displayed when an operation succeeds, fails, or
+when you just want to inform the user. You can easily take advantage of your key
+values and use them as css selectors like that :
+
+    ....
+    <div>
+      <!-- flash -->
+      <?r [:success, :error, :info].each do |type| ?>
+        <?r if flash[type] ?>
+
+          <div class="alert alert-block alert-#{type} fade in">
+            <a class="close" data-dismiss="alert" href="#">×</a>
+            <h4 class="alert-heading">#{ type.capitalize }</h4>
+            #{flash[type]}
+          </div>
+
+        <?r end ?>
+      <?r end ?>
+
+      #{@content}
+
+    </div>
+    ...
+

data/guide/general/special_thanks.md

@@ -0,0 +1,69 @@
+# @title Special Thanks
+# Special Thanks
+
+There are a large number of people who made Ramaze possible by their ongoing
+efforts in the world of open source and by encouraging and helping me.
+
+This list is by no means a full listing of all these people, but I try to
+get a good coverage despite that.
+
+I would like to thank:
+
+* Yukihiro Matsumoto a.k.a matz
+
+  For giving the world Ruby and bringing fun back into programming.
+
+* Zed Shaw a.k.a. zedas
+
+  For developing Mongrel, Ramaze started out as a simple Hello World based on
+  that awesome server.
+
+* Christian Neukirchen a.k.a chris2
+
+  For building rack, which is just what the numerous web-developers had
+  anticipated and which will, with no doubt, change the world.
+
+* Pistos
+
+  For continious encouragment and building the first real webpage on Ramaze. His
+  bugreports were invaluable.
+
+* Jim Weirich
+
+  For Rake, which lifts off a lot of tasks from the shoulders of every
+  developer who uses it.
+
+* Thomas Sawyer a.k.a Trans
+
+  Dragging me deep into the rabbit-hole and showing me how awesome Ruby truely
+  is through his work on facets, ratchets and tons of other projects.
+
+* George Moschovitis a.k.a gmosx
+
+  For his tremendous efforts in the Nitro/Og framework, which is a source of
+  steady inspiration for Ramaze and brought me to Ruby in the first place.
+
+* Rob Levin a.k.a. lilo
+
+  He founded the most excellent Freenode IRC-network, where the most important
+  channels for rubyists are located (as is #ramaze).  May he rest in peace.
+
+* Loren Segal
+
+  For creating YARD. Without YARD we'd still be stuck using rdoc.
+
+* The guys (and gals) in the various channels on Freenode.
+
+  As the people are way too many to be listed, here the channels that I call my
+  online home. All the people in there deserve special thanks for getting me
+  hooked to Ruby and providing their help in a friendly and patient manner:
+
+  * \#nitro
+  * \#ruby-de
+  * \#ruby-lang
+  * \#rubyforce
+
+I'd also like to thank the following people for contributing to the guide:
+
+* [Stas Sușcov](https://github.com/stas)
+* [John Pagonis](https://github.com/pagojo)