kaminari
v1.2.2
Ein umfangreicher und engbasierter, sauberer, leistungsstarker, anpassbarer und ausgefeilter Paginator für moderne Web -App -Frameworks und Orms
Verschmutzt nicht global Array , Hash , Object oder AR::Base .
Bündeln Sie einfach das Edelstein, dann sind Ihre Modelle bereit, paginiert zu werden. Keine Konfiguration erforderlich. Sie müssen nichts in Ihren Modellen oder Helfern definieren.
Alles ist mit weniger "Hasheritis" methodellbar. Sie wissen, das ist die moderne Rails -Art. Keine spezielle Sammlungsklasse oder irgendetwas für die paginierten Werte, statt eine allgemeine AR::Relation Relationsinstance. Natürlich können Sie noch andere Bedingungen vor oder nach dem Paginatorbereich ketten.
Da der gesamte Helfer im Grunde genommen nur eine Sammlung von Links und Nicht-Links ist, macht Kaminari jeden von ihnen durch seine eigene teilweise Vorlage im Motor. So können Sie ihr Verhalten, Stil oder was auch immer durch überschreibende Teilvorlagen modifizieren.
Kaminari unterstützt mehrere Ormen (Activerecord, Datamapper, Mongoid, Mongomapper), mehrere Webrahmen (Rails, Sinatra, Grape) und mehrere Vorlagenmotoren (ERB, Haml, Slim).
Das Pagination -Helfer gibt standardmäßig das HTML5 <nav> -Tag aus. Außerdem unterstützt der Helfer die Rails unauffälligen Ajax.
Ruby 2,1, 2,2, 2,3, 2,4, 2,5, 2,6, 2,7, 3,0, 3,1, 3,2, 3,3, 3,3
Schienen 4.1, 4.2, 5,0, 5,1, 5,2, 6,0, 6,1, 7,0, 7,1, 7,2, 8,0
Sinatra 1.4, 2.0
Haml 3+
Mongoid 3+
Mongomapper 0,9+
DataMapper 1.1.0+
Um Kaminari auf dem Standard Rails -Stack zu installieren, legen Sie diese Linie einfach in Ihre GemFile ein:
gem 'kaminari'Dann Bündel:
% bundleWenn Sie Nicht-Sails oder Nicht-ActivereCord-App erstellen und die Paginierungsfunktion darauf wünschen, schauen Sie sich bitte einen anderen Abschnitt mit dem Rahmen-/Bibliotheksunterstützung an.
page Um die 7. Seite der Benutzer abzurufen (Standard per_page ist 25)
User . page ( 7 )HINWEIS: Die Pagination beginnt auf Seite 1, nicht auf Seite 0 (Seite (0) gibt dieselben Ergebnisse wie Seite (1)) zurück.
Kaminari fügt Fragen keine order hinzu. Um Überraschungen zu vermeiden, sollten Sie im Allgemeinen eine Bestellung in paginierten Anfragen aufnehmen. Zum Beispiel:
User . order ( :name ) . page ( 7 )Sie können Seitennummern oder Seitenbedingungen erhalten, indem Sie folgende Methoden verwenden.
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? #=> trueper Umfang Um jede Seite viel mehr Benutzer zu zeigen (ändern Sie den Wert per Wert)
User . order ( :name ) . page ( 7 ) . per ( 50 ) Beachten Sie, dass der per Umfang nicht direkt in den Modellen definiert ist, sondern nur eine Methode ist, die auf dem Seitenumfang definiert ist. Dies ist absolut vernünftig, da Sie per ohne Angabe der page niemals tatsächlich verwenden werden.
Denken Sie daran, dass per intern limit einsetzt und so die zuvor festgelegte limit überschreibt. Und wenn Sie die Größe für alle Anforderungsdatensätze erhalten möchten, können Sie total_count -Methode verwenden:
User . count #=> 1000
a = User . limit ( 5 ) ; a . count #=> 5
a . page ( 1 ) . per ( 20 ) . size #=> 20
a . page ( 1 ) . per ( 20 ) . total_count #=> 1000paddingGelegentlich müssen Sie eine Reihe von Datensätzen polieren, die nicht ein Vielfaches der Seitengröße sind.
User . order ( :name ) . page ( 7 ) . per ( 50 ) . padding ( 3 ) Beachten Sie, dass das padding auch nicht direkt in den Modellen definiert ist.
Wenn Sie aus irgendeinem Grund die page "Seite" und per Methoden, die Sie aufrufen können, 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 Sie können die folgenden Standardwerte konfigurieren, indem Sie diese Werte mit der Kaminari.configure -Methode überschreiben.
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
Es gibt einen praktischen Generator, der die Standardkonfigurationsdatei in das Verzeichnis config/Initializer generiert. Führen Sie den folgenden Generatorbefehl aus und bearbeiten Sie dann die generierte Datei.
% rails g kaminari:configpage_method_name Sie können die page "Methodenname" in bonzo oder plant oder was auch immer Sie mögen, um mit vorhandener page , Assoziation oder Umfang oder einem anderen Plugin, das die page auf Ihren Modellen definiert, gut zu spielen.
paginates_per Sie können den Standardwert per_page pro Modell mit dem folgenden deklarativen DSL angeben.
class User < ActiveRecord :: Base
paginates_per 50
endmax_paginates_per Sie können den maximalen per_page -Wert pro Modell mit dem folgenden deklarativen DSL angeben. Wenn die über per Umfang angegebene Variable mehr als diese Variable ist, wird max_paginates_per anstelle davon verwendet. Der Standardwert ist NIL, was bedeutet, dass Sie keinen maximalen per_page -Wert auferlegen.
class User < ActiveRecord :: Base
max_paginates_per 100
endmax_pages Sie können den Wert max_pages pro Modell mit dem folgenden deklarativen DSL angeben. Dieser Wert schränkt die Gesamtzahl der Seiten ein, die zurückgegeben werden können. Nützlich zum Festlegen von Grenzen für große Sammlungen.
class User < ActiveRecord :: Base
max_pages 100
end Wenn Sie das ransack_memory -Edelstein verwenden und Probleme haben, die zur vorherigen oder ersten Seite zurückkehren, setzen Sie die Einstellung params_on_first_page auf true .
params[:page]Normalerweise sieht Ihr Controller -Code so aus:
@users = User . order ( :name ) . page params [ :page ] Rufen Sie einfach den paginate -Helfer an:
<%= paginate @users %> Dadurch werden mehrere ?page=N Pagination -Links rendern, die von einem HTML5 <nav> -Tag umgeben sind.
paginate Helfermethode <%= paginate @users %> Dies würde mehrere Paginierungsverbindungen wie « First ‹ Prev ... 2 3 4 5 6 7 8 9 10 ... Next › Last » .
<%= paginate @users, window: 2 %> Dies würde so etwas wie ... 5 6 7 8 9 ... wenn 7 die aktuelle Seite ist.
<%= paginate @users, outer_window: 3 %> Dies würde ungefähr 1 2 3 ...(snip)... 18 19 20 ausgeben, während sie insgesamt 20 Seiten haben.
<%= paginate @users, left: 1, right: 3 %> Dies würde ungefähr 1 ...(snip)... 18 19 20 ausgeben, während sie insgesamt 20 Seiten haben.
:param_name ) für die Links <%= paginate @users, param_name: :pagina %> Dies würde den Parameternamen des Abfrage auf jedem Links ändern.
:params ) für die Links <%= paginate @users, params: {controller: 'foo', action: 'bar', format: :turbo_stream} %> Dies würde url_option jedes Links ändern. :controller und :action können die Tasten gemeinsam sein.
<%= paginate @users, remote: true %> Dies würde allen Links in Inside data-remote="true" hinzufügen.
<%= paginate @users, views_prefix: 'templates' %> Dies würde nach Teilungen in app/views/templates/kaminari suchen. Diese Option erleichtert es, Dinge wie A/B -Test -Paginationsvorlagen/Themen zu machen, gleichzeitig neue/alte Vorlagen sowie eine bessere Integration mit anderen Edelsteinen wie Zellen.
link_to_next_page und link_to_previous_page ( link_to_prev_page <%= link_to_next_page @items, 'Next Page' %> Dies macht einfach einen Link zur nächsten Seite. Dies wäre hilfreich, um eine Twitter-ähnliche Paginierungsfunktion zu erstellen.
Die Helfermethoden unterstützen eine params , um den Link weiter anzugeben. Wenn format festgelegt werden muss, geben Sie es in den params -Hash ein.
<%= link_to_next_page @items, 'Next Page', params: {controller: 'foo', action: 'bar', format: :turbo_stream} %> page_entries_info <%= page_entries_info @posts %>Dies macht eine hilfreiche Nachricht mit Anzahl der angezeigten und insgesamt Einträge.
Standardmäßig verwendet die Nachricht den humanisierten Klassennamen von Objekten in der Sammlung: Zum Beispiel "Projekttypen" für Projekttyp -Modelle. Der Namespace wird ausgeschnitten und nur der Nachname wird verwendet. Überschreiben Sie dies mit dem Parameter :entry_name :
<%= page_entries_info @posts, entry_name: 'item' %>
#= > Displaying items 6 - 10 of 26 in totalrel_next_prev_link_tags <%= rel_next_prev_link_tags @users %>Dies macht die REL -nächsten und die vorherrschenden Link -Tags für den Kopf.
path_to_next_page Helper -Methode <%= path_to_next_page @users %>Dies gibt den relativen Pfad des Servers auf die nächste Seite zurück.
path_to_prev_page <%= path_to_prev_page @users %>Dies gibt den relativen Pfad des Servers zur vorherigen Seite zurück.
Die Standardbezeichnungen für "First", "Last", "vorher", "..." und "Next" werden im i18n yaml im Motor gespeichert und durch I18N -API gerendert. Sie können den Etikettwert pro i18n.locale für Ihre internationale Anwendung wechseln. Schlüssel und die Standardwerte sind die folgenden. Sie können sie überschreiben, indem Sie eine YAML -Datei in Ihrem Rails.root/config/locales -Verzeichnis hinzufügen.
en :
views :
pagination :
first : " « First "
last : " Last » "
previous : " ‹ Prev "
next : " Next › "
truncate : " … "
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 " Wenn Sie eine nicht englische Lokalisierung verwenden, siehe I18N-Regeln zum Ändern von one_page:display_entries Block.
Kaminari enthält einen praktischen Vorlagengenerator.
Führen Sie den Generator zuerst aus,
% rails g kaminari:views default Bearbeiten Sie dann die Teilungen in app/views/kaminari/ Verzeichnis Ihrer App.
Sie können das HTML2HAML -Gem oder das HTML2Slim -Gem verwenden, um ERB -Vorlagen zu konvertieren. Das Kaminari -Edelstein sammelt automatisch Haml/Slim -Vorlagen, wenn Sie sie in app/views/kaminari/ .
Falls Sie unterschiedliche Vorlagen für Ihren Paginator benötigen (z. B. öffentlich und admin), können Sie wie folgt übergeben --views-prefix directory :
% rails g kaminari:views default --views-prefix admin Dies generiert Teilungen in app/views/admin/kaminari/ Verzeichnis.
Der Generator hat die Möglichkeit, mehrere Beispiel -Vorlagen -Themen aus dem externen Repository (https://github.com/amatsuda/kaminari_themes) zu holen, zusätzlich zum gebündelten "Standard", der Ihnen hilft, einen gut aussehenden Paginator zu erstellen.
% rails g kaminari:views THEME Um die vollständige Liste der verfügbaren Themen anzuzeigen, schauen Sie sich das Themen -Repository an oder klicken Sie einfach auf den Generator, ohne THEME Themenargument anzugeben.
% rails g kaminari:viewsUm mehrere Themen aus einer einzigen Anwendung zu verwenden, erstellen Sie ein Verzeichnis in der App/Ansichten/Kaminari/und verschieben Sie Ihre benutzerdefinierten Vorlagendateien in dieses Verzeichnis.
% 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/ Verweisen Sie als nächstes auf dieses Verzeichnis, wenn Sie die paginate Methode aufrufen:
<%= paginate @users, theme: 'my_custom_theme' %> Anpassen!
Hinweis: Wenn das Thema nicht vorhanden ist oder keiner angegeben ist, wird Kaminari standardmäßig die im Edelstein enthaltenen Ansichten zurückgeben.
Im Allgemeinen muss der Paginator die Gesamtzahl der Datensätze kennen, um die Links anzuzeigen, aber manchmal benötigen wir nicht die Gesamtzahl der Datensätze und benötigen nur die Links "vorherige Seite" und "nächste Seite". Für einen solchen Anwendungsfall stellt Kaminari without_count Modus für den Count eine paginierbare Sammlung bereit, ohne die Anzahl aller Datensätze zu zählen. Dies kann hilfreich sein, wenn Sie mit einem sehr großen Datensatz zu tun haben, da das Zählen auf einem großen Tisch in der Regel langsam auf RDBMs wird.
Fügen Sie einfach Ihrem paginierten Objekt zu .without_count hinzu:
User . page ( 3 ) . without_count In Ihrer Ansichtsdatei können Sie nur einfache Helfer wie das folgende anstelle des paginate Helfers mit vollem Funktionsumfang verwenden:
<%= link_to_prev_page @users, 'Previous Page' %>
<%= link_to_next_page @users, 'Next Page' %> Kaminari bietet eine Array -Wrapper -Klasse, die ein generisches Array -Objekt an den paginate View -Helfer anpasst. Der paginate -Helfer verarbeitet jedoch Ihr Array -Objekt nicht automatisch (dies ist beabsichtigt und entworfen). Kaminari::paginate_array -Methode wandelt Ihr Array -Objekt in ein paginierbares Array um, das page akzeptiert.
@paginatable_array = Kaminari . paginate_array ( my_array_object ) . page ( params [ :page ] ) . per ( 10 ) Sie können den Wert total_count über Optionen Hash angeben. Dies wäre hilfreich, wenn Sie ein Array-ischiges Objekt behandeln, das einen anderen count als die tatsächliche count hat, z. B. RSOLR-Suchergebnisse oder wenn Sie eine benutzerdefinierte Pagination erzeugen müssen. Zum Beispiel:
@paginatable_array = Kaminari . paginate_array ( [ ] , total_count : 145 ) . page ( params [ :page ] ) . per ( 10 )oder bei der Verwendung einer externen API, um die Datenseite zu beziehen:
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 ) Aufgrund des page Parameters und des Rails-Routings können Sie problemlos SEO- und benutzerfreundliche URLs generieren. Für jede Ressource, die Sie paginieren möchten, fügen Sie einfach Folgendes zu Ihren routes.rb hinzu.rb:
resources :my_resources do
get 'page/:page' , action : :index , on : :collection
end Wenn Sie Rails 4 oder höher verwenden, können Sie die Routendefinitionen mit concern vereinfachen:
concern :paginatable do
get '(page/:page)' , action : :index , on : :collection , as : ''
end
resources :my_resources , concerns : :paginatable Dies erstellt URLs wie /my_resources/page/33 anstelle von /my_resources?page=33 . Dies ist jetzt eine freundliche URL, aber auch andere zusätzliche Vorteile ...
Da der page jetzt ein URL -Segment ist, können wir das Caching der Rails -Seite nutzen!
Hinweis: In diesem Beispiel habe ich die Route auf meine :index hingewiesen. Möglicherweise haben Sie eine benutzerdefinierte Paginierungsaktion in Ihrem Controller definiert action: :your_custom_action
Technisch gesehen besteht das Kaminari -Edelstein aus 3 Einzelkomponenten:
kaminari-core: the core pagination logic
kaminari-activerecord: Active Record adapter
kaminari-actionview: Action View adapter
Daher entspricht das Bündeln von gem 'kaminari' den folgenden 2 Zeilen (Kaminari-Core wird aus den Adaptern verwiesen):
gem 'kaminari-activerecord'
gem 'kaminari-actionview'Wenn Sie andere unterstützte Ormen anstelle von Activerecord verwenden möchten, z. B. Mongoid, bündeln Sie seinen Adapter anstelle von Kaminari-Activerecord.
gem 'kaminari-mongoid'
gem 'kaminari-actionview'Kaminari stellt derzeit Adapter für folgende Ormen an:
Wenn Sie andere Web-Frameworks anstelle von Rails + Action View verwenden möchten, z. B. Sinatra, bündeln Sie seinen Adapter anstelle von Kaminari-Actionview.
gem 'kaminari-activerecord'
gem 'kaminari-sinatra'Kaminari bietet derzeit Adapter für die folgenden Webrahmen an:
Schauen Sie sich die Kaminari -Rezepte auf dem Github Wiki an, um fortschrittlichere Tipps und Techniken zu erhalten. https://github.com/kaminari/kaminari/wiki/kaminari-recipes
Fühlen Sie sich frei, mir auf Github (Amatsuda) oder Twitter (@A_MATSUDA) ☇☇☇ zu senden :)
Gabel, beheben und dann eine Pull -Anfrage senden.
Um die Testsuite lokal gegen alle unterstützten Frameworks auszuführen:
% bundle install
% rake test:allAuf die Testsuite gegen einen Framework abzielen:
% rake test:active_record_50 Sie finden eine Liste unterstützter Testaufgaben, indem Sie rake -T ausführen. Möglicherweise finden Sie es auch nützlich, einen bestimmten Test für ein bestimmtes Framework auszuführen. Dazu müssen Sie zunächst sicherstellen, dass Sie alles für diese Konfiguration gebündelt haben, und dann können Sie den spezifischen Test ausführen:
% 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. Weitere Informationen finden Sie unter MIT-Lizenz.
