ホーム>プログラミング関連>その他のソースコード
ダウンロード

カミナリ

最新のWebアプリフレームワークとORMのためのスコープ＆エンジンベース、クリーン、パワフル、カスタマイズ可能で洗練されたページネーター

特徴

クリーン

Array 、 Hash 、 Object 、またはAR::Baseグローバルに汚染しません。

使いやすい

宝石を束ねるだけで、モデルを塗る準備ができています。構成は不要です。モデルやヘルパーに何かを定義する必要はありません。

単純なスコープベースのAPI

すべてがメソッドチェーン可能であり、「hasheritis」が少なくなります。あなたが知っている、それは現代のレールの方法です。一般的なAR::Relationインスタンスを使用する代わりに、特別なコレクションクラスやパジネート値のためのものはありません。したがって、もちろん、ページネーターの範囲の前後に他の条件をチェーンできます。

カスタマイズ可能なエンジンベースのi18n対応ヘルパー

ページネーションヘルパー全体が基本的にリンクと非リンクのコレクションにすぎないため、カミナリはエンジン内の独自の部分テンプレートを介してそれぞれをレンダリングします。したがって、部分的なテンプレートをオーバーライドすることで、動作、スタイル、またはあらゆるものを簡単に変更できます。

Orm＆Template Engine Agnostic

Kaminariは、複数のORM（ActivereCord、DataMapper、Mongoid、Mongomapper）、複数のWebフレームワーク（Rails、Sinatra、Grape）、および複数のテンプレートエンジン（ERB、Haml、Slim）をサポートしています。

モダンな

ページネーションヘルパーは、デフォルトでHTML5 <nav>タグを出力します。さらに、ヘルパーは控えめなajaxをサポートします。

サポートされているバージョン

  • Ruby 2.1、2.2、2.3、2.4、2.5、2.6、2.7、3.0、3.1、3.2、3.3

  • Rails 4.1、4.2、5.0、5.1、5.2、6.0、6.1、7.0、7.1、7.2、8.0

  • シナトラ1.4、2.0

  • ハム3+

  • マンゴイド3+

  • Mongomapper 0.9+

  • Datamapper 1.1.0+

インストール

デフォルトのRailsスタックにKaminariをインストールするには、このラインをGemfileに配置するだけです。 

 gem 'kaminari'

次にバンドル： 

% bundle

非レールまたは非アクティブコードアプリを構築し、ページネーション機能を必要とする場合は、他のフレームワーク/ライブラリサポートセクションをご覧ください。

クエリの基本

pageスコープ

ユーザーの7番目のページを取得するには（デフォルトのper_pageは25です） 

 User . page ( 7 )

注：ページはページ1から始まり、ページ0ではなく（ページ（0）はページ（1）と同じ結果が返されます）。

カミナリはクエリにorderを追加しません。驚きを避けるために、通常、塗装されたクエリに注文を含める必要があります。例えば： 

 User . order ( :name ) . page ( 7 )

以下のメソッドを使用して、ページ番号またはページ条件を取得できます。 

 User . count                     #=> 1000
User . page ( 1 ) . limit_value       #=> 20
User . page ( 1 ) . total_pages       #=> 50
User . page ( 1 ) . current_page      #=> 1
User . page ( 1 ) . next_page         #=> 2
User . page ( 2 ) . prev_page         #=> 1
User . page ( 1 ) . first_page?       #=> true
User . page ( 50 ) . last_page?       #=> true
User . page ( 100 ) . out_of_range?   #=> true

スコープper

各ページごとに多くのユーザーを表示するには（値per変更） 

 User . order ( :name ) . page ( 7 ) . per ( 50 )

スコープperモデルで直接定義されるのではなく、ページスコープで定義されているメソッドにすぎないことに注意してください。これは、 page番号を指定せずに実際per使用することはないため、絶対に合理的です。

内部的per limitを利用しているため、以前に設定されたlimitをオーバーライドすることに注意してください。また、すべてのリクエストレコードのサイズを取得したい場合は、 total_countメソッドを使用できます。 

 User . count                     #=> 1000
