Como criar plugins para Rails

RAILTIES
OU

COMO DESENVOLVER
PLUGINS/GEMS PARA RAILS

Carlos Antonio blog.plataformatec.com.br @cantoniodasilva

$ WHOAMI


CARLOS ANTONIO DA SILVA

@cantoniodasilva


COMECEI COM
DESENVOLVIMENTO EM 2003

E COM RUBY E RAILS EM 2007


TRABALHO NA


DEVISE


SIMPLE_FORM


RESPONDERS


THE ROAD SO FAR

RAILS 2.3


RAILS 2.3

Já possuía a estrutura de Rails Engine.


RAILS 2.3


Mas...


RAILS 2.3


Mas...
podemos dizer que era uma boa “gambiarra”.


RAILS 2.3

http://thereiﬁxedit.ﬁles.wordpress.com/2011/02/white-trash-repairs-traveling-for-kludgers.jpg


RAILS 2.3
module Rails
class Plugin

# Engines are plugins with an app/ directory.
def engine?
has_app_directory?
end

private

def has_app_directory?
File.directory?(File.join(directory, 'app'))
end

end
end

https://github.com/rails/rails/blob/2-3-stable/railties/lib/rails/plugin.rb


RAILS 2.3

Diretórios como app/[models|controllers|helpers]
e as rotas eram automaticamente carregados.


RAILS 2.3

Diretórios como app/[models|controllers|helpers]
e as rotas eram automaticamente carregados.

Mas eram ﬁxos, não existia a possibilidade de
nenhuma conﬁguração de paths.


RAILS 2.3
module Rails
class Plugin

def view_path
File.join(directory, 'app', 'views')
end

def controller_path
File.join(directory, 'app', 'controllers')
end

def routing_file
File.join(directory, 'config', 'routes.rb')
end

private

def app_paths
[ File.join(directory, 'app', 'models'),
File.join(directory, 'app', 'helpers'), controller_path, metal_path ]
end

end
end

https://github.com/rails/rails/blob/2-3-stable/railties/lib/rails/plugin.rb


RAILS 2.3

Tínhamos ORMs diferentes “integradas” ao Rails,
como o Datamapper e o MongoMapper...


RAILS 2.3

Tínhamos ORMs diferentes “integradas” ao Rails,
como o Datamapper e o MongoMapper...

Que poderiam quebrar a cada novo patch release
do Rails.


RAILS 2.3

Não existia uma API pública deﬁnida para outros
frameworks se integrarem.


RAILS 2.3

Não existia uma API pública deﬁnida para outros
frameworks se integrarem.

A solução: alias method chain / monkey patch.


RAILS 2.3

http://thereiﬁxedit.ﬁles.wordpress.com/2011/02/white-trash-repairs-you-spoiled-your-sweet-ride.jpg


RAILS 2.3

O Rails sabia da existência do ActiveRecord...


RAILS 2.3

O Rails sabia da existência do ActiveRecord...

Pois era ele o responsável por inicializar o
ActiveRecord e os demais frameworks.


RAILS 2.3

Isso quer dizer que, por mais que você estivesse
utilizando o DataMapper ou MongoMapper, por
exemplo, o ActiveRecord sempre estaria lá.


RAILS 2.3
module Rails
class Initializer
# Requires all frameworks specified by the Configuration#frameworks
# list. By default, all frameworks (Active Record, Active Support,
# Action Pack, Action Mailer, and Active Resource) are loaded.
def require_frameworks
configuration.frameworks.each { |framework| require(framework.to_s) }
end

def load_observers
if gems_dependencies_loaded && configuration.frameworks.include?(:active_record)
ActiveRecord::Base.instantiate_observers
end
end

def initialize_database
if configuration.frameworks.include?(:active_record)
ActiveRecord::Base.configurations = configuration.database_configuration
ActiveRecord::Base.establish_connection
end
end
end
end


RAILS 2.3

module Rails
class Configuration

private

def default_frameworks
[ :active_record, :action_controller, :action_view, :action_mailer, :active_resource ]
end

end
end


RAILS 2.3

SINGLE
RESPONSIBILITY
PRINCIPLE


RAILS 2.3


NOW

RAILS 3


RAILS 3

Modularidade.

API pública e bem deﬁnida.


RAILS 3

HOOKS!

http://www.ﬂickr.com/photos/ooh_food/3304708302/


RAILS 3

O Rails não conhece o ActiveRecord.


