kaminari
v1.2.2
Un paginador basado en el alcance y el motor, limpio, potente, personalizable y sofisticado para los modernos marcos de aplicaciones web y ORMS
No contamina globalmente Array , Hash , Object o AR::Base .
Simplemente agrupe la gema, entonces sus modelos están listos para ser paginados. No se requiere configuración. No tiene que definir nada en sus modelos o ayudantes.
Todo es el método en cadena de menos "Hasheritis". Ya sabes, esa es la forma moderna de Rails. No hay clase de recolección especial ni nada para los valores paginados, en su lugar, utilizando una instancia general AR::Relation . Entonces, por supuesto, puede encadenar cualquier otra condición antes o después del alcance del paginador.
Como todo el ayudante de paginación es básicamente una colección de enlaces y no enlaces, Kaminari hace que cada uno de ellos a través de su propia plantilla parcial dentro del motor. Por lo tanto, puede modificar fácilmente su comportamiento, estilo o lo que sea anulando plantillas parciales.
Kaminari admite múltiples ORMS (Activerecord, DataMapper, Mongoid, Mongomapper), múltiples marcos web (Rails, Sinatra, Grape) y motores de plantillas múltiples (ERB, Haml, Slim).
El ayudante de paginación genera la etiqueta HTML5 <nav> de forma predeterminada. Además, el ayudante admite Rails discreto 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
Sinatra 1.4, 2.0
Haml 3+
Mongoide 3+
Mongomapper 0.9+
DATAMAPPER 1.1.0+
Para instalar kaminari en la pila de rieles predeterminados, simplemente coloque esta línea en su archivo gem:
gem 'kaminari'Luego paquete:
% bundleSi está construyendo una aplicación sin rieles o no activos y desea la función de paginación, eche un vistazo a otra sección de soporte de marco/biblioteca.
page Para obtener la séptima página de los usuarios ( per_page predeterminado es 25)
User . page ( 7 )Nota: La paginación comienza en la página 1, no en la página 0 (página (0) devolverá los mismos resultados que la página (1)).
Kaminari no agrega un order a las consultas. Para evitar sorpresas, generalmente debe incluir un pedido en consultas paginadas. Por ejemplo:
User . order ( :name ) . page ( 7 )Puede obtener números de página o condiciones de página utilizando los métodos a continuación.
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 alcance Para mostrar muchos más usuarios por cada página (cambie el valor per )
User . order ( :name ) . page ( 7 ) . per ( 50 ) Tenga en cuenta que el alcance per no se define directamente en los modelos, sino que es solo un método definido en el alcance de la página. Esto es absolutamente razonable porque en realidad nunca usará per sin especificar el número page .
Tenga en cuenta que per utilizar internamente limit y, por lo tanto, anulará cualquier limit que se estableciera anteriormente. Y si desea obtener el tamaño de todos los registros de solicitud, puede usar el método 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 #=> 1000paddingOcasionalmente, debe rellenar una serie de registros que no son un múltiplo del tamaño de la página.
User . order ( :name ) . page ( 7 ) . per ( 50 ) . padding ( 3 ) Tenga en cuenta que el alcance padding tampoco se define directamente en los modelos.
Si por alguna razón necesita sin cesar page y per los métodos, puede llamar 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 Puede configurar los siguientes valores predeterminados anulando estos valores usando el método 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
Hay un generador práctico que genera el archivo de configuración predeterminado en el directorio config/inicializadores. Ejecute el siguiente comando generador, luego edite el archivo generado.
% rails g kaminari:configpage_method_name Puede cambiar la page de nombre del método a bonzo o plant o lo que desee, para jugar bien con el método o asociación page existente o alcance o cualquier otro complemento que define el método page en sus modelos.
paginates_per Puede especificar el valor per_page predeterminado por cada modelo utilizando el siguiente DSL declarativo.
class User < ActiveRecord :: Base
paginates_per 50
endmax_paginates_per Puede especificar el valor máximo per_page por cada modelo utilizando el siguiente DSL declarativo. Si la variable que se especifica a través per es más que esta variable, se usa max_paginates_per en lugar de ella. El valor predeterminado es nulo, lo que significa que no está imponiendo ningún valor máximo per_page .
class User < ActiveRecord :: Base
max_paginates_per 100
endmax_pages Puede especificar el valor max_pages por cada modelo utilizando el siguiente DSL declarativo. Este valor restringe el número total de páginas que se pueden devolver. Útil para establecer límites en grandes colecciones.
class User < ActiveRecord :: Base
max_pages 100
end Si está utilizando la gema ransack_memory y experimenta problemas para navegar a la página anterior o primera, establezca la configuración de params_on_first_page en true .
params[:page]Por lo general, su código de controlador se verá así:
@users = User . order ( :name ) . page params [ :page ] Simplemente llame al ayudante paginate :
<%= paginate @users %> <nav> hará varios ?page=N
paginate <%= paginate @users %> Esto generaría varios enlaces de paginación como « First ‹ Prev ... 2 3 4 5 6 7 8 9 10 ... Next › Last » .
<%= paginate @users, window: 2 %> Esto generaría algo como ... 5 6 7 8 9 ... cuando 7 es la página actual.
<%= paginate @users, outer_window: 3 %> Esto generaría algo así como 1 2 3 ...(snip)... 18 19 20 mientras tiene 20 páginas en total.
<%= paginate @users, left: 1, right: 3 %> Esto generaría algo así como 1 ...(snip)... 18 19 20 mientras tiene 20 páginas en total.
:param_name ) para los enlaces <%= paginate @users, param_name: :pagina %> Esto modificaría el nombre del parámetro de consulta en cada enlace.
:params ) para los enlaces <%= paginate @users, params: {controller: 'foo', action: 'bar', format: :turbo_stream} %> Esto modificaría url_option de cada enlace. :controller y :action podría ser las claves en común.
<%= paginate @users, remote: true %> Esto agregaría data-remote="true" a todos los enlaces dentro.
<%= paginate @users, views_prefix: 'templates' %> Esto buscaría parciales en app/views/templates/kaminari . Esta opción hace que sea más fácil hacer cosas como las plantillas/temas de paginación de prueba A/B, utilizando plantillas nuevas/antiguas al mismo tiempo, así como una mejor integración con otras gemas como las células.
link_to_next_page y link_to_previous_page (aliased link_to_prev_page ) Métodos de ayuda <%= link_to_next_page @items, 'Next Page' %> Esto simplemente representa un enlace a la página siguiente. Esto sería útil para crear una función de paginación similar a Twitter.
Los métodos auxiliares admiten una opción params para especificar aún más el enlace. Si se debe establecer format , inclúyelo en el hash params .
<%= link_to_next_page @items, 'Next Page', params: {controller: 'foo', action: 'bar', format: :turbo_stream} %> page_entries_info Helper <%= page_entries_info @posts %>Esto hace que un mensaje útil con números de entradas mostradas versus totales.
De manera predeterminada, el mensaje utilizará el nombre de clase humanizado de los objetos en la colección: por ejemplo, "tipos de proyectos" para modelos ProjectType. El espacio de nombres se cortará y solo se usará el apellido. Anule esto con el parámetro :entry_name :
<%= page_entries_info @posts, entry_name: 'item' %>
#= > Displaying items 6 - 10 of 26 in totalrel_next_prev_link_tags Helper <%= rel_next_prev_link_tags @users %>Esto representa las etiquetas REL SIGUITAS y PREVION LINK para la cabeza.
path_to_next_page <%= path_to_next_page @users %>Esto devuelve la ruta relativa del servidor a la página siguiente.
path_to_prev_page <%= path_to_prev_page @users %>Esto devuelve la ruta relativa del servidor a la página anterior.
Las etiquetas predeterminadas para 'Primero', 'Último', 'Anterior', '...' y 'Next' se almacenan en el I18N YAML dentro del motor y se reproducen a través de la API I18N. Puede cambiar el valor de la etiqueta por i18n.locale para su aplicación internacionalizada. Las claves y los valores predeterminados son los siguientes. Puede anularlos agregando a un archivo YAML en sus Rails.root/config/locales .
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 " Si usa la localización no inglesa, consulte las reglas i18n para cambiar one_page:display_entries Block.
Kaminari incluye un práctico generador de plantillas.
Ejecute el generador primero,
% rails g kaminari:views default Luego edite los parciales en app/views/kaminari/ directorio de su aplicación.
Puede usar la gema html2haml o la gema html2slim para convertir las plantillas ERB. La gema de Kaminari recogerá automáticamente plantillas Haml/Slim si las coloca en app/views/kaminari/ .
En caso de que necesite diferentes plantillas para su paginador (por ejemplo, público y administrador), puede aprobar --views-prefix directory como este:
% rails g kaminari:views default --views-prefix admin Eso generará parciales en app/views/admin/kaminari/ Directorio.
El generador tiene la capacidad de obtener varios temas de plantilla de muestra del repositorio externo (https://github.com/amatsuda/kaminari_themes) además del "predeterminado" inclinado, lo que lo ayudará a crear un paginador de buen aspecto.
% rails g kaminari:views THEME Para ver la lista completa de temas disponibles, eche un vistazo al repositorio de temas o simplemente presione el generador sin especificar el argumento THEME .
% rails g kaminari:viewsPara utilizar múltiples temas desde una sola aplicación, cree un directorio dentro de la aplicación/vistas/kaminari/y mueva sus archivos de plantilla personalizados a ese directorio.
% 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/ A continuación, haga referencia a ese directorio al llamar al método paginate :
<%= paginate @users, theme: 'my_custom_theme' %> ¡Personalizar lejos!
Nota: Si el tema no está presente o no se especifica ninguno, Kaminari volverá a las vistas incluidas dentro de la gema.
En general, el Paginator necesita saber el número total de registros para mostrar los enlaces, pero a veces no necesitamos el número total de registros y solo necesitamos los enlaces "Página anterior" y "Página siguiente". Para dicho caso de uso, Kaminari proporciona el modo without_count que crea una colección paginatable sin contar el número de todos los registros. Esto puede ser útil cuando se trata de un conjunto de datos muy grande porque contar con una tabla grande tiende a acelerar en RDBMS.
Simplemente agregue .without_count a su objeto paginado:
User . page ( 3 ) . without_count En su archivo de vista, solo puede usar ayudantes simples como los siguientes en lugar del ayudante paginate con todas las funciones:
<%= link_to_prev_page @users, 'Previous Page' %>
<%= link_to_next_page @users, 'Next Page' %> Kaminari proporciona una clase de envoltorio de matriz que adapta un objeto de matriz genérico al ayudante paginate View. Sin embargo, el ayudante paginate no maneja automáticamente su objeto de matriz (esto es intencional y por diseño). El método Kaminari::paginate_array convierte su objeto de matriz en una matriz paginatable que acepta el método page .
@paginatable_array = Kaminari . paginate_array ( my_array_object ) . page ( params [ :page ] ) . per ( 10 ) Puede especificar el valor total_count a través de opciones hash. Esto sería útil al manejar un objeto de matriz que tiene un valor count diferente del count real, como el resultado de la búsqueda RSOLR o cuando necesita generar una paginación personalizada. Por ejemplo:
@paginatable_array = Kaminari . paginate_array ( [ ] , total_count : 145 ) . page ( params [ :page ] ) . per ( 10 )o, en el caso de usar una API externa para obtener la página de datos:
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 ) Debido al parámetro page y al enrutamiento de rieles, puede generar fácilmente SEO y URL fáciles de usar. Para cualquier recurso que desee paginar, simplemente agregue lo siguiente a sus routes.rb :
resources :my_resources do
get 'page/:page' , action : :index , on : :collection
end Si está utilizando Rails 4 o posterior, puede simplificar las definiciones de ruta utilizando concern :
concern :paginatable do
get '(page/:page)' , action : :index , on : :collection , as : ''
end
resources :my_resources , concerns : :paginatable Esto creará URL como /my_resources/page/33 en lugar de /my_resources?page=33 . Esta es ahora una URL amigable, pero también tiene otros beneficios adicionales ...
Debido a que el parámetro page ahora es un segmento de URL, ¡podemos aprovechar el almacenamiento en caché de la página de rieles!
Nota: En este ejemplo, he señalado la ruta a mi acción :index . Es posible que haya definido una acción de paginación personalizada en su controlador: debe apuntar action: :your_custom_action .
Técnicamente, la gema Kaminari consta de 3 componentes individuales:
kaminari-core: the core pagination logic
kaminari-activerecord: Active Record adapter
kaminari-actionview: Action View adapter
Entonces, gem 'kaminari' es equivalente a las siguientes 2 líneas (Kaminari-Core se hace referencia a los adaptadores):
gem 'kaminari-activerecord'
gem 'kaminari-actionview'Si desea usar otros ORMS compatibles en lugar de Activerecord, por ejemplo Mongoide, agrupe su adaptador en lugar de Kaminari-Activerecord.
gem 'kaminari-mongoid'
gem 'kaminari-actionview'Kaminari actualmente proporciona adaptadores para los siguientes ORM:
Si desea utilizar otros marcos web en lugar de Rails + Action View, por ejemplo Sinatra, agrupe su adaptador en lugar de Kaminari-ActionView.
gem 'kaminari-activerecord'
gem 'kaminari-sinatra'Kaminari actualmente proporciona adaptadores para los siguientes marcos web:
Echa un vistazo a las recetas de Kaminari en el Wiki GitHub para obtener consejos y técnicas más avanzados. https://github.com/kaminari/kaminari/wiki/kaminari-recipes
No dude en enviarme un mensaje en Github (Amatsuda) o Twitter (@A_Matsuda) ☇☇☇ :)
Fork, arreglar, luego envíe una solicitud de extracción.
Para ejecutar la suite de prueba localmente en todos los marcos compatibles:
% bundle install
% rake test:allPara apuntar a la suite de prueba contra un marco:
% rake test:active_record_50 Puede encontrar una lista de tareas de prueba compatibles ejecutando rake -T . También puede encontrar útil ejecutar una prueba específica para un marco específico. Para hacerlo, primero deberá asegurarse de haber incluido todo para esa configuración, luego puede ejecutar la prueba específica:
% 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. Ver MIT-License para más detalles.
