使い方

Contents

セットアップ
edgar:scaffold
カスタマイズ
テスト

Recent Updates
使い方	2012/12/23
Edgarモデル規約	2012/09/28
サポート・コンサルティング	2012/09/19
特徴	2012/09/19
index	2012/09/19

English

Edgar の使い方を順を追って説明します。

[+] [-] 1. セットアップ

'my_app' という名前のアプリケーションを Rails で作成すると仮定して説明します。
```
$ cd MY_PROJECT_DIR
$ rails new my_app -d postgresql
$ cd my_app
```
- この初期状態の段階でリポジトリにコミットしておくといいかもしれません:
```
$ git init
$ git add .
$ git commit -v
```
'Edgar' プラグインをセットアップします。まだ gem 化していませんので、下記の方法をとって下さい:
1. my_app ディレクトリ直下に 'edgar' plugin をコピーします:
```
$ git clone git://jjedgar.git.sourceforge.net/gitroot/jjedgar/edgar2
```
2. Gemfile に下記を追加して下さい: (Edgar エンジン内の Gemfile で定義している内容と同様です。再帰的に呼ばれないのはなぜかよく分かっていません):
```
gem 'jquery-ui-rails'
gem 'edgar', path: 'edgar2'
gem 'rails-i18n'
gem 'will_paginate',  '~> 3.0.0'
gem 'remotipart',     '~> 1.0.2'
gem 'bcrypt-ruby',    require: "bcrypt"
gem 'acts_as_tree',   '~> 1.1.0'
group :development do
  gem 'yard'
  gem 'rails-erd'
end
```
  追加後はお決まりの bundle install です:
```
$ bundle install
```
DB セットアップ
1. configを設定します:
```
$ $EDITOR config/database.yml   # config database
```
2. edgar で使用するテーブルのマイグレーションファイルを MyApp にコピーします:
```
$ rake edgar_engine:install:migrations
```
3. DBを作成します:
```
$ rake db:create
$ rake db:migrate
$ rake db:setup
```
Edgar関連モジュールの取り込み
1. app/controllers/application_controller.rb に下記を追加します:
```
include Edgar::ControllerMixinForApp  
include Edgar::AuthenticationMixin
before_filter :require_login
```
2. app/helper/application_helper.rb に下記を追加します:
```
include EdgarHelper
```
3. app/assets/javascripts/application.js に下記を追加します:
```
//= require jquery.ui.dialog
//= require jquery.ui.datepicker
//= require jquery.remotipart
//= require edgar/base
//= require edgar/menu
//= require edgar/operator_selection
```
4. app/assets/stylesheets/application.css に下記を追加します:
```
*= require jquery.ui.dialog
*= require jquery.ui.datepicker
*= require edgar/base
*= require edgar/menu
```
5. セッションストアを有効にします。 config/initializers/session_store.rb のコメントアウトを外します:
```
MyApp::Application.config.session_store :active_record_store
```
  (※ 既に行った 'rake edgar_engine:install:migrations' でセッションテーブルは作成されているので、ここでの migration は必要ありません。)
6. この段階で、最小限ながら正しい設定が行われていれば MyApp が起動するはずです。下記でサーバを起動し:
```
$ rails server
```
  http://localhost:3000 にブラウザからアクセスしてみて下さい。 Rails logo のページが表示されればひとまず ok です。何らかのエラーが表示されたり何も表示されないと言った場合は、どこかの設定が間違っています。ひとまず立ち戻って確認してみて下さい。
cronジョブのセットアップ

Edgar では以下の cronジョブを必要とします:
1. セッション削除
2. csv作業ファイル削除
リポジトリにある lib/edgar/templates/cron をカスタマイズして /etc/cron.d/ にセットすることで対応します。

[+] [-] 2. edgar:scaffold

一例として、製品マスターと注文を管理するアプリを edgar:scaffold を使って開発することとします。ここで、'製品' 対 '注文' は '1対多' の関係にあるとします。

