ramaze 2011.07.25 → 2011.10.23

data/guide/general/special_thanks.md

@@ -0,0 +1,67 @@
+# 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)

data/guide/general/testing.md

@@ -0,0 +1,61 @@
+# Testing With Ramaze
+
+Ramaze uses and encourages BDD (Behaviour Driven Development). It comes out of
+the box with a helper for [Bacon][bacon]. Bacon is a small [Rspec][rspec] clone
+used by Ramaze for all specifications (also known as "specs").
+
+Writing tests with Bacon results to clean and complete specifications with
+minimum learning time and effort for adaptation. When creating a new Ramaze
+application using ``ramaze create`` Ramaze will automatically generate a
+directory for your specifications.
+
+Ramaze does not enforce the use of a particular testing library but for the sake
+of simplicity this guide assumes you'll be using Bacon. In order to use Bacon
+you must first install it from Rubygems. This can be done using the following
+command:
+
+    gem install bacon
+
+In order to run the tests in the spec directory you can run the following
+command:
+
+    bacon spec/*
+
+To test the Ramaze application tests coverage, you can use a tool like
+[SimpleCov][simplecov]. SimpleCov requires minimal effort to get integrated,
+start by installing the gem:
+
+    gem install simplecov
+
+In order to actually measure your code coverage you'll have to tell SimpleCov a
+bit about your application. This is done by loading Simplecov and starting it
+*before* loading all your tests. This can be done by using the following code:
+
+    require 'simplecov'
+
+    SimpleCov.start
+
+    # Load the existing files
+    Dir.glob('spec/*.rb').each do |spec_file|
+      unless File.basename(spec_file) == 'init.rb'
+        require File.expand_path(spec_file)
+      end
+    end
+
+In order to run the file you'd simply invoke the following:
+
+    bacon spec/init.rb
+
+Upon success SimpleCov will create a new directory ``coverage`` with the
+results. You can point your browser to the index.html file inside that directory
+If you have Python installed you can start a webserver directly on port 11111
+and browse to the same folder. This can be done as following:
+
+    python -m SimpleHTTPServer 11111
+
+For more information on using Simplecov see the [Github project][simplecov gh].
+
+[bacon]: https://github.com/chneukirchen/bacon
+[simplecov]: https://github.com/colszowka/simplecov
+[rspec]: http://relishapp.com/rspec
+[simplecov gh]: https://github.com/colszowka/simplecov

data/guide/general/views.md

@@ -0,0 +1,322 @@
+# Views
+
+Views are the last step in the process of a request to a MVC framework such as
+Ramaze. A controller loads a model, the model processes a certain amount of
+data and the controller will then pass this data to a view. The typical flow of
+a MVC framework (or any framework using a view system) looks like the following::
+
+    Request --> Controller --> View
+                  ^ |
+                  | '--> Model
+                  |        |
+                  '--<-----'
+
+The contents of a view is what the visitor of a page will eventually see.
+Looking back at the waiter example introduced in the :doc:`controllers` chapter
+a view can be seen as our dinner. It's the end result we requested for but it
+has been modified according to our order.
+
+Ramaze has support for many different template engines and thus views can look
+quite different. By default Ramaze uses a simple template engine called "Etanni",
+Etanni was developed by Michael Fellinger exclusively for Ramaze and is a very
+fast template engine. In this chapter we'll use Etanni to make it a bit easier
+to understand how views work.
+
+## Layouts
+
+Ramaze also has a concept of layouts. Layouts are basically views for views and
+are placed in the "layout" directory of your application. These views can be
+used to display generic elements such as a navigation menu for all views.
+Because of this it's recommended to only place action specific markup in your
+views. Global elements such as navigation menus or page titles should go in a
+layout.
+
+In order to render a view inside a layout all you have to do is calling the
+"content" instance variable. If we were to use Etanni (more on this later) our
+code would look like the following:
+
+    <div id="container">
+        #{@content}
+    </div>
+
+In order to use a layout we have to tell Ramaze to do so in our controller.
+Setting a layout can be done in a few different ways. The easiest way is using
+the method "layout" in your controller as following:
+
+    class Blogs < Ramaze::Controller
+      layout 'default'
+    end
+
+This will tell Ramaze to use the layout "default.xhtml" for the Blogs controller.
+While suited for most people there comes a time when you're in the need of a
+more dynamic way of assigning a layout. This can be done in two different ways.
+The first way is passing a block to the layout() method:
+
+    class Blogs < Ramaze::Controller
+      layout do |path|
+        if path === 'index'
+          :index_layout
+        else
+          :alternative_layout
+        end
+      end
+    end
+
+In this example two layouts are used, "index_layout" for the index() method and
+"alternative_layout" for all other methods.
+
+The second way is using the method "set_layout". This method works almost
+identical to layout() but has one big advantage: it can set method specific
+layouts. Changing the code posted above so that it uses this method would look
+like the following:
+
+    class Blogs < Ramaze::Controller
+      # Set our default layout
+      layout 'alternative_layout'
+
+      # Set our layout for the index() method
+      set_layout 'index_layout' => [:index]
+    end
+
+The set_layout method takes a hash where the keys are the names of the layouts
+to use and the values the methods for which to use each layout. Below is another
+example that specifies a few extra layout/method combinations.
+
+    class Blogs < Ramaze::Controller
+      # Set our default layout
+      layout 'default'
+
+      # Set our layout for the index() method
+      set_layout 'main' => [:index, :edit], 'extra' => [:add, :synchronize]
+    end
+
+## Loading Views
+
+Loading views can be done in two different ways. When not explicitly calling a
+certain view (or returning any data from the controller) Ramaze will try to load
+a matching view for the current action. If the method "edit" was called Ramaze
+will try to load a view called "edit". Manually sending a response back can be
+done by returning a string from the controller method that is called. Take a
+look at the example below.
+
+    class Blogs < Ramaze::Controller
+      map '/'
+
+      def index
+
+      end
+
+      def custom
+        "This is my custom response!"
+      end
+
+      def other
+        render_view :foobar
+      end
+    end
+
+If the user were to visit /index Ramaze would try to load the view "index.xhtml"
+(``.xhtml`` is the extension for Etanni templates) but when the user goes to
+/custom he'll always see the message "This is my custom response!". This is
+because Ramaze will use the return value of a controller method as the body for
+the response that will be sent back to the visitor.
+
+Let's take a look at the other() method in our controller. As you can see it
+calls a method "render_view". This method is used to render a different view
+(in this case foobar.xhtml) but without calling it's action, once this is done
+the contents of the view will be returned to the controller. When calling custom
+views you can use any of the following methods:
+
+* render_view
+* render_partial
+* render_file
+* render_custom
+* render_full
+
+### render_view
+
+As mentioned earlier this method is used to render a view without calling it's
+action. This can be useful if you have several methods that share the same view
+but feed it different data. The usage of this method is quite simple, it's first
+argument is the name of the view to load (without the extension, Ramaze will
+figure this out) and the second argument is a hash containing any additional
+variables to send to the view (more on this later).
+
+    # Render "foo.xhtml"
+    render_view :foo
+
+    # Render "foo.xhtml" and send some extra data to it
+    render_view :foo, :name => "Ramaze"
+
+### render_partial
+
+The render_partial method works very similar to the render_view method, the
+difference is that the render_partial method will not render a layout while
+render_view will. This makes the render_partial method useful for responses to
+Ajax calls that don't need (or don't want to) load both the view and the layout.
+This method has the same arguments as the render_view method.
+
+    # Render the view "partial.xhtml"
+    render_partial :partial
+
+    # Render the partial "partial.xhtml" and send some extra data to it
+    render_partial :partial, :name => "Ramaze"
+
+### render_file
+
+There comes a time when you may want to render a file that's located somewhere
+else. For this there is the render_file() method. This method takes a path,
+either relative or absolute to a file that should be rendered. This can be
+useful if you have a cache  directory located outside of your project directory
+and you want to load a view from it.
+
+The first argument of this method is a path to a file to render, the second
+argument is a hash with variables just like the other render methods.
+Optionally this method accepts a block that can be used to modify the current
+action.
+
+    # Render a file located in /tmp
+    render_file '/tmp/view.xhtml'
+
+    # Render a file and send some extra data to it
+    render_file '/tmp/view.xhtml', :name => "Ramaze"
+
+    # Render a file and modify the action
+    render_file '/tmp/view.xhtml' do |action|
+      # Remove our layout
+      action.layout = nil
+    end
+
+### render_custom
+
+The render_custom() method can be used to create your personal render method and
+is actually used by methods such as the render_partial method. The syntax is the
+same as the render_file() method except that instead of a full path it's first
+argument should be the name of the action to render.
+
+    render_custom :index do |action|
+      # Remove the layout
+      action.layout = nil
+
+      # Render the view without calling a method
+      action.method = nil
+    end
+
+### render_full
+
+Last but not least there's the render_full() method. This is the method Ramaze
+uses for calling a controller along with it's views and such. This method takes
+two arguments, the first is the full path of the action to render and the second
+a hash that will be used for the query string parameters. Please note that if this
+method is called in the first request of a client you won't have access to the
+session data and such, any following calls will have access to this data.
+
+    # Calls Blogs#index
+    render_full '/blog/index'
+
+    # Calls Blogs#edit(10)
+    render_full '/blog/edit/10'
+
+### Assigning Data
+
+Assigning data to a view is very simple. Ramaze will copy all instance variables
+from the current controller into the view. This means that if you have a variable
+@user set to "Yorick Peterse" this variable can be displayed in your view as
+following (assuming you're using Etanni):
+
+    <p>Username: #{@user}</p>
+
+Besides this you can assign custom data to a view by calling any of the render
+methods and passing a hash to them.
+
+Please note that the behavior or the syntax of displaying variables may change
+depending on the template engine you're using. While Etanni allows you to execute
+plain Ruby code in your view a template engine such as Mustache won't and thus
+may have a different syntax. If we wanted to use Mustache and display our @user
+variable it would have to be done as following:
+
+    <p>Username: {{user}}</p>
+
+## View Mapping
+
+Views are saved in the directory "view" and are saved according to the controller
+mapping. If you have a controller that's mapped to /modules/blog the index view
+will be located at view/modules/blog/index.xhtml. Below are a few examples that
+show where the views are located when passing different values to the map()
+method.
+
+    map '/'             # view/index.html, view/edit.xhtml, etc
+    map '/blog'         # view/blog/index.xhtml, view/blog/edit.xhtml, etc
+    map '/modules/blog' # view/modules/blog/index.xhtml, view/modules/blog/edit.xhtml, etc
+
+## Template Engines
+
+Ramaze ships with support for the following template engines:
+
+* Erector
+* Etanni
+* Erubis
+* Ezamar
+* HAML
+* Less
+* Gestalt
+* Liquid
+* Lokar
+* Mustache
+* Nagoro
+* Remarkably
+* Sass
+* Slippers
+* Tagz
+* Tenjin
+
+All of these engines can be used on a per controller basis by calling the
+engine() method and passing a symbol or string to it.
+
+    class Blogs < Ramaze::Controller
+      engine :etanni
+    end
+
+The engine() method uses the provide() method (more on that in a second) to set
+the given engine for all data sent back to the visitor with a content type of
+"text/html". If you want to use a certain engine for a different content type
+(e.g. application/json) you can do so using the provide() method:
+
+    class Blogs < Ramaze::Controller
+      # Simple right?
+      provide(:json, :erb)
+
+      # Somewhat more verbose
+      provide(:json, :engine => :erb)
+
+      # AWESOME!
+      provide(:json, :type => 'application/json') do |action, value|
+        # "value" is the response body from our controller's method
+        value.to_json
+      end
+    end
+
+It's important to remember that the actions in the provide() method will only
+be executed if it's first parameter (in this case "json") are appended to the
+URL as an extension. A request to /hello would output HTML when using the above
+code, if we wanted JSON we'd have to send a request to /hello.json.
+
+The default template engine used by Ramaze is Etanni. Etanni is a small template
+engine that ships with Ramaze (and Innate!) that's extremely fast and has a very
+simple syntax. Statements are wrapped in <?r ?> tags and rendering data can be
+done by wrapping the variables in ``#{}``:
+
+    # <?r ?> accepts regular Ruby code
+    <?r if @user.name === 'yorick' ?>
+    <p>Hello Yorick</p>
+    <?r else ?>
+    <p>And who are you?</p>
+    <?r end ?>
+
+    # Display our name
+    #{@user.name}
+
+Etanni can be very useful for most project but it's *not* recommended to use it
+when you want to allow a client to manage certain templates (e.g. Email layouts).
+This is because Etanni allows you to execute regular Ruby code and thus someone
+could do some serious damage to your server without even knowing it.