RAILS 3

O Rails não conhece o ActiveRecord.

O ActiveRecord é quem conta para o Rails como
ele deve ser inicializado.


RAILS 3

E isso acontece com todos os outros frameworks.


RAILS 3

ActiveRecord ActionView

E isso acontece com todos os outros frameworks.

ActiveResource
ActionController
ActionMailer


RAILS 3

E isso acontece com todas as demais gems/plugins
que se integram com o Rails.


RAILS 3

DataMapper Mongoid

E isso acontece com todas as demais gems/plugins
que se integram com o Rails.
outros...
RSpec
Devise


EXEMPLO REAL???


module ActiveRecord
class Railtie < Rails::Railtie
config.active_record = ActiveSupport::OrderedOptions.new

config.generators.orm :active_record, :migration => true,
:timestamps => true

config.app_middleware.insert_after "::ActionDispatch::Callbacks",
"ActiveRecord::QueryCache"

rake_tasks do
load "active_record/railties/databases.rake"
end

console do
ActiveRecord::Base
end

initializer "active_record.logger" do

?
ActiveSupport.on_load(:active_record) { self.logger ||= ::Rails.logger }
end

config.after_initialize do
ActiveSupport.on_load(:active_record) do
instantiate_observers
# ....
end
end
end
end
https://github.com/rails/rails/tree/3-0-stable/activerecord


RAILS 3

SINGLE
RESPONSIBILITY
PRINCIPLE


RAILS 3

WIN!!!
http://www.ﬂickr.com/photos/simoncopping/5050597808/


Railties

?


Railties

?
WTF???

Railties
?


Railties Engine

?


Application Railties Engine

?


Initialization


?


Initialization


?
Generators


Initialization

? HOOKS

Generators


CONFIGURAÇÃO
?


CONFIGURAÇÃO

module Responders
class Railtie < ::Rails::Railtie

config.responders = ActiveSupport::OrderedOptions.new

# Na configuração da app (application.rb):

? # config.responders.flash_keys = [:notice, :failure]
end
end

https://github.com/plataformatec/responders


GENERATORS
?


GENERATORS

module MyGem

generators do
require "my_gem/generator"
end

? end
end


GENERATORS

Preciso realmente adicionar na Railtie?

?


GENERATORS

Preciso realmente adicionar na Railtie?

? Não, se você seguir a convenção.


GENERATORS
simple_form
lib
generators
simple_form
install_generator.rb
templates

? simple_form.rb

rails generate simple_form:install

https://github.com/plataformatec/simple_form


GENERATORS
simple_form
lib Namespace
generators
simple_form
install_generator.rb
Generator templates

? simple_form.rb


https://github.com/plataformatec/simple_form


GENERATORS
module SimpleForm
module Generators
class InstallGenerator < Rails::Generators::Base
desc "Copy SimpleForm default files"
source_root File.expand_path('../templates', __FILE__)

def copy_initializers
copy_file 'simple_form.rb',
'config/initializers/simple_form.rb'

? end
end
end
end

http://guides.rubyonrails.org/generators.html


GENERATORS

Siga as convenções.

?
http://www.ﬂickr.com/photos/jasonteale/1340004498/


GENERATORS

Siga as convenções.

? E você será mais feliz =).

http://www.ﬂickr.com/photos/jasonteale/1340004498/


GENERATORS - HOOKS
?


GENERATORS - ORM

module Rails
module Mongoid

config.generators.orm :mongoid, :migration => false

? end
end
end

https://github.com/mongoid/mongoid


GENERATORS - TEST FRAMEWORK

module Rails
module RSpec

config.generators.test_framework :rspec

? end
end
end

https://github.com/rspec/rspec-rails


GENERATORS - TEMPLATE ENGINE

module Rails
module Haml

config.generators.template_engine :haml

? end
end
end

https://github.com/nex3/haml


GENERATORS - MAIS OPÇÕES?

:helper => true,
:orm => nil,
:integration_tool => nil,
:performance_tool => nil,
:resource_controller => :controller,
:scaffold_controller => :scaffold_controller,

? :stylesheets
:test_framework
:template_engine
=>
=>
=>
true,
nil,
:erb

https://github.com/rails/rails/blob/3-0-stable/railties/lib/rails/generators.rb


RAKE TASKS
?


RAKE TASKS
module Rails
module RSpec

rake_tasks do
load "rspec/rails/tasks/rspec.rake"
end