a = User . limit ( 5 ) ; a . count     #=> 5
a . page ( 1 ) . per ( 20 ) . size         #=> 20
a . page ( 1 ) . per ( 20 ) . total_count  #=> 1000

paddingスコープ

時には、ページサイズの倍数ではない多くのレコードをパッドする必要があります。 

 User . order ( :name ) . page ( 7 ) . per ( 50 ) . padding ( 3 )

paddingスコープもモデルで直接定義されていないことに注意してください。

unscoping

何らかの理由でpage解除する必要がある場合、およびメソッドper電話をかけることができますexcept(:limit, :offset) 

 users = User . order ( :name ) . page ( 7 ) . per ( 50 )
unpaged_users = users . except ( :limit , :offset ) # unpaged_users will not use the kaminari scopes

カミナリの構成

一般的な構成オプション

Kaminari.configureメソッドを使用してこれらの値をオーバーライドすることにより、次のデフォルト値を構成できます。 

 default_per_page      # 25 by default
max_per_page          # nil by default
max_pages             # nil by default
window                # 4 by default
outer_window          # 0 by default
left                  # 0 by default
right                 # 0 by default
page_method_name      # :page by default
param_name            # :page by default
params_on_first_page  # false by default

デフォルトの構成ファイルをConfig/Intializersディレクトリに生成する便利なジェネレーターがあります。次のGeneratorコマンドを実行し、生成されたファイルを編集します。 

% rails g kaminari:config

page_method_name変更します

メソッド名page bonzoやplant 、または好きなものに変更して、既存のpageメソッド、アソシエーション、スコープ、またはモデルのpageメソッドを定義するその他のプラグインをうまく再生できます。

paginates_perによって各モデルのデフォルトのPER_PAGE値を構成します

次の宣言DSLを使用して、各モデルごとにデフォルトのper_page値を指定できます。 

 class User < ActiveRecord :: Base
  paginates_per 50
end

max_paginates_perによって各モデルのmax per_page値の構成

次の宣言DSLを使用して、各モデルごとに最大per_page値を指定できます。スコープperに指定された変数がこの変数を超えている場合、 max_paginates_perが使用されます。デフォルト値はnilです。つまり、最大値per_page値を課していません。 

 class User < ActiveRecord :: Base
  max_paginates_per 100
end

各モデルのMAX_PAGE値の値をmax_pagesで構成します

次の宣言DSLを使用して、各モデルごとにmax_pages値を指定できます。この値は、返すことができるページの総数を制限します。大規模なコレクションに制限を設定するのに役立ちます。 

 class User < ActiveRecord :: Base
  max_pages 100
end

ransack_memoryを使用するときにparams_on_first_pageの構成

ransack_memory gemを使用していて、前のページまたは最初のページに戻る問題の問題を経験している場合は、 params_on_first_page設定をtrueに設定します。

コントローラー

ページパラメーターはparams[:page]

通常、コントローラーコードは次のようになります。 

 @users = User . order ( :name ) . page params [ :page ]

ビュー

同じ古いヘルパーメソッド

paginateヘルパーに電話するだけです： 

 <%= paginate @users %>

これにより、HTML5 <nav>タグに囲まれたいくつかの?page=Nページネーションリンクが表示されます。

ヘルパー

paginate Helperメソッド

 <%= paginate @users %>

これにより« First ‹ Prev ... 2 3 4 5 6 7 8 9 10 ... Next › Last »などのいくつかのページネーションリンクが出力されます。

「内側のウィンドウ」サイズを指定する（デフォルトで4） 

 <%= paginate @users, window: 2 %>

これにより、 ... 5 6 7 8 9 ... 7が現在のページのようなものが出力されます。

「外側のウィンドウ」サイズを指定する（デフォルトで0） 

 <%= paginate @users, outer_window: 3 %>

これにより、 1 2 3 ...(snip)... 18 19 20合計20ページを持っています。

外側の窓は、左、右（デフォルトで0）で個別に指定できます

 <%= paginate @users, left: 1, right: 3 %>

これにより、 1 ...(snip)... 18 19 20合計20ページを持っています。