製品ページとモデルを edgar:scaffold で生成します。
1. edgar:scaffold を実行動します:
```
$ rails generate edgar:scaffold Product name:string price:integer
$ rake db:migrate
```
  - Rails の素の scaffold とは異なり, edgar:scaffold は view を生成しません。デフォルトでは EdgarController の view を使用するためです。もちろん、製品ページ固有の view を後から追加することは可能です。
2. view のレイアウトを作成します。
  1. application レイアウトを作成します。 edgar プラグインの dummy アプリのそれをコピーするのが手始めとしては手っ取り早いと思います:
```
$ cp edgar2/test/dummy/app/views/layouts/application.html.erb app/views/layouts/
```
  2. ログインページ用のレイアウトを作成します (Edgar ではログインページ用のレイアウトを必要としているためです)。これも、edgar プラグインの dummy アプリのそれをコピーするのが手始めとしては手っ取り早いと思います:
```
$ cp edgar2/test/dummy/app/views/layouts/login.html.erb app/views/layouts/
```
3. メニュー設定ファイルを作成します。手っ取り早くするには、 dummy アプリのそれをコピーして修正して下さい:
```
$ mkdir config/edgar
$ cp edgar2/test/dummy/config/edgar/menu_config.rb config/edgar/
```
  ファイル中に、下記のように 'products' を追加します:
```
module Edgar::MenuConfig
  def top
    ...
    'products',
    '_separator',
    ...
end
```
  ('authors' と 'books' の行は dummy 用なので削除して下さい)
4. 初期データ(seed data)を DB に取り込みます。下記のどれかを行って下さい:
  - 最低限の初期データは、管理者ユーザ(root)データです。下記で取り込むことができます:
```
$ cp edgar2/db/seeds.rb db/
$ rake db:seed
```
  - サンプル用に、 Edgar プラグインのテスト用フィクスチャをロードするのも１つの手です。下記の手順で行って下さい:
```
$ cd edgar2
$ tar cvf /tmp/x.tar test/fixtures/edgar*
$ cd -                        # 先のディレクトリ(Rails.root)に戻る
$ tar xvf /tmp/x.tar          # edgar2/test/fixtures/edgar* を test/fixtures/edgar* にコピー
$ rake db:fixtures:load       # test/fixtures/ を開発DBにロード
```
5. サーバを再起動し、http://localhost:3000/products にアクセスします。ここで、ログインID/パスワードとして root/root でログインして下さい。
もう１つの例である「注文」画面を作成します。製品選択ポップアップ画面が自動で注文入力フォームで動作する点に着目して下さい。
1. edgar:scaffold を実行動します:
```
$ rails generate edgar:scaffold Order name:string product_id:integer quantity:integer
$ rake db:migrate
```
2. 製品と注文との間に 1:多の関連を定義します:
  - Productモデルに 'has_many :orders' を追加します。
  - Orderモデルに 'belongs_to :product' を追加します。
3. メニュー設定ファイル config/edgar/menu_config.rb に '注文' 項目を追加します:
```
module Edgar::MenuConfig
  def top
   ...
    'products',
    'orders',
    '_separator',
   ...
end
```
4. サーバを再起動し、ブラウザからアクセスして下さい。注文の入力画面から製品選択ポップアップが表示されることを確認してみて下さい。

[+] [-] 3. カスタマイズ

Edgar では以下のカスタマイズをサポートしています。簡単なレベルから複雑なレベルの順に説明します:

[+] [-] 3.1. カラムの追加

Rails の 'migration' 機能を使うことで、任意の数のカラムを追加することができます (ただし DB の制限の範囲内で)。追加したカラムは自動的に一覧表示・フォーム画面・検索画面に表示されます（もちろん、カラムを表示する・しないは、一覧・フォーム・検索フォームそれぞれにおいて制御することもできます）。

例として、Customer モデルの name カラムを first_name, last_name に変更する方法を示します:

migration を生成し、エディタを起動します (viに限りません。好みのエディタをご使用下さい):

$ rails generate migration change_name_of_customers
$ vi db/migrate/YYYYMMDDNNNNNN_change_name_of_customers.rb  # 実際に生成されたファイル名を使用して下さい

以下の様に編集します:

class ChangeNameOfCustomers < ActiveRecord::Migration
  def up
    remove_column :customers, :name
    add_column    :customers, :first_name,  :string
    add_column    :customers, :last_name,   :string
  end

  def down
    add_column    :customers, :name,  :string
    remove_column :customers, :first_name
    remove_column :customers, :last_name
  end
end

migration を実行します:
```
$ rake db:migrate
```
name カラムがなくなったので、以下のような name メソッドを定義します (Edgarモデル規約参照)。また、validation も合わせて変更します:
```
class Customer < ActiveRecord::Base
    :
  validates_presence_of :first_name, :last_name
    :
  def name
    (first_name || '?') + ' ' + (last_name || '?')
  end
end
```
注: 現時点で first_name, last_name には空のデータが入っているため、 nil の場合は '?' を表示するようにしています。必須項目の場合、単純に first_name + ' ' + last_name とできるでしょう。
画面をリロードして Customer 画面を表示してみてください。
Customer を参照する画面、例えばお問合わせ画面で、フォームから顧客ポップアップを開いてみてください。

[+] [-] 3.2. 画面デザインの変更

もし今の Edgar の Webデザインが気に入らないなら(承知しています。^^;)、テンプレートやスタイルシートを変更することで対応可能です。 app/views/ 及び app/assets/stylesheets/ のファイルを変更してください。

[+] [-] 3.3. 表示項目を選ぶ

edgar:scaffold で生成したモデル・ビュー・コントローラは自由にカスタマイズできます。この節では、表示項目を制限したり表示順を指定する方法について説明します。それ以上の動作(計算値を表示する・専用のUIを使う等)を望む場合は次節以降を参照下さい。

edgar:scaffold 実行直後の画面をご覧になると分かると思いますが、一覧・フォーム・検索フォーム・選択ポップアップ(他からbelongs_toで参照されている場合)に、すべてのカラムが表示されています(*)。時としてこれは多すぎることがあります。また、この段階では表示順は DB の仕様で勝手に決められてしまっていますが、これを指定したい場合があります。 Edgar ではこのレベルのカスタマイズを行う簡単な方法を提供します。

(*)正確には、フォームでは id, created_at, updated_at は表示されません。

[+] [-] 3.3.1. モデルの表示項目を定義する

カラム名からなる文字列配列を返す view_columns() クラスメソッドを再定義することで、モデルの表示項目と表示順を指定することができます。例:

class Product < ActiveRecord::Base
    :
  def self.view_columns
    %w(id name)
  end
    :
end

[+] [-] 3.3.2. 画面ごとに表示項目を定義する

EdgarController では、一覧・フォーム・検索フォーム・ポップアップ用一覧の、計4つの "画面部品" を制御しています。これら画面部品ごとに表示項目を指定したい場合、モデルに以下のクラスメソッドを定義します:

一覧: view_list_columns()
フォーム: view_form_columns()
検索フォーム: view_search_form_columns()
ポップアップ: view_popup_columns()

返す値は view_columns() と同様、カラム名文字列の配列です。ユーザモデルの例を示しましょう:

class User < ActiveRecord::Base
    :
  # AR::Base.view_list_columns() を上書きする
  def self.view_list_columns
    %w(id login email created_at updated_at)
  end
    :
end

view_columns() がモデルに対して４つの画面部品共通の表示項目を定義するのに対し、これら４つのメソッドは画面部品ごとの表示項目を定義します。これら計５つのメソッドは、組み合わせて使用することができます。優先順は、画面部品ごとのメソッドが優先されます。従って、以下の順に設計するのがよいでしょう:

モデルのカラムをそのまま４つの画面部品すべてに表示していい場合 → 何も追加しない。
４つの画面部品共通で表示項目を決めたい → view_columns() を再定義。
(例えば)ポップアップ表示項目だけ決めたい → view_popup_columns() を再定義。フォーム、一覧、検索フォームも同様。

カスタマイズ後は、プログラムが問題ないか以下で確認して下さい:

$ rake test

[+] [-] 3.4. 専用の view を作る

画面のレイアウトを変えたい・専用の UI を使いたい・計算結果をリアルタイムに画面に出したい、という場合、上記のカスタマイズでは対応できません。

ここでは、EdgarController (及びその派生クラス --edgar:scaffold で生成したコントローラが当てはまります) の範囲内で view をカスタマイズするケースについて説明します。

edgar:scaffold は view を生成しませんが、それは、デフォルトで EdgarController の view を使用するためです (Rails 3 の素晴らしい機能のおかげです)。EdgarController では下記のテンプレートを使用しています:

edgar/_form.html.erb:	フォーム
edgar/_list.html.erb:	一覧
edgar/_search_form.html.erb:	検索フォーム
edgar/index.html.erb:	全体表示

それぞれ、各コントローラにて上書きすることが可能です。次節にて例を示します。

[+] [-] 3.4.1. 例

例として、製品モデルのフォームをカスタマイズすることにします。 app/views/products/_form.html.erb を作成することで、自動的にこちらのテンプレートが使用されます. 例えば、下記のようにテキストフィールドを明示的に表形式で表示する、ということが可能です:

...
<%= edgar_form do |f| %>
  <%= draw_form_buttons %>
    <table>
      <tr><th>Name</th>   <td><%= f.text_field :name %></td></tr>
      <tr><th>Price</th>  <td><%= f.text_field :price %></td></tr>
    </table>
<% end %>
...

[+] [-] 3.5. アクションを追加する

単に view テンプレートをカスタマイズするだけでは不十分な場合があります。その場合は、コントローラにアクションを追加する必要がある場合があることでしょう。これは通常のコントローラへのアクションの追加と同様です。

[+] [-] 3.6. EdgarController からの継承を止め ActionController::Base から継承する

EdgarController の提供する機能をほとんど使用しない場合、 EdgarController からの継承を止めて ActionController::Base から継承し、通常のコントローラ開発の手順を踏みます。これは最後の手段です。カスタマイズというより、Rails フレームワークにおける追加開発と言えます。

[+] [-] 4. テスト

edgar:scaffold は機能テスト(functional test)と単体テスト(unit test) も生成します。単体テストは素の scaffold と同じものですが、機能テストは EdgarController 用に大きく修正されており、Edgar用テストヘルパとEdgar用フィクスチャにも依存しているため、以下のような準備が必要になります:

以下を Gemfile に追記し、bundle install します:
```
group :test do
  gem 'shoulda-context'
end
```

以下を test/test_helper.rb に追記します:

require 'shoulda-context'
Dir[Rails.root + 'edgar2/test/support/**/*.rb'].each { |f| require f }

同ファイルの ActiveSupport::TestCase にて Edgar::ControllerSupporter を includeします:
```
class ActiveSupport::TestCase
  include Edgar::ControllerSupporter
  ...
```

Edgar関連のフィクスチャを使用する場合、以下のように MyApp にコピーするのが簡単でしょう:

$ cd edgar2
$ tar cvf /tmp/x.tar test/fixtures/edgar*
$ cd -                        # 先のディレクトリ(Rails.root)に戻る
$ tar xvf /tmp/x.tar          # edgar2/test/fixtures/edgar* を test/fixtures/edgar* にコピー

Edgar用フィクスチャについて、1点だけ例外があり、名前空間ありかつ複数が推測できないモデルである Edgar::ViewStatus だけは明示的に読み込まないといけないようです:
```
set_fixture_class edgar_view_status:  'Edgar::ViewStatus'
```

最終的に test/test_helper.rb は以下のようになるでしょう (コメント行は省いています):

ENV["RAILS_ENV"] = "test"
require File.expand_path('../../config/environment', __FILE__)
require 'rails/test_help'
require 'shoulda-context'
Dir[Rails.root + 'edgar2/test/support/**/*.rb'].each { |f| require f }

class ActiveSupport::TestCase
  include Edgar::ControllerSupporter
  fixtures :all
  set_fixture_class edgar_view_status:  'Edgar::ViewStatus'
end

テストの実行:
```
$ rake test
```
- テストは全てパスするはずです。もし失敗するなら、何かがおかしいのでチェックして下さい。
- edgar:scaffold の生成した機能テストのいくつかは pending 状態です。必要な権限をセットした上できちんとテストを通すようにするのはアプリ開発者であるあなたの責任となります。

| Generated by juli 1.17.00