? end
end
end


CONSOLE
?


CONSOLE
module ActiveRecord

# Forçar o carregamento do
# ActiveRecord com o console.
console do
ActiveRecord::Base

? end
end

end


INITIALIZATION HOOKS

?
http://www.ﬂickr.com/photos/mattbrett/224471090/



module MyGem

config.before_configuration {
# Roda após criar a classe da Aplicação, mas

?
# antes de rodar as configurações do usuário.
}

end
end



module MyGem

config.before_initialize {
# Roda depois da configuração do usuário, mas

?
# antes dos initializers.
}

end
end



module MyGem

config.to_prepare {
# Roda antes de cada request em development, e

?
# antes da primeira request em production.
}

end
end


module MyGem

config.before_eager_load {
# Roda antes do Rails carregar todo o código
# da aplicação. Isso só acontece com a opção

? }
# :cache_classes habilitada (production).

end
end


module MyGem

config.after_initialize {
# Roda após a inicialização do Rails,
# configurações do usuário e initializers, e o

?
# próprio bloco to_prepare. É executado apenas
# uma única vez, antes da primeira requisição.
}

end
end


Development Production (cache_classes)

before_conﬁguration before_conﬁguration
=> Booting WEBrick => Booting WEBrick
before_initialize before_initialize
to_prepare to_prepare

?
after_initialize before_eager_load
[...] INFO WEBrick 1.3.1 after_initialize
[...] INFO WEBrick 1.3.1
to_prepare
Request... Request...
to_prepare Request...
Request...
to_prepare


INITIALIZERS
?


INITIALIZERS
module CarrierWave

# Initializers “customizados”
initializer "carrierwave.setup_paths" do
CarrierWave.root =

? end
Rails.root.join(Rails.public_path).to_s

end
end

https://github.com/jnicklas/carrierwave


INITIALIZERS
module MyGem

# Temos acesso ao objeto app para
# obter as configs do usuário.
initializer "my_gem.setup" do |app|

? # app.config
end

end
end


FRAMEWORK LOADING
?


FRAMEWORK LOADING

# Cada módulo avisa através do ActiveSupport
# quando é carregado.

? ActiveSupport.run_load_hooks(
:active_record, ActiveRecord::Base)


FRAMEWORK LOADING
# E podemos executar código neste exato
# momento, dentro do contexto do que está
# sendo carregado.

ActiveSupport.on_load(:active_record) do
include MyGem::ActiveRecordExtensions
end

? ActiveSupport.on_load(:action_controller) do
include MyGem::ActionControllerExtensions
end


E O QUE EU FAÇO COM
ESSE NEGÓCIO DE
FRAMEWORK LOADING?


FRAMEWORK LOADING +
INITIALIZERS
module Devise
class Engine < ::Rails::Engine

initializer "devise.url_helpers" do
ActiveSupport.on_load(:action_controller) do
include Devise::Controllers::Helpers

?
include Devise::Controllers::UrlHelpers
end
end

end
end
https://github.com/plataformatec/devise


FRAMEWORK LOADING

E você pode criar o seu hook.

? ActiveSupport.run_load_hooks(:my_gem, MyGem)

ActiveSupport.on_load(:my_gem) do end


COMO EU CRIO UMA
RAILS::RAILTIE???
?


RAILS::RAILTIE => COMO?

module MyGem

# Acabamos de criar nossa railtie.

? end
end


E QUANDO EU REALMENTE
PRECISO DE UMA RAILS::RAILTIE???
?


RAILS::RAILTIE => QUANDO?

• Precisar carregar generators em outro diretório;
• Precisar de rake tasks disponíveis na aplicação;
• Precisar executar código ao carregar o console;
• Precisar rodar código no momento de inicialização de seu
? plugin/gem, como um initializer do Rails;
• Precisar extender as funcionalidades de algum dos frameworks;


module Responders
config.responders = ActiveSupport::OrderedOptions.new
config.generators.scaffold_controller = :responders_controller

# Add load paths straight to I18n, so engines and application can overwrite it
require 'active_support/i18n'
I18n.load_path << File.expand_path('../responders/locales/en.yml', __FILE__)

initializer "responders.flash_responder" do |app|
if app.config.responders.flash_keys

?
Responders::FlashResponder.flash_keys = app.config.responders.flash_keys
end
end
end
end

https://github.com/plataformatec/responders


Rails::Engine
?
Rails::Railtie + Paths + Autoload