リンクのパラメーター名（ :param_name ）の変更

 <%= paginate @users, param_name: :pagina %>

これにより、各リンクのクエリパラメーター名が変更されます。

リンクの追加パラメーター（ :params ） 

 <%= paginate @users, params: {controller: 'foo', action: 'bar', format: :turbo_stream} %>

これにより、各リンクのurl_optionが変更されます。 :controllerと:action共通のキーである可能性があります。

Ajaxリンク（Rails-UJを介して、Rails <7.2で動作します） 

 <%= paginate @users, remote: true %>

これにより、内部のすべてのリンクにdata-remote="true"が追加されます。

代替ビューディレクトリの指定（デフォルトはkaminari/） 

 <%= paginate @users, views_prefix: 'templates' %>

これにより、 app/views/templates/kaminariでPartialsが検索されます。このオプションにより、A/Bテストページネーションテンプレート/テーマなどを簡単に行うことができます。これは、新しい/古いテンプレートを同時に使用し、セルなどの他のGEMとのより良い統合を使用します。

link_to_next_pageおよびlink_to_previous_page （ link_to_prev_pageにエイリアス）ヘルパーメソッド

 <%= link_to_next_page @items, 'Next Page' %>

これにより、次のページへのリンクが表示されます。これは、Twitterのようなページネーション機能を作成するのに役立ちます。

ヘルパーメソッドは、リンクをさらに指定するためのparamsオプションをサポートしています。 format設定する必要がある場合は、 params Hashに含めてください。 

 <%= link_to_next_page @items, 'Next Page', params: {controller: 'foo', action: 'bar', format: :turbo_stream} %>

page_entries_infoヘルパーメソッド

 <%= page_entries_info @posts %>

これにより、表示されている数と総エントリの数を含む有用なメッセージが表示されます。

デフォルトでは、このメッセージは、コレクション内のオブジェクトの人間化されたクラス名を使用します。たとえば、ProjectTypeモデルの「プロジェクトタイプ」です。名前空間が切り取られ、姓のみが使用されます。これを以下でオーバーライドします:entry_nameパラメーター： 

 <%= page_entries_info @posts, entry_name: 'item' %> 
#= > Displaying items 6 - 10 of 26 in total

rel_next_prev_link_tagsヘルパーメソッド

 <%= rel_next_prev_link_tags @users %>

これにより、ヘッドのREL次のリンクタグが表示されます。

path_to_next_pageヘルパーメソッド

 <%= path_to_next_page @users %>

これにより、サーバーの相対パスが次のページに戻ります。

path_to_prev_pageヘルパーメソッド

 <%= path_to_prev_page @users %>

これにより、サーバーの相対パスが前のページに戻ります。

I18Nおよびラベル

「ファースト」、「最後」、「前」、「...」のデフォルトラベルは、エンジン内のi18n yamlに保存され、i18n APIを介してレンダリングされます。国際化されたアプリケーションのために、i18n.localeごとにラベル値を切り替えることができます。キーとデフォルト値は次のとおりです。 Rails.root/config/localesディレクトリのyamlファイルに追加することで、それらをオーバーライドできます。 

 en :
  views :
    pagination :
      first : " &laquo; First "
      last : " Last &raquo; "
      previous : " &lsaquo; Prev "
      next : " Next &rsaquo; "
      truncate : " &hellip; "
  helpers :
    page_entries_info :
      one_page :
        display_entries :
          zero : " No %{entry_name} found "
          one : " Displaying <b>1</b> %{entry_name} "
          other : " Displaying <b>all %{count}</b> %{entry_name} "
      more_pages :
        display_entries : " Displaying %{entry_name} <b>%{first}–%{last}</b> of <b>%{total}</b> in total "

英語以外のローカリゼーションを使用する場合は、 one_page:display_entriesブロックを変更するためのi18nルールを参照してください。

ページネーションヘルパーのカスタマイズ

カミナリには、便利なテンプレートジェネレーターが含まれています。

あなたのパジネーターを編集します

最初にジェネレーターを実行し、 

% rails g kaminari:views default

