動手寫一個 Rails plugin

因為開發上方便，需要一個能快速切換登入身分的小 widget，正好趁這個機會搞懂怎麼開發一個 Rails plugin。成品在這：https://github.com/kevin-shu/user_switch
以下就是步驟囉：

1. rails plugin new my_gem

首先執行 rails plugin new <plugin_name>，會產生 plugin 資料夾，結構為：

my_plugin
├── Gemfile
├── Gemfile.lock
├── MIT-LICENSE
├── README.rdoc
├── Rakefile
├── lib
│ ├── my_plugin
│ │ └── version.rb
│ ├── my_plugin.rb
│ └── tasks
│ └── my_plugin_tasks.rake
├── my_plugin.gemspec
└── test
│
...(本篇不提到，忽略)

接下來就要介紹這些資料夾、檔案的用途

2. my_plugin.gemspec

這是一個 manifest 檔案，用來告訴 gem 該怎麼打包這個專案。

3. lib 資料夾

my_plugin.rb:

這就是 plugin 的核心，當裝上 plugin 後，被執行的就是這個檔案。你當然可以將所有 code 都寫在裡面，但是這樣很亂。一個功能稍微複雜且完整的 plugin 一定會有系統的做模組化。所以我們往往不在裡面寫很多 code ，而是將一個個寫好的模組 require 近來。

my_plugin 資料夾：

剛剛說的模組化的 code 通常會被分門別類放在這裡。

my_plugin/version.rb:

在初始化後，my_plugin 資料夾一開始只有這個檔案，用來記錄版本號。你如果有看一下 gemspec 的內容的話，會發現這個檔案會被 gemspec require 到。

Engine

如果你的 plugin 需要一些自定的 controller、view、assets，首先要加入這段程式碼：

module ZurbFoundation
  class Engine < Rails::Engine
  end
end

你可以將他獨立成一個檔案由 my_plugin.rb 載入，或是直接寫到 my_plugin.rb 裡。有了這段程式碼，Rails就會自動將 app 及 config 兩個資料夾下的所有檔案載入。

請注意，載入 engine 的 code 必須放在 my_plugin.rb 的最後，才能正常運作

4. app 資料夾

當你希望在安裝這個套件的專案中使用客製的 controller、assets 等檔案，就要在根目錄下建立一個 app 資料夾。結構基本上跟你熟悉的 rails 的 app 資料夾是一樣的。要注意的是，裡面的 controller 或 model 必須在專案的 namespace 下，例如：

# CURRENT FILE :: app/controllers/my_plugin/my_controller.rb
module MyPlugin
  class MyController < ::ApplicationController
    def index
      ...
    end
  end
end

5. config

這個資料夾跟app資料夾一樣需要手動建立，最常見的用途是設定 routing，例如：

# CURRENT FILE :: config/routes.rb
Rails.application.routes.draw do
  get "team" => "team_page/team#index" , :as => :team_page
end

6. generators 資料夾

這個資料夾也是需要時才要自行建立。裡面放了一些設定檔等的 template 以及 install method，讓這個 gem 提供 install 功能，執行後會複製一份設定檔到專案中。這邊不會對 generators 多做介紹。

7. pack & push

當你的 plugin 完成後，就可以用以下指令將他打包起來，gem 會按照 gemspec 的設定做打包。

gem build /project_path/user_switch.gemspec

打包後的 gem 可以 push 到 rubygems.org：

gem push project_name-0.0.1.gem

8. 在 Rails 專案中掛上剛寫好的plugin push

我們有可以在 Gemfile 中依不同來源來做來源的設定，其中當來源是來自 local 或 git 時，是不用打包就可以直接掛上的，開發的時候來源通常是設定在 local。

(1) local:

gem "my_plugin", :path=>"/path/to/your/plugin"

(2) git:

gem "my_plugin", :git=>"https://path/to/your/repo"

(3) rubygem.org:

gem "my_plugin"

Reference:

http://zurb.com/article/814/yetify-your-rails-new-foundation-gem-and-
http://coding.smashingmagazine.com/2011/06/23/a-guide-to-starting-your-own-rails-engine-gem/
http://guides.rubyonrails.org/plugins.html

2013年12月30日星期一