ramaze 0.3.9.1 → 2023.01.06

data/guide/general/testing.md

@@ -0,0 +1,228 @@
+# @title Testing Ramaze
+# Testing Ramaze
+
+Ramaze uses and encourages BDD (Behaviour Driven Development). Ramaze itself is
+tested using [Bacon][bacon] and supports it out of the box, it however isn't
+limited to just Bacon.
+
+One might wonder why to bother with writing tests. The answer to this is quite
+simple: stability. Manually testing an application works on a very basic level
+but there are various issues that will arise once your application grows. The
+two biggest issues are human errors and repeatability. Especially the latter
+becomes an issue when your development team grows in size, while the initial
+developer may be willing to manually test every feature every time a change has
+been made others might not. Even worse, there's a chance they won't test their
+code at all and assume it's production ready because on their setup.
+
+Writing tests that can be executed using a single command (or automatically)
+makes your life a lot easier as you no longer have to worry about any of these
+issues (assuming people actually write tests). Whenever somebody commits code
+they write a test and you can easily verify if it works on different setups by
+simply running said test.
+
+When writing Ruby code you can pick from a large collection of testing libraries
+such as Bacon and [Rspec][rspec] for general tests, [SimpleCov][simplecov] for
+code coverage and [Capybara][capybara] for testing form based actions and the
+like. Of course the list doesn't stop here, there's simply too much to discuss
+everything.
+
+## Bacon
+
+Bacon is a small and lightweight Rspec clone that's used by Ramaze and Innate
+and is the recommended tool to use. Each bacon test consists out of at least two
+bits: a "describe" block and an "it" (or "should") block. The describe block can
+be seen as a group of multiple it/should blocks. In most cases these blocks are
+used to specify the name of a class, module, etc. The it/should blocks are used
+for individual tests.
+
+Lets take a look at a simple block of code:
+
+    class Person
+      attr_accessor :name
+
+      def initialize(name = nil)
+        @name = name
+      end
+    end
+
+Using Bacon we can test this code as following:
+
+    require 'bacon'
+
+    describe 'Person' do
+      should 'respond to #name' do
+        person = Person.new
+
+        person.respond_to?(:name).should  == true
+        person.respond_to?(:name=).should == true
+      end
+
+      should 'set the name in the constructor' do
+        person = Person.new('Matz')
+
+        person.name.should == 'Matz'
+      end
+
+      should 'set the name using #name=' do
+        person = Person.new
+
+        person.name = 'Matz'
+
+        person.name.should == 'Matz'
+      end
+    end
+
+For more information on the syntax of Bacon and other information see the
+[Bacon Github project][bacon].
+
+### Bacon With Ramaze
+
+Ramaze makes it easy to test your code using Bacon by providing you with a small
+helper file. This file can be loaded as following:
+
+    require 'ramaze/spec/bacon'
+
+This file adds two bacon contexts (rack_test and webrat), configures Ramaze to
+only show error messages and adds a few helper methods.
+
+### Bacon and Rack::Test
+
+In order to test Ramaze specific code you'll need to use a tool that's capable
+of mocking Rack requests or execute this request in a different way (e.g. using
+Selenium). Rack::Test (gem install rack-test) makes it possible to test your
+Rack based (and thus Ramaze) applications without having to use a webbrowser.
+
+Ramaze makes it easy to use Rack::Test by defining a special bacon context:
+"rack_test". This context can be used by calling `behaves_like :rack_test`
+inside your describe block:
+
+    describe 'Using Rack::Test' do
+      behaves_like :rack_test
+    end
+
+Once loaded you can execute HTTP requests using methods such as `get`:
+
+    describe 'Using Rack::Test' do
+      behaves_like :rack_test
+
+      should 'display the homepage' do
+        get('/').body.should == 'Hello, Rack::Test!'
+      end
+    end
+
+More information about Rack::Test can be found on the [Github page of
+Rack::Test][rack-test].
+
+## Capybara
+
+Capybara is a Gem that can be used to simulate browser requests using
+Rack::Test, Selenium or other drivers, it's even capable of testing Javascript
+based code using Selenium.
+
+In order to use Capybara you must first install it:
+
+    $ gem install capybara
+
+Once installed you'll have to configure Capybara so it knows how to use your
+Ramaze application. Depending on the testing Gem you're using you'll also have
+to configure said Gem, for this guide it's assumed that you're using Bacon.
+
+First you should load and configure Capybara:
+
+    require 'capybara'
+    require 'capybara/dsl'
+    require 'bacon'
+
+    # Tells Capybara which driver to use and where to find your application.
+    # Without this Capybara will not work properly.
+    Capybara.configure do |config|
+      config.default_driver = :rack_test
+      config.app            = Ramaze.middleware
+    end
+
+Next you'll have to set up a context for Bacon:
+
+    shared :capybara do
+      Ramaze.setup_dependencies
+      extend Capybara::DSL
+    end
+
+Last but not least, make sure Ramaze knows about your root directories and set
+your mode:
+
+    Ramaze.options.roots << 'path/to/spec/directory'
+    Ramaze.options.mode  = :spec
+
+Once all of this has been done you can start using Capybara. A simple example of
+this is the following:
+
+    class MainController < Ramaze::Controller
+      map '/'
+
+      def index
+        return 'Hello, Ramaze!'
+      end
+
+      def redirect_request
+        redirect(MainController.r(:index))
+      end
+    end
+
+    describe 'Testing Ramaze' do
+      behaves_like :capybara
+
+      it 'Go to the homepage' do
+        visit '/'
+
+        page.has_content?('Hello, Ramaze!').should == true
+      end
+
+      it 'Follow redirects' do
+        visit '/redirect_request'
+
+        page.current_path.should == '/index'
+        page.has_content?('Hello, Ramaze!').should == true
+      end
+    end
+
+For more information on how to use Capybara with other testing tools, how to use
+the syntax and so on you should resort to the [Capybara Github page][capybara].
+
+## Code Coverage using SimpleCov
+
+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
+to view the results.
+
+For more information on using Simplecov see the [Github project][simplecov].
+
+[bacon]: https://github.com/chneukirchen/bacon
+[simplecov]: https://github.com/colszowka/simplecov
+[rspec]: http://relishapp.com/rspec
+[capybara]: http://jnicklas.github.com/capybara/
+[rack-test]: https://github.com/brynary/rack-test

