295 lines
12 KiB
Plaintext
295 lines
12 KiB
Plaintext
|
= Padrino (padrino-core)
|
||
|
|
||
|
Padrino is the godfather of Sinatra.
|
||
|
|
||
|
== Preface
|
||
|
|
||
|
Padrino is a ruby framework built upon the excellent {Sinatra Microframework}[http://www.sinatrarb.com].
|
||
|
Sinatra is a DSL for creating simple web applications in Ruby with speed and minimal effort.
|
||
|
This framework tries hard to make it as fun and easy as possible to code much more advanced web applications by
|
||
|
building upon the Sinatra philosophies and foundation.
|
||
|
|
||
|
== Introduction
|
||
|
|
||
|
Many people love Sinatra's simplicity and lightweight but often quickly come to miss a great deal
|
||
|
of functionality provided by other web frameworks such as Rails when building non-trivial applications.
|
||
|
|
||
|
Our goal with this framework is to match the essence of Sinatra and at the same time create a standard library
|
||
|
of tools, helpers and components that will make Sinatra suitable for more complex applications.
|
||
|
|
||
|
Here is a brief overview of functionality provided by the Padrino framework:
|
||
|
|
||
|
Agnostic:: Full support for many popular testing, templating, mocking, and data storage choices.
|
||
|
Generators:: Create Padrino applications, models, controllers i.e: padrino-gen project.
|
||
|
Mountable:: Unlike other ruby frameworks, principally designed for mounting multiple apps.
|
||
|
Routing:: Full url named routes, named params, respond_to support, before/after filter support.
|
||
|
Tag Helpers:: View helpers such as: tag, content_tag, input_tag.
|
||
|
Asset Helpers:: View helpers such as: link_to, image_tag, javascript_include_tag.
|
||
|
Form Helpers:: Builder support such as: form_tag, form_for, field_set_tag, text_field.
|
||
|
Text Helpers:: Useful formatting like: time_ago_in_words, js_escape_html, sanitize_html.
|
||
|
Mailer:: Fast and simple delivery support for sending emails (akin to ActionMailer).
|
||
|
Admin:: Builtin Admin interface (like Django)
|
||
|
Logging:: Provide a unified logger that can interact with your ORM or any library.
|
||
|
Reloading:: Automatically reloads server code during development.
|
||
|
Localization:: Full support of I18n language localization and can auto-set user's locale.
|
||
|
|
||
|
Keep in mind, the user will be able to pull in these components
|
||
|
{seperately into existing Sinatra applications}[http://www.padrinorb.com/guides/standalone-usage-in-sinatra]
|
||
|
or use them altogether for a comprehensive upgrade to Sinatra (a full-stack Padrino application).
|
||
|
|
||
|
== Installation
|
||
|
|
||
|
To install the padrino framework, simply grab the latest version from gemcutter:
|
||
|
|
||
|
$ sudo gem install padrino
|
||
|
|
||
|
This will install the necessary padrino gems to get you started.
|
||
|
Now you are ready to use this gem to enhance your sinatra projects or to create new Padrino applications.
|
||
|
|
||
|
For a more detailed look at Padrino installation,
|
||
|
check out the {Installation Guide}[http://www.padrinorb.com/guides/installation].
|
||
|
|
||
|
== Usage
|
||
|
|
||
|
Padrino is a framework which builds on the existing functionality and Sinatra and provides a variety of
|
||
|
additional tools and helpers to build upon that foundation. This README and Padrino documentation in general will focus
|
||
|
on the enhancements to the core Sinatra functionality. To use Padrino, one should be familiar with the basic
|
||
|
usage of Sinatra itself.
|
||
|
|
||
|
Please check out the
|
||
|
{Understanding Sinatra}[http://www.padrinorb.com/guides/underlying-sinatra-overview] guide
|
||
|
to learn more about these fundamentals.
|
||
|
|
||
|
For information on how to use a specific gem in isolation within an existing Sinatra project, checkout the guide for
|
||
|
{Using Padrino in Sinatra}[http://www.padrinorb.com/guides/standalone-usage-in-sinatra].
|
||
|
|
||
|
== Getting Started
|
||
|
|
||
|
Once a developer understands Sinatra, Padrino is quite easy to get comfortable with since Padrino is simply a superset
|
||
|
of existing Sinatra Functionality! Best way to get started with building Padrino applications is to read following resources:
|
||
|
|
||
|
* {Blog Tutorial}[http://www.padrinorb.com/guides/blog-tutorial] - Step-by-step guide to building a blog application with Padrino.
|
||
|
* {Quick Overview}[http://www.padrinorb.com/guides/basic-projects] - Outlines basic generation commands.
|
||
|
* {Padrino Examples}[http://www.padrinorb.com/guides/examples] - List of known Padrino applications which can serve as examples.
|
||
|
|
||
|
== Enhanced Base Application (padrino-core)
|
||
|
|
||
|
Sinatra has support for classes which can be extended to create an application: <tt>Sinatra::Base</tt> and <tt>Sinatra::Application</tt>
|
||
|
These classes can be extended in order to create a Sinatra web application. These classes provide support for all the basic
|
||
|
functionality afforded by Sinatra.
|
||
|
|
||
|
Padrino has support for an enhanced base application class <tt>Padrino::Application</tt>. <tt>Padrino::Application</tt>
|
||
|
expands the capabilities of Sinatra::Application and automatically provides the resulting application access to all of
|
||
|
the padrino framework's functionalities.
|
||
|
|
||
|
=== Simple Application Definition
|
||
|
|
||
|
Let us first take a look at the simplest possible Padrino application:
|
||
|
|
||
|
# app.rb
|
||
|
PADRINO_ROOT = File.dirname(__FILE__) unless defined? PADRINO_ROOT
|
||
|
require 'padrino'
|
||
|
Padrino.load!
|
||
|
|
||
|
class SimpleApp < Padrino::Application
|
||
|
get '/' do
|
||
|
'Hello world'
|
||
|
end
|
||
|
|
||
|
# and for read better we can divide with controllers
|
||
|
controller '/admin' do
|
||
|
get '/foo' do
|
||
|
'Url is /admin/foo'
|
||
|
end
|
||
|
end
|
||
|
end
|
||
|
|
||
|
=== Enhanced Route Definitions and Controllers
|
||
|
|
||
|
For a complete overview of the Padrino routing and controller system,
|
||
|
check out the {Routing and Controller guide}[http://www.padrinorb.com/guides/controllers].
|
||
|
|
||
|
Suppose we wanted to add additional routes to our Padrino application, and we want to organize the routes
|
||
|
within a more structured layout. Simply add a <tt>controllers</tt> or <tt>app/controllers</tt> folder and create a file as such:
|
||
|
|
||
|
# Simple Example
|
||
|
SimpleApp.controllers do
|
||
|
get "/test" do
|
||
|
"Text to return"
|
||
|
end
|
||
|
end
|
||
|
|
||
|
You can also do more complex route alias definitions:
|
||
|
|
||
|
# app/controllers/example.rb
|
||
|
SimpleApp.controllers :posts do
|
||
|
get :index do
|
||
|
...
|
||
|
end
|
||
|
|
||
|
get :show, :with => :id do
|
||
|
# url generated is '/posts/show/:id'
|
||
|
# access params[:id]
|
||
|
end
|
||
|
end
|
||
|
|
||
|
as well as mapping the route aliases to an explicit url:
|
||
|
|
||
|
# app/controllers/example.rb
|
||
|
SimpleApp.controllers do
|
||
|
get :index, :map => '/index' do
|
||
|
...
|
||
|
end
|
||
|
|
||
|
get :account, :map => '/the/accounts/:name/and/:id' do
|
||
|
# access params[:name] and params[:index]
|
||
|
end
|
||
|
end
|
||
|
|
||
|
and even configure the respond_to for each route:
|
||
|
|
||
|
# app/controllers/example.rb
|
||
|
SimpleApp.controllers :admin do
|
||
|
get :show, :with => :id, :provides => :js do
|
||
|
"Url is /admin/show/#{params[:id]}.#{params[:format]}"
|
||
|
end
|
||
|
|
||
|
get :other, with => [:id, :name], respond_to => [:html, :json] do
|
||
|
case content_type
|
||
|
when :js then ... end
|
||
|
when :json then ... end
|
||
|
end
|
||
|
end
|
||
|
end
|
||
|
|
||
|
or auto lookup for current locale or content_type
|
||
|
|
||
|
# app/controllers/example.rb
|
||
|
SimpleApp.controllers :admin do
|
||
|
get :show, :with => :id, :provides => [html, :js] do
|
||
|
render "admin/show"
|
||
|
end
|
||
|
end
|
||
|
|
||
|
When you visit :+show+ and your I18n.locale == :ru Padrino try to look for "admin/show.ru.js.*" if nothing match that path
|
||
|
they try "admin/show.ru.*" then "admin/show.js.*" if none match return "admin/show.erb" (or other engine i.e. haml)
|
||
|
|
||
|
For a complete overview of the routing and controller system, check out the
|
||
|
{Routing and Controller guide}[http://www.padrinorb.com/guides/controllers].
|
||
|
|
||
|
=== Rendering
|
||
|
|
||
|
Unlike Sinatra, Padrino supports automatic template lookups such as:
|
||
|
|
||
|
# searches for 'account/index.{erb,haml,...}
|
||
|
render 'account/index'
|
||
|
|
||
|
This render does not require any template engine to be specified and will choose the first one that is discovered.
|
||
|
The existing render function works as well if an engine type should be specified:
|
||
|
|
||
|
# example.haml
|
||
|
render :haml, 'account/index'
|
||
|
|
||
|
For a complete overview of the Padrino rendering system, check out the
|
||
|
{Routing and Controller guide}[http://www.padrinorb.com/guides/controllers].
|
||
|
|
||
|
=== Layout
|
||
|
|
||
|
With Padrino you can (like rails do) use for your custom layout, disable it
|
||
|
|
||
|
class SimpleApp < Padrino::Application
|
||
|
|
||
|
# Disable layouts
|
||
|
disable layout
|
||
|
|
||
|
# Use the layout located in views/layouts/custom.haml
|
||
|
layout :custom
|
||
|
|
||
|
For a complete overview of the layout functionality,
|
||
|
check out the {Routing and Controller guide}[http://www.padrinorb.com/guides/controllers].
|
||
|
|
||
|
=== Mounting Applications
|
||
|
|
||
|
Padrino applications are all automatically mountable into other Padrino projects. This means that a given Padrino
|
||
|
project directory can easily mount multiple applications. This allows for better organization of complex applications,
|
||
|
re-usable applications that can be applied (i.e admin, auth, blog) and even more flexibility.
|
||
|
|
||
|
You can think of mountable applications as a 'full-featured' merb slice or rails engine. Instead of a separate construct,
|
||
|
any application can simply be packaged and mounted into another project.
|
||
|
|
||
|
Padrino stores application mounting information by default within <tt>config/apps.rb</tt>. This file is intended
|
||
|
to keep all information regarding what applications are mounted to which uri's.
|
||
|
|
||
|
For a complete look at mounting applications within a Padrino project,
|
||
|
check out the guide on {Mounting Applications}[http://www.padrinorb.com/guides/mounting-applications].
|
||
|
|
||
|
=== Auto Load Paths
|
||
|
|
||
|
Padrino also intelligently supports requiring useful files within your application automatically and provides
|
||
|
functionality for easily splitting up your application into separate files. Padrino automatically requires <tt>config/database.rb</tt>
|
||
|
as a convention for establishing database connection. Also, any files within the <tt>lib</tt> folder will be required
|
||
|
automatically by Padrino.
|
||
|
|
||
|
For a complete overview of auto-loaded paths within Padrino,
|
||
|
check out the {Padrino Development Guide}[http://www.padrinorb.com/guides/development-and-terminal-commands].
|
||
|
|
||
|
=== Application Logging
|
||
|
|
||
|
Padrino also supports robust logging capabilities. By default, logging information will
|
||
|
go to the STDOUT in development (for use in a console) and in an environment-specific log file <tt>log/development.log</tt>
|
||
|
in test and production environments.
|
||
|
|
||
|
To use the logger within a Padrino application, simply refer to the <tt>logger</tt> method accessible
|
||
|
within your app and any controller or views:
|
||
|
|
||
|
# controllers/example.rb
|
||
|
SimpleApp.controllers do
|
||
|
get("/test") { logger.info "This is a test" }
|
||
|
end
|
||
|
|
||
|
For a complete overview of Padrino logger functionality, check out the
|
||
|
{Padrino Development Guide}[http://www.padrinorb.com/guides/development-and-terminal-commands].
|
||
|
|
||
|
=== Development Reloader
|
||
|
|
||
|
Padrino applications also have the enabled ability to automatically reload all changing application files without
|
||
|
the need to restart the server. Through the use of a customized Rack middleware, all files on the 'load path'
|
||
|
are monitored and reloaded whenever changes are applied.
|
||
|
|
||
|
This makes rapid development much easier and provides a better alternative to 'shotgun' or 'rerun'
|
||
|
which requires the application server to be restarted which makes requests take much longer to complete.
|
||
|
|
||
|
For a complete overview of code reloading in development,
|
||
|
check out the {Padrino Development Guide}[http://www.padrinorb.com/guides/development-and-terminal-commands].
|
||
|
|
||
|
=== Terminal Commands
|
||
|
|
||
|
Padrino also comes equipped with multiple useful terminal commands which can be activated to perform
|
||
|
common tasks such as starting / stopping the application, executing the unit tests or activating an irb session.
|
||
|
|
||
|
The following commands are available:
|
||
|
|
||
|
# starts the app server (non-daemonized)
|
||
|
$ padrino start
|
||
|
# starts the app server (daemonized) with given port, environment and adapter
|
||
|
$ padrino start -d -p 3000 -e development -a thin
|
||
|
|
||
|
# Stops a daemonized app server
|
||
|
$ padrino stop
|
||
|
|
||
|
# Bootup the Padrino console (irb)
|
||
|
$ padrino console
|
||
|
|
||
|
# Run/List tasks
|
||
|
$ padrino rake
|
||
|
|
||
|
You can also create custom rake tasks as well. Using these commands can simplify common tasks
|
||
|
making development that much smoother.
|
||
|
|
||
|
For a complete overview of Padrino terminal commands, check out the
|
||
|
{Padrino Commands Guide}[http://www.padrinorb.com/guides/development-and-terminal-commands].
|
||
|
|
||
|
== Copyright
|
||
|
|
||
|
Copyright (c) 2011 Padrino. See LICENSE for details.
|