Home

Installation

$ gem install flame

Application

Rackup

run MyProject::Application # or `run MyProject::Application.new`

Mounting

Mount controllers in application-class by mount method.

Namespace path as class-name without Controller or Ctrl by default.

Paths and HTTP-methods for controller's public-methods as REST and others as GET by default.

Mounting ParrentController:

# parent_controller.rb

class ParentController < Flame::Controller
  def hello_world
    'Hello, world!'
  end

  def my_name(name, last_name = nil)
    "My name is #{name} #{last_name}"
  end

  def bye
    'Bye!'
  end
end

# rest_controller.rb

class RESTController < Flame::Controller
  def index
    view # :index
  end

  def new
    view # :new
  end

  def create
    Model.create(model_params)
    redirect :index
  end

  def show(id)
    @model = Model.first(id)
    view # :show
  end

  def update(id)
    @model = Model.first(id)
    @model.update(model_params)
    redirect :show
  end

  def delete(id)
    @model = Model.first(id)
    @model.destroy
    redirect :index
  end

  private

  def model_params
    params[:model]
  end
end

# application.rb

# ...

mount ParentController
  ## path => '/parent'
  ## routes =>
  ##   GET '/parent/hello' => :hello
  ##   GET '/parent/my_name/:name/:?last_name' => :my_name
  ##   GET '/parent/bye' => :bye

mount RESTController, '/model'
  ## path => '/model'
  ## routes =>
  ##   GET '/' => :index
  ##   GET '/new' => :new
  ##   POST '/' => :create
  ##   GET '/:id' => :show
  ##   PUT '/:id' => :update
  ##   DELETE '/:id' => :delete
# ...

For other path specify it as argument:

mount ParentController, '/other_path'
  ## path => '/other_path'

For others HTTP methods or URL-paths use block as route-refines:

mount ParentController do
  get '/hello', :hello_world
    ## `get` - HTTP-method
    ## '/hello' - new URL-path
    ## :hello_world - controller's method name
  post :bye
    ## `post` - HTTP-method
    ## URL-path as method-name by default
    ## :bye - controller's method name

  defaults
    ## if you don't refine all public-method of controller (as `:my_name` for now)
    ## you must write this method in block after all refining
    ## for mounting remaining methods by default
    ## (REST-matching, or with GET HTTP-method and path as method-name)

  # You can mount children controllers
  mount ChildController, '/children' # path will be '/parent/children'
end

You must specify method-arguments in path when refining:

# controller.rb

  def hello(first_name, last_name = nil)
  end

# application.rb

  ## default path => '/hello/:first_name/:?last_name'
  ##   :first_name - required argument
  ##   :?last_name - not required
  get '/hello_world/:first_name/:?last_name', :hello

REST

Default available REST:

get '/', :index
post '/', :create
get '/:id', :show
put '/:id', :update
delete '/:id', :delete

:show, :update and :delete methods by default must have id argument:

# controller.rb

  def show(id)
  end

Config

Application config available by config method. Config-object like a Hash.

Root directory of application available by config[:root_dir]

Also available :public_dir, :views_dir and :config_dir

Config options may be proc and called by #[]:

config[:locales_dir] = proc { File.join(config[:root_dir], 'locales' }
# config[:locales_dir] => '%app_root_dir%/locales'

Environment also available: config[:environment] # => ENV['RACK_ENV'] or 'development'

Config-object available from controllers

Controllers

Scopes

Public instance methods (not inherited) - your actions.

execute protected method is wrapper for any action execute, action-name (method-name) is argument. In this method you can write or invoke before-hooks, than call super (for ancestors execute method, and in the end of target-method call), then and after-hooks. execute method can be mixed by include or prepend. Also you can handling errors in execute method by rescue (re-raising of exception is recommended).

Private methods for helpers (model_params, for example).

Get current response body: body. Set: body 'New body'.

status works the same.

Also available as Hash request.headers, response.headers, cookies and session.

view or render (alias) receive file-name of template as String or Symbol (and options for Tilt), and return rendering file as String.

path_to method for building path to the controller and it's action: path_to ArticlesController, :show, id: 2 for show(id) method of ArticlesController.

Return value of called method (action) will be body of response.

module MyProject
  class SiteController < Flame::Controller
    ## public method - end-point
    def index
      view # or `view :index` (default name of template is method-name)
    end
  end

  class APIController < Flame::Controller
    include APIHelper # That's out helper module! Described below

    ## public method - end-point
    ## returns Hash
    def index
      { result: 'success', data: 'Welcome!' }
    end

    # And 404 handling!
    # Attention: hooks will executing (not_found method calling as `super` in `execute` method)
    def not_found
      view :'error/404'
    end
  end
end

Helpers

Helpers is just including modules for Controllers

module MyProject
  module APIHelper
    # Method for after-hook in controller above
    def to_json(content = body)
      response.headers[Rack::CONTENT_TYPE] = 'application/json; charset=utf-8'
      body JSON.generate(content)
    end

    protected

    # Method for overriding controller executing (any route)
    # Must be protected
    def execute(method)
      # before hooks
      check_access!
      # You can also check which method is calling (`method` argument)
      super # execute calling method
      # after hooks
      to_json body
    rescue => exception # 500 error handling
      body render :'errors/500' # `render` is alias for `view`
      raise exception # needing for base-controllers or helpers
    end
  end
end

Views

Flame::Render use Tilt engine.

Caching enabled in production and disabled in development (config[:environment]).

Methods for rendering: view (recommended for controller's methods) and render (recommended for partial renders at view, but alias for view). Receive file-name as String or Symbol, and render-options.

Layouts are supported by default (if compiled layout.* file found). Also nested layouts.

If file-name beginning from _ (_part.erb) - layout is disabled by default.

All controllers methods are available from templates (controller's scope by default).

Models

No models by Flame. Use what you want. I recommend Sequel.

Conclusion

Good luck!

Reports, issues, pull-requests and other cooperation are welcome.