data/guide/general/upgrading.md

@@ -0,0 +1,85 @@
+# @title Upgrading
+# Upgrading
+
+Ramaze strives to be backwards compatible between each release. However, some
+releases may contain changes that are *not* backwards compatible. This document
+describes the steps required to upgrade between these releases.
+
+## Upgrading to Ramaze 2012.12.08
+
+Ramaze 2012.12.08 is **not** backwards compatible with previous releases due
+to changes made in Innate 2012.12.
+
+### Middleware
+
+In previous versions one could add Rack middleware using `Ramaze.middleware!`.
+This method has been renamed to `Ramaze.middleware` (without the `!`) and its
+use has been changed. Instead of calling `run Ramaze.middleware` one now has to
+use `run Ramaze.core`.
+
+An example of the old way of defining middleware:
+
+    Ramaze.middleware! :dev do |m|
+      m.use Rack::Lint
+      m.run Ramaze.middleware
+    end
+
+The new way of defining middleware:
+
+    Ramaze.middleware :dev do
+      use Rack::Lint
+      run Ramaze.core
+    end
+
+### Commands
+
+Various executable commands such as `ramaze start` and `ramaze console` have
+been removed in favour of the use of Rake tasks. For existing projects that do
+not have these Rake tasks you'll have to import them manually, new projects
+will have these tasks automatically. These tasks are located [here][rake
+tasks].
+
+These commands were removed as they contained a lot of old and rotting code
+without any tests. Some of them, such as `ramaze start` weren't very useful
+either as most people will use the commands for their webservers (e.g. Thin)
+instead. The use of Rake tasks also makes it possible for people to customize
+these to their liking.
+
+### Snippets
+
+Ramaze ships with various snippets that extend various core Ruby classes. In
+Ramaze 2012.12.08 a lot of these snippets have been removed. A list of all the
+removed snippets can be found [here][removed snippets].
+
+### Loggers
+
+The following logging classes are no longer available:
+
+* Ramaze::Logger::Growl
+* Ramaze::Logger::Analogger
+* Ramaze::Logger::Knotify
+* Ramaze::Logger::Xosd
+
+### Helpers
+
+The following helpers have been removed:
+
+* Ramaze::Helper::Disqus
+* Ramaze::Helper::Ultraviolet
+
+### Core classes
+
+The following core classes have been removed:
+
+* Ramaze::AppGraph
+* Ramaze::Plugin
+* Ramaze::MiddlewareCompiler (alias of Innate::MiddlewareCompiler)
+
+### Prototypes
+
+The prototype generated by `ramaze create` has been changed. It contains a set
+of Rake tasks, a README, a Gemfile and some other small changes compared to the
+previous prototype. Existing projects are not affected.
+
+[rake tasks]: https://github.com/Ramaze/ramaze/blob/master/lib/proto/task/ramaze.rake
+[removed snippets]: https://github.com/Ramaze/ramaze/commit/7e966dcdec50d490eb828f7673f101b1a6b087b3

data/guide/general/views.md

@@ -0,0 +1,335 @@
+# @title Views
+# 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
+
+<div class="note todo">
+    <p>
+        <strong>Note:</strong> layouts should be set <strong>outside</strong>
+        controller actions. Doing so can lead to unexpected behaviour as the
+        layout won't be visible until the next request.
+    </p>
+</div>
+
+## 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 similar to the `render_view` method but with
+two differences:
+
+1. This method *does* execute a matching action.
+2. This method *does not* render a layout.
+
+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.

data/lib/proto/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+gem 'ramaze'
+gem 'rake'

data/lib/proto/README.md

@@ -0,0 +1,35 @@
+# Ramaze Application
+
+Welcome to your new Ramaze application. This README serves as a starting point
+for writing an application using the code you just generated.
+
+Once you've started working on your application you'll probably want to update
+this README so that its contents reflect your application's state and purpose.
+
+## Requirements
+
+In order to run this application you'll need to have Ramaze 2.0.0 or newer and
+Rake. Optionally you can install Bundler and use it for Gem management, this
+can be done as following:
+
+    $ gem install bundler
+    $ bundle install
+
+## Rake Tasks
+
+This application comes with a few predefined Rake tasks that make it easy to
+get started. You can list these tasks by running `rake -T` or `rake -D` (this
+shows longer descriptions for tasks if there are any).
+
+For example, to start a Ramaze console using Pry you'd run the following
+command:
+
+    $ rake ramaze:pry
+
+## Resources
+
+In case you need help you can refer to the following resources:
+
+* Ramaze website: <http://ramaze.net/>
+* Github repository: <https://github.com/ramaze/ramaze>
+* IRC channel: \#ramaze on Freenode

data/lib/proto/Rakefile

@@ -0,0 +1 @@
+Dir.glob(File.expand_path('../task/*.rake', __FILE__)) { |task| import task }

data/lib/proto/app.rb

@@ -0,0 +1,9 @@
+# This file contains your application, it requires dependencies and necessary
+# parts of the application.
+require 'rubygems'
+require 'ramaze'
+
+# Make sure that Ramaze knows where you are
+Ramaze.options.roots = [__DIR__]
+
+require __DIR__('controller/init')