RAILS::ENGINE

app/controllers
app/helpers
app/mailers
app/models
app/views
config/initializers/*.rb
config/routes.rb

? config/locales/*.{rb,yml}
lib
lib/tasks/*.rake


RAILS::ENGINE
Carrega automaticamente controllers,
helpers, models, mailers e views dentro do
diretório app/.

? O arquivo de rotas, initializers e locales são
detectados e carregados quando em conﬁg/,
seguindo a mesma estrutura da aplicação.


RAILS::ENGINE

O diretório lib é adicionado ao
autoload_path do Rails.

? Os arquivos lib/tasks/*.rake são
automaticamente carregados, basta
seguir esta convenção.


RAILS::ENGINE

O que não é carregado
automaticamente pela Engine:
migrations e assets na pasta public
? (javascripts, stylesheets, etc).


RAILS::ENGINE

module MyGem

# Você pode alterar os load_paths padrão.
paths.app.controllers << "lib/controllers"

? end
end


COMO EU CRIO UMA
RAILS::ENGINE???
?


RAILS::ENGINE => COMO?

module MyGem

# Acabamos de criar nossa engine.

? end
end


E QUANDO EU PRECISO DE UMA
RAILS::ENGINE???
?


RAILS::ENGINE => QUANDO?

• Suas extensões precisarem de: rotas, controllers, views ou
mailers, por exemplo.

?


module Devise
config.devise = Devise

# Initialize Warden and copy its configurations.
config.app_middleware.use Warden::Manager do |config|
Devise.warden_config = config
end

# Force routes to be loaded if we are doing any eager load.
config.before_eager_load { |app| app.reload_routes! }

initializer "devise.url_helpers" do
Devise.include_helpers(Devise::Controllers)
end

initializer "devise.omniauth" do |app|
Devise.omniauth_configs.each do |provider, config|

?
app.middleware.use config.strategy_class, *config.args do |strategy|
config.strategy = strategy
end
end

if Devise.omniauth_configs.any?
Devise.include_helpers(Devise::OmniAuth)
end
end
end
end
https://github.com/plataformatec/devise


Rails::Plugin
?
Rails::Engine + interno ao Rails


RAILS::PLUGIN

Engine com alguns conhecimentos
extras para carregar os plugins.

?


RAILS::PLUGIN

Engine com alguns conhecimentos
extras para carregar os plugins.

? E você ganha de brinde a habilidade
do Rails de carregar o arquivo
“init.rb” no diretório root do plugin.


RAILS::PLUGIN

Cada plugin em vendor/plugins é carregado
pelo Rails como um Rails::Plugin.

?


RAILS::PLUGIN

Cada plugin em vendor/plugins é carregado
pelo Rails como um Rails::Plugin.

? Isto quer dizer que não é possível colocar
uma Engine dentro de vendor/plugins, porque
os arquivos seriam carregados duas vezes.


COMO EU CRIO UM
RAILS::PLUGIN???
?


RAILS::PLUGIN => COMO?

rails plugin install
rails server
?


E QUANDO EU PRECISO DE UM
RAILS::PLUGIN???
?


RAILS::PLUGIN => QUANDO?

Nunca. Lembre-se: é interno ao Rails.

?


Rails::Application
?
Rails::Engine + App Bootstrap


RAILS::APPLICATION

Engine com super powers e a
responsabilidade de coordenar o
processo de inicialização da app.

?


RAILS::APPLICATION

Engine com super powers e a
responsabilidade de coordenar o
processo de inicialização da app.

? Inicializa railties, engines e plugins.


RAILS::APPLICATION
Possui as conﬁgurações relativas a
aplicação, como o “cache_classes”.

?


RAILS::APPLICATION
Possui as conﬁgurações relativas a
aplicação, como o “cache_classes”.

Carrega e recarrega as rotas quando
? necessário, e constrói a estrutura de
middlewares da aplicação.


RAILS::APPLICATION

Highlander!

?


RAILS::APPLICATION

Highlander!

?
raise "You cannot have more than one Rails::Application" if Rails.application

https://github.com/rails/rails/blob/3-0-stable/railties/lib/rails/application.rb


COMO EU CRIO UMA
RAILS::APPLICATION???
?


RAILS::APPLICATION => COMO?

rails new my_app
cd my_app
rails server
?


RESUMO


SIMPLE_FORM

Não é uma Rails::Application.


SIMPLE_FORM

Não é um Rails::Plugin.


SIMPLE_FORM

(a não ser que seja instalado como tal)


SIMPLE_FORM


Não é uma Rails::Engine.


SIMPLE_FORM


Não é uma Rails::Railtie.


SIMPLE_FORM

Nenhum hook é necessário,
podemos apenas utilizar a
estratégia de framework loading
sem precisar de uma Rails::Railtie.


RESPONDERS



RESPONDERS


É uma Rails::Railtie.


RESPONDERS

Permite conﬁguração através do objeto :conﬁg;
Utiliza alguns hooks de inicialização;
Sobrescreve o :scaffold_generator para utilizar o
seu próprio.


DEVISE



DEVISE

(e NÃO DEVE ser instalado como tal)


DEVISE

(e NÃO DEVE ser instalado como tal)

É uma Rails::Engine e por
consequência uma Rails::Railtie.


DEVISE

Permite conﬁguração através do objeto :conﬁg;
Utiliza alguns hooks de inicialização;
Adiciona middlewares;
Possui funções similares a uma aplicação, com
controllers, helpers, mailers, views e rotas, mas não
é capaz de rodar isoladamente.


CRIANDO UMA GEM


BUNDLER


BUNDLER

bundle gem ruby_masters


BUNDLE GEM

Cria a estrutura de diretórios basica da gem.

Cria um arquivo Rakeﬁle carregando tarefas do
próprio Bundler.

Inicializa um repositório git.


BUNDLE GEM

~/Projects [ree-1.8.7@rubymasters] $ bundle gem ruby_masters
create ruby_masters/Gemfile
create ruby_masters/Rakefile
create ruby_masters/.gitignore
create ruby_masters/ruby_masters.gemspec
create ruby_masters/lib/ruby_masters.rb
create ruby_masters/lib/ruby_masters/version.rb
Initializating git repo in ~/Projects/ruby_masters


BUNDLE GEM

Gemﬁle

source "http://rubygems.org"

# Specify your gem's dependencies in
ruby_masters.gemspec
gemspec


BUNDLE GEM

Rakeﬁle

require 'bundler'
Bundler::GemHelper.install_tasks


BUNDLE GEM

ruby_masters.gemspec
# -*- encoding: utf-8 -*-
$:.push File.expand_path("../lib", __FILE__)
require "ruby_masters/version"

Gem::Specification.new do |s|
s.name = "ruby_masters"
s.version = RubyMasters::VERSION
s.platform = Gem::Platform::RUBY
s.authors = ["TODO: Write your name"]
s.email = ["TODO: Write your email address"]
s.homepage = ""
s.summary = %q{TODO: Write a gem summary}
s.description = %q{TODO: Write a gem description}

s.rubyforge_project = "ruby_masters"
# ... continua
end


BUNDLE GEM

lib/ruby_masters.rb

module RubyMasters
# Your code goes here...
end


BUNDLE GEM

lib/ruby_masters/version.rb

module RubyMasters
VERSION = "0.0.1"
end


BUNDLE GEM

rake tasks

~/Projects/ruby_masters [ree-1.8.7@rubymasters] $ rake -T
rake build # Build ruby_masters-0.0.1.gem into the pkg directory
rake install # Build and install ruby_masters-0.0.1.gem into system gems
rake release # Create tag v0.0.1 and build and push ruby_masters-0.0.1.gem to Rubygems


RAILTIE?


BUNDLE GEM + RAILTIE

lib/ruby_masters.rb
module RubyMasters

# config.ruby_masters = ActiveSupport::OrderedOptions.new
# rake_tasks {}
# generators {}
# console {}
# config.to_prepare {}
# initializer {}

end
end



Ou



lib/ruby_masters.rb lib/ruby_masters/railtie.rb
module RubyMasters

# config.ruby_masters =
require "ruby_masters/railtie" ActiveSupport::OrderedOptions.new
# rake_tasks {}
module RubyMasters # generators {}
# Your code goes here... # console {}
end # config.to_prepare {}
# initializer {}

end
end


BUNDLER <3


RAILS 3


@cantoniodasilva
?! blog.plataformatec.com.br

Obrigado
!

Como criar plugins para Rails

Recommended

Recommended

More Related Content

Similar to Como criar plugins para Rails

Similar to Como criar plugins para Rails (20)

More from Plataformatec

More from Plataformatec (15)

Como criar plugins para Rails

Editor's Notes