次に、アプリのapp/views/kaminari/ディレクトリの部分を編集します。

Haml/Slimユーザー用

HTML2Haml GEMまたはHTML2SLIM GEMを使用して、ERBテンプレートを変換できます。 app/views/kaminari/にそれらを配置すると、Kaminari宝石はHaml/Slimテンプレートを自動的にピックアップします。

複数のテンプレート

Paginator（パブリックや管理者など）に異なるテンプレートが必要な場合は、このような--views-prefix directory渡すことができます。 

% rails g kaminari:views default --views-prefix admin

これにより、 app/views/admin/kaminari/ Directoryで部分的に生成されます。

テーマ

ジェネレーターには、外部リポジトリ（https://github.com/amatsuda/kaminari_themes）からいくつかのサンプルテンプレートテーマを取得する機能があり、バンドルされた「デフォルト」のテンプルに加えて、見栄えの良いパジネーターを作成するのに役立ちます。 

% rails g kaminari:views THEME

利用可能なテーマの完全なリストを表示するには、テーマリポジトリをご覧になるか、 THEME引数を指定せずにジェネレーターを押してください。 

% rails g kaminari:views

複数のテーマ

単一のアプリケーション内から複数のテーマを利用するには、アプリ/views/kaminari/内にディレクトリを作成し、カスタムテンプレートファイルをそのディレクトリに移動します。 

% rails g kaminari:views default (skip if you have existing kaminari views)
% cd app/views/kaminari
% mkdir my_custom_theme
% cp _ * .html. * my_custom_theme/

次に、 paginateメソッドを呼び出すときのディレクトリを参照してください。 

 <%= paginate @users, theme: 'my_custom_theme' %>

カスタマイズしてください！

注：テーマが存在しないか、何も指定されていない場合、カミナリは宝石に含まれるビューにデフォルトに戻ります。

Select Countクエリを発行せずにページングします

一般的に、ページネーターはリンクを表示するためにレコードの総数を知る必要がありますが、レコードの総数は必要なく、「前のページ」と「次のページ」リンクだけが必要な場合があります。このようなユースケースの場合、Kaminariは、すべてのレコードの数をカウントせずにページナタのコレクションを作成するwithout_countモードを提供します。これは、大きなテーブルをカウントするとRDBMSが遅くなる傾向があるため、非常に大きなデータセットを扱っている場合に役立ちます。

Paginatedオブジェクトに.without_countを追加するだけです。 

 User . page ( 3 ) . without_count

ビューファイルでは、フル機能のpaginateヘルパーの代わりに、次のような単純なヘルパーのみを使用できます。 

 <%= link_to_prev_page @users, 'Previous Page' %>
<%= link_to_next_page @users, 'Next Page' %>

一般的な配列オブジェクトのページング

Kaminariは、一般的なアレイオブジェクトをpaginate Viewヘルパーに適応させるアレイラッパークラスを提供します。ただし、 paginateヘルパーはアレイオブジェクトを自動的に処理しません（これは意図的で設計によるものです）。 Kaminari::paginate_arrayメソッドは、配列オブジェクトをpageメソッドを受け入れるページの配列に変換します。 

 @paginatable_array = Kaminari . paginate_array ( my_array_object ) . page ( params [ :page ] ) . per ( 10 )

Options Hashを使用してtotal_count値を指定できます。これは、RSOLR検索結果など、実際のcountとは異なるcount値を持つ配列オブジェクトを処理する場合、またはカスタムページネーションを生成する必要がある場合に役立ちます。例えば： 

 @paginatable_array = Kaminari . paginate_array ( [ ] , total_count : 145 ) . page ( params [ :page ] ) . per ( 10 )

または、外部APIを使用してデータのページを調達する場合は、 

 page_size = 10
one_page = get_page_of_data params [ :page ] , page_size
@paginatable_array = Kaminari . paginate_array ( one_page . data , total_count : one_page . total_count ) . page ( params [ :page ] ) . per ( page_size )

フレンドリーなURLとキャッシュを作成します

