====== Installing Ramaze ======

The simplest way of installing Ramaze is to use the [[http://rubygems.org|Rubygems]] package manager:

  $ gem install ramaze

To get the latest Ramaze code from the darcs repository instead, read [[Contributing]]. Alternatively, install the latest [[http://manveru.net/gems/ramaze-nightly/|Ramaze nightly gem]]:

  $ wget http://manveru.net/gems/ramaze-nightly/ramaze-nightly.gem
  $ gem install ramaze-nightly.gem

Note: For Windows users, you may wish to install the win32console gem. This will both satisfy the warning generated by ramaze as well as give you pretty colors when you run your server.

  $ gem install win32console

====== Ramaze Basics ======

===== The Controller =====

The basic building block of a Ramaze application is the Controller. A simple Ramaze app will usually contain one controller named MainController.

<code ruby>
class MainController < Ramaze::Controller
end
</code>

By default, MainController maps to '/'. You can create additional controllers that map to other urls.

<code ruby>
class AnotherController < Ramaze::Controller
  map '/another'
end
</code>


===== Actions and Helpers =====

Methods defined inside controllers are of two types:
  * public methods are known as actions (these are accessible via the web)
  * private methods are known as helpers (for functionality commonly used via actions and templates)

==== Actions ====

The ''index'' action is called by default when no other URL is provided. Below, accessing http://localhost:7000 invokes this ''index'' method and the return value, "Hello World" is rendered to the browser.

<code ruby>
class MainController < Ramaze::Controller
  def index
    # http://localhost:7000
    "Hello, World!"
  end
end
</code>

Controllers can be mounted onto different urls with the ''map'' directive. A mapped controller will only respond to requests that are prefixed with the supplied mapping. Below, http://localhost:7000/another/hello will invoke ''AnotherController'''s method ''hello''.

<code ruby>
class AnotherController < Ramaze::Controller
  map '/another'
  
  def hello
    # http://localhost:7000/another/hello
    "Hello Another"
  end
end
</code>

Your action methods can accept arguments in two ways- get/post variables and via the url. For example, if you accessed http://localhost:7000/add/A/B?number=one

<code ruby>
class MainController < Ramaze::Controller
  def add(first, second)
    # http://localhost:7000/add/A/B?number=one

    # request.get? == true
    # first == 'A'
    # second == 'B'
    # request['number'] == 'one'
  end
end
</code>

Default values for method params, like with ''def add first, second, third = "C"'', will work as expected.

Finally, use two underscores instead of a forward slash, or define_method for actions that contain a period or slash

<code ruby>
class MainController < Ramaze::Controller
  def admin__setup
    # http://localhost:7000/admin/setup
  end

  define_method 'style.css' do
    # http://localhost:7000/style.css
  end

  define_method 'admin/app.js' do
    # http://localhost:7000/admin/app.js
  end
end
</code>

==== Helpers ====

Private helper methods can be defined in the controller and reused by different actions and templates.

<code ruby>
class AnotherController < Ramaze::Controller
  map '/another'
  
  def hello
    greeting
  end

  def goodbye
    greeting 'Goodbye'
  end

  private
  
  def greeting(g='Hello')
    "#{g}, World!"
  end
end
</code>

The private method ''greeting'' above cannot be accessed via the web. 

Ramaze includes a number of default and optional helpers, including a [[features:helpers#session-flash|session]], [[features:helpers#aspect|aspect]] (to run code before or after actions) and [[features:helpers#cache|caching]] helper. For more information, refer to the [[features:helpers|Helpers]] page.

===== Templates =====

Ramaze supports both inline and external templates. The value returned by an action method is run through the templating engine of your choice. By default, controllers use the bundled Ezamar templating engine.

<code ruby>
class MainController < Ramaze::Controller
  def index
    %q(
        <?r @str = "abc" ?>
        @str is #{@str}
      )
  end
end
</code>

To simply render the returned value instead, use the ''None'' template engine.

<code ruby>
class MainController < Ramaze::Controller
  engine :None

  def index
    'Hello world. This is not evaluated: <?r @str = "abc" ?> #@str'
  end
end
</code>

Ramaze includes support for a variety of templating engines, including [[features:templates#haml|Haml]], [[features:templates#erubis|Erubis]], [[features:templates#liquid|Liquid]] and [[features:templates#markaby|Markaby]]. For a full list and more information on using external templates, check the [[features:templates|Templates]] page.

===== Layouts =====

To wrap your actions in a layout, simply create an inline or external template that uses ''@content'' and set it as a layout in your controller.

<code ruby>
class MainController < Ramaze::Controller
  def index
    'Hi there!'
  end

  def layout
    %q( <html> #{@content} </html> )
  end

  # apply to all actions
  layout :layout

  # apply to all actions except index
  layout :layout
  deny_layout :index

  # apply only to index
  layout :layout => [ :index ]
end
</code>


===== Routing =====

Ramaze support simple routing using string, regex and lambda based routers.
Routes are stored in a dictionary, which supports hash-like access but
preserves order, so routes are evaluated in the order they are added.

String routers are the simplest way to route in Ramaze. One path is
translated into another:

<code ruby>
  Ramaze::Route[ '/foo' ] = '/bar'

  #  '/foo'  =>  '/bar'
</code>

Regex routers allow matching against paths using regex. Matches within
your regex using () are substituted in the new path using printf-like
syntax.

<code ruby>
  Ramaze::Route[ %r!^/(\d+)\.te?xt$! ] = "/text/%d"

  #  '/123.txt'  =>  '/text/123'
  #  '/789.text' =>  '/text/789'
</code>

For more complex routing, lambda routers can be used. Lambda routers are
passed in the current path and request object, and must return either a new
path string, or nil.

<code ruby>
  Ramaze::Route[ 'name of route' ] = lambda{ |path, request|
    '/bar' if path == '/foo' and request[:bar] == '1'
  }

  #  '/foo'        =>  '/foo'
  #  '/foo?bar=1'  =>  '/bar'
</code>

Lambda routers can also use this alternative syntax:

<code ruby>
  Ramaze::Route('name of route') do |path, request|
    '/bar' if path == '/foo' and request[:bar] == '1'
  end
</code>


===== Error Handling =====

Errors raised in your actions are caught by the Ramaze dispatcher and sent to an ''error'' action in your controller. If an ''error'' action or template does not exist, the default Ramaze::Controller ''error'' action is used instead, and the error message and backtrace are rendered to the browser.

Use your own custom error handler as follows:

<code ruby>
class MainController < Ramaze::Controller
  def error
    @error = Ramaze::Error.current
    %(
      <h1>Error: #{@error.message}</h1>
      <div>
        #{@error.backtrace.join('<br/>')}
      </div>
    )
  end
end
</code>

You can also configure what error action is used based on the exception raised:

<code ruby>
Ramaze::Dispatcher::Error::HANDLE_ERROR[Og::Exception] = [ Ramaze::STATUS_CODE['Conflict'],
                                                           '/ogerror' ]
</code>

In this case, any Og::Exception errors raised will return a HTTP status code 409 and render the ''/ogerror'' action to the browser.

===== Running your app =====

Running your Ramaze app is easy, just add a Ramaze.start to the end of the file and use ''ruby file.rb''

Ramaze can accept a number of options to configure what adapter to use, what port to run on, etc. There are [[http://source.ramaze.net/#/lib/ramaze/global.rb|various configuration options]] available, and [[faq#how-do-i-set-ramaze-options|several ways to set them]]. The most common way is to provide these options to Ramaze.start as follows:

<code ruby>
require 'rubygems'
require 'ramaze'

class MainController < Ramaze::Controller
  def index(); 'hello, world!!'; end
end

Ramaze.start :adapter => :mongrel, :port => 7000
</code>

<code bash>
$ ruby file.rb
INFO   Starting up Ramaze (Version 0.2.1)
DEBUG  mapped Controllers: {"/"=>MainController}
INFO   Adapter: Ramaze::Adapter::Mongrel, testing connection to 0.0.0.0:7000..7000
INFO   and we are running: 0.0.0.0:7000..7000
</code>

Ramaze includes support for several adapters, including [[features:adapters#mongrel|Mongrel]], [[features:adapters#evented-mongrel|Evented Mongrel]] and [[features:adapters#fcgi|FastCGI]]. Read more on the [[features:adapters|Adapters]] page.

For Nginx and Apache deployment recipes, check out the [[Deploying]] page.

====== Examples ======

A few more examples to get you started. These and many others are available at http://darcs.ramaze.net/ramaze/examples/. There is also an [[http://darcs.ramaze.net/ramaze/doc/tutorial/todolist.html|introductory tutorial]] that accompanies the [[http://darcs.ramaze.net/ramaze/examples/todolist/|todolist example]].

The best way to view [[http://source.ramaze.net/#/examples|these examples]], and browse around the ramaze source code is via the [[http://source.ramaze.net/#/examples/sourceview/sourceview.rb|Ramaze source code browser]]

===== hello.rb =====
<code ruby>
require 'ramaze'

# you can access it now with http://localhost:7000/
# This should output
# Hello, World!
# in your browser

class MainController < Ramaze::Controller
  def index
    "Hello, World!"
  end
end

Ramaze.start
</code>

===== simple.rb =====
<code ruby>
require 'ramaze'

# A very simple little application, you can simply run it and
# point your browser to http://localhost:7000
# you can change the port by setting
# Ramaze::Global.port = 80 or Ramaze.start :port => 80
# this most likely requires root-privileges though.

# This example shows following (requests to the mentioned base-url) :
# - simple text-output from the controller    [ / ]
# - showing you what your request looked like [ /simple ]
# - joining two strings                       [ /join/string1/string2 ]
# - join arbitary strings                     [ /join_all/string1/string2/string3 ... ]
# - sum two numbers                           [ /sum/1/3 ]
# - show if you made a POST or GET request    [ /post_or_get ]
# - How to map your controllers to urls       [ /other ]
# - Also try out the error-page, just pass something odd ;)

class SimpleController < Ramaze::Controller
  map '/'

  def index
    "simple"
  end

  def simple
    request.inspect
  end

  def join(first, second)
    [first, second].join
  end

  def join_all(*strings)
    strings.join
  end
  
  def sum(first, second)
    first.to_i + second.to_i
  end
  
  def post_or_get
    request.post? ? 'POST' : 'GET'
  end
end

class OtherController < Ramaze::Controller
  map '/other'

  def index
    "Hello, World from #{self.class.name}"
  end
end

Ramaze.start
</code>

===== element.rb =====
<code ruby>
require 'ramaze'

class Page < Ezamar::Element
  def render
    %{
    <html>
      <head>
        <title>examples/element</title>
      </head>
      <body>
        <h1>#{@title}</h1>
        #{content}
      </body>
    </html>
    }
  end
end

class SideBar < Ezamar::Element
  def render
    %{
    <div class="sidebar">
      <a href="http://something.com">something</a>
    </div>
    }
  end
end

class MainController < Ramaze::Controller
  map '/'

  def index
    %{
    <Page title="Test">
      <SideBar />
      <p>
        Hello, World!
      </p>
    </Page>
    }
  end
end

Ramaze.start
</code>

===== layout.rb =====
<code ruby>
require 'ramaze'

class MainController < Ramaze::Controller
  map '/'
  layout :page

  def index
    @title = "Test"
    "<p>Hello, World!</p>"
  end

  def page
    %{
    <html>
      <head>
        <title>examples/layout</title>
      </head>
      <body>
        <h1>#@title</h1>
        #@content
      </body>
    </html>
    }
  end
end

Ramaze.start
</code>