Tennpipes
(tennpipes-base)¶ ↑
Tennpipes
is the framework based on Sinatra
.
Preface¶ ↑
Tennpipes
is a ruby framework built upon the excellent Sinatra Microframework. 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 Tennpipes
framework:
- Agnostic
-
Full support for many popular testing, templating, mocking, and data storage choices.
- Generators
-
Create
Tennpipes
applications, models, controllers i.e: tennpipes-init project. - Mountable
-
Unlike other ruby frameworks, principally designed for mounting multiple apps.
- Routing
-
Full url named routes, named params, 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 or use them altogether for a comprehensive upgrade to Sinatra
(a full-stack Tennpipes
application).
Installation¶ ↑
To install the tennpipes framework, simply grab the latest version from gemcutter:
$ sudo gem install tennpipes
This will install the necessary tennpipes gems to get you started. Now you are ready to use this gem to enhance your sinatra projects or to create new Tennpipes
applications.
For a more detailed look at Tennpipes
installation, check out the Installation Guide.
Usage¶ ↑
Tennpipes
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 Tennpipes
documentation in general will focus on the enhancements to the core Sinatra
functionality. To use Tennpipes
, one should be familiar with the basic usage of Sinatra
itself.
Please check out the Understanding Sinatra 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 Tennpipes in Sinatra.
Getting Started¶ ↑
Once a developer understands Sinatra
, Tennpipes
is quite easy to get comfortable with since Tennpipes
is simply a superset of existing Sinatra
Functionality! Best way to get started with building Tennpipes
applications is to read following resources:
-
Blog Tutorial - Step-by-step guide to building a blog application with
Tennpipes
. -
Quick Overview - Outlines basic generation commands.
-
Tennpipes Examples - List of known
Tennpipes
applications which can serve as examples.
Enhanced Base Application (tennpipes-base)¶ ↑
Sinatra
has support for classes which can be extended to create an application: Sinatra::Base
and Sinatra::Application
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
.
Tennpipes
has support for an enhanced base application class Tennpipes::Application
. Tennpipes::Application
expands the capabilities of Sinatra::Application and automatically provides the resulting application access to all of the tennpipes framework's functionalities.
Simple Application Definition¶ ↑
Let us first take a look at the simplest possible Tennpipes
application:
# app.rb TENNPIPES_ROOT = File.dirname(__FILE__) unless defined? TENNPIPES_ROOT require 'tennpipes' Tennpipes.load! class SimpleApp < Tennpipes::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 Tennpipes
routing and controller system, check out the Routing and Controller guide.
Suppose we wanted to add additional routes to our Tennpipes
application, and we want to organize the routes within a more structured layout. Simply add a controllers
or app/controllers
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 provides
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], :provides => [: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 Tennpipes
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.
Rendering¶ ↑
Unlike Sinatra
, Tennpipes
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 Tennpipes
rendering system, check out the Routing and Controller guide.
Layout¶ ↑
With Tennpipes
you can (like rails do) use for your custom layout, disable it
class SimpleApp < Tennpipes::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.
Mounting Applications¶ ↑
Tennpipes
applications are all automatically mountable into other Tennpipes
projects. This means that a given Tennpipes
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.
Tennpipes
stores application mounting information by default within config/apps.rb
. 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 Tennpipes
project, check out the guide on Mounting Applications.
Auto Load Paths¶ ↑
Tennpipes
also intelligently supports requiring useful files within your application automatically and provides functionality for easily splitting up your application into separate files. Tennpipes
automatically requires config/database.rb
as a convention for establishing database connection. Also, any files within the lib
folder will be required automatically by Tennpipes
.
For a complete overview of auto-loaded paths within Tennpipes
, check out the Tennpipes Development Guide.
Application Logging¶ ↑
Tennpipes
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 log/development.log
in test and production environments.
To use the logger within a Tennpipes
application, simply refer to the logger
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 Tennpipes
logger functionality, check out the Tennpipes Development Guide.
Development Reloader¶ ↑
Tennpipes
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 Tennpipes Development Guide.
Terminal Commands¶ ↑
Tennpipes
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) $ tennpipes start # starts the app server (daemonized) with given port, environment and adapter $ tennpipes start -d -p 3000 -e development -a thin # Stops a daemonized app server $ tennpipes stop # Bootup the Tennpipes console (irb) $ tennpipes console # Run/List tasks $ tennpipes 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 Tennpipes
terminal commands, check out the Tennpipes Commands Guide.
Copyright¶ ↑
Copyright © 2011-2013 Tennpipes
. See LICENSE for details.