pageパラメーターとRailsルーティングのため、SEOとユーザーフレンドリーなURLを簡単に生成できます。ポジネートしたいリソースについては、次のことをroutes.rbに追加するだけです。 

 resources :my_resources do
  get 'page/:page' , action : :index , on : :collection
end

レール4以降を使用している場合は、 concern使用してルートの定義を簡素化できます。 

 concern :paginatable do
  get '(page/:page)' , action : :index , on : :collection , as : ''
end

resources :my_resources , concerns : :paginatable

これにより、 /my_resourcesの代わりに/my_resources/page/33のようなURLが作成されます/my_resources?page=33 。これは今ではフレンドリーなURLですが、他の追加の利点もあります...

pageパラメーターはURLセグメントになるため、Railsページキャッシングを活用できます！

注：この例では、ルートを自分のルートを指し示しました:indexアクション。コントローラーでカスタムページネーションアクションを定義している可能性があります - 代わりにaction: :your_custom_action 。

その他のフレームワーク/ライブラリサポート

カミナリジェム

技術的には、カミナリの宝石は3つの個別のコンポーネントで構成されています。 

 kaminari-core: the core pagination logic
kaminari-activerecord: Active Record adapter
kaminari-actionview: Action View adapter

したがって、 gem 'kaminari'のバンドルは、次の2行に相当します（カミナリコアはアダプターから参照されます）： 

 gem 'kaminari-activerecord'
gem 'kaminari-actionview'

他のORMユーザー向け

MongoidなどのActivereCordの代わりに他のサポートされているORMを使用したい場合は、Kaminari-Activerecordの代わりにアダプターをバンドルします。 

 gem 'kaminari-mongoid'
gem 'kaminari-actionview'

カミナリは現在、次の骨のアダプターを提供しています。

  • アクティブレコード：https：//github.com/kaminari/kaminari/tree/master/kaminari-ctiverecord（このレポに含まれる）
  • Mongoid：https：//github.com/kaminari/kaminari-mongoid
  • mongomapper：https：//github.com/kaminari/kaminari-mongo_mapper
  • データマッパー：https：//github.com/kaminari/kaminari-data_mapper（Kaminari 1.0.xでは動作しません）

他のWebフレームワークユーザー向け

Rails + Action View、たとえばSinatraの代わりに他のWebフレームワークを使用する場合は、Kaminari-actionViewの代わりにアダプターをバンドルします。 

 gem 'kaminari-activerecord'
gem 'kaminari-sinatra'

カミナリは現在、次のWebフレームワークにアダプターを提供しています。

  • アクションビュー：https：//github.com/kaminari/kaminari/tree/master/kaminari-アクションビュー（このレポに含まれる）
  • シナトラ：https：//github.com/kaminari/kaminari-sinatra
  • グレープ：https：//github.com/kaminari/kaminari-grape

詳細については

より高度なヒントとテクニックについては、Github WikiのKaminariレシピをご覧ください。 https://github.com/kaminari/kaminari/wiki/kaminari-recipes

質問、フィードバック

Github（Amatsuda）またはTwitter（@a_matsuda）で私にメッセージを送ってください：:)

カミナリへの貢献

フォーク、修正、プルリクエストを送信します。

サポートされているすべてのフレームワークに対してテストスイートをローカルに実行するには： 

% bundle install
% rake test:all

1つのフレームワークに対してテストスイートをターゲットにするには： 

% rake test:active_record_50

rake -Tを実行することで、サポートされているテストタスクのリストを見つけることができます。また、特定のフレームワークの特定のテストを実行すると便利な場合があります。そのためには、最初にその構成のためにすべてをバンドルしたことを確認する必要があります。次に、特定のテストを実行できます。 

% BUNDLE_GEMFILE= ' gemfiles/active_record_50.gemfile ' bundle install
% BUNDLE_GEMFILE= ' gemfiles/active_record_50.gemfile ' TEST=kaminari-core/test/requests/navigation_test.rb bundle exec rake test

著作権

Copyright（c）2011- Akira Matsuda。詳細については、MIT-Licenseを参照してください。

拡大する
追加情報
関連アプリ
おすすめ
関連情報 すべて