kaminari
v1.2.2
Основная, чистая, мощная, мощная, мощная, настраиваемая и сложная страница для современных платформ веб -приложений и ORM
Не является глобально загрязненным Array , Hash , Object или AR::Base .
Просто объедините драгоценный камень, тогда ваши модели готовы к нанесению на страницу. Конфигурация не требуется. Не нужно ничего определять в ваших моделях или помощниках.
Все метод, цепный с меньшим «хасхеритом». Вы знаете, это современный путь. Нет специального класса коллекции или чего -либо еще для значений на странице, вместо этого используя экземпляр General AR::Relation . Таким образом, конечно, вы можете цепорить любые другие условия до или после масштаба Paginator.
Поскольку весь помощник по странице представляет собой в основном просто набор ссылок и не связанных с ними, Kaminari производит каждый из них через свой частичный шаблон внутри двигателя. Таким образом, вы можете легко изменить их поведение, стиль или что -то еще, переопределив частичные шаблоны.
Kaminari поддерживает несколько ORM (Activerecord, DataMapper, Mongoid, Mongomapper), несколько веб -структур (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
HAML 3+
Монгоид 3+
Mongomapper 0,9+
DataMapper 1.1.0+
Чтобы установить kaminari в стеке рельсов по умолчанию, просто поместите эту линию в свой Gemfile:
gem 'kaminari'Затем пучок:
% bundleЕсли вы строите приложение, не являющееся Rails или не ActivereCord и хотите на ней функцию страниц, посмотрите на другие рамки/библиотечную поддержку.
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? #=> trueper применение Чтобы показать гораздо больше пользователей на каждую страницу (измените per )
User . order ( :name ) . page ( 7 ) . per ( 50 ) Обратите внимание, что per прицела не определяется напрямую на моделях, но это просто метод, определяемый на сфере страницы. Это абсолютно разумно, потому что вы никогда не будете использовать per без указания номера page .
Имейте в виду, что 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 #=> 1000paddingВремя от времени вам нужно подумать о нескольких записях, которые не имеют кратного размера страницы.
User . order ( :name ) . page ( 7 ) . per ( 50 ) . padding ( 3 ) Обратите внимание, что применение padding также не определяется напрямую на моделях.
Если по какой -то причине вам нужно на page UNSCOPE и 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/initializers. Запустите следующую команду генератора, затем отредактируйте сгенерированный файл.
% rails g kaminari:configpage_method_name Вы можете изменить page названия метода на bonzo или plant или что -либо еще, чтобы играть хорошо с помощью существующего метода или ассоциации или сферы page или любого другого плагина, который определяет метод page на ваших моделях.
paginates_per Вы можете указать значение per_page по умолчанию на каждую модель, используя следующую декларативную DSL.
class User < ActiveRecord :: Base
paginates_per 50
endmax_paginates_per Вы можете указать значение MAX per_page на каждую модель, используя следующую декларативную DSL. Если переменная, указанная через область per область, больше, чем эта переменная, вместо этого используется max_paginates_per . Значение по умолчанию равна нулю, что означает, что вы не навязываете какое -либо per_page значение.
class User < ActiveRecord :: Base
max_paginates_per 100
endmax_pages Вы можете указать значение max_pages на каждую модель, используя следующую декларативную DSL. Это значение ограничивает общее количество страниц, которые могут быть возвращены. Полезно для настройки ограничений на больших коллекциях.
class User < ActiveRecord :: Base
max_pages 100
end Если вы используете драгоценный камень ransack_memory и проблемы с опытом, перемещающиеся обратно на предыдущую или первую страницу, установите настройку params_on_first_page на true .
params[:page]Как правило, ваш код контроллера будет выглядеть так:
@users = User . order ( :name ) . page params [ :page ] Просто позвоните на paginate помощник:
<%= paginate @users %> Это отобразит несколько ссылок на ?page=N окруженные HTML5 <nav> тегом.
paginate . <%= paginate @users %> Это выведет несколько ссылок на страниц, таких как « First ‹ Prev ... 2 3 4 5 6 7 8 9 10 ... Next › Last » .
<%= paginate @users, window: 2 %> Это выведет что -то вроде ... 5 6 7 8 9 ... когда 7 является текущей страницей.
<%= paginate @users, outer_window: 3 %> Это вызовет примерно 1 2 3 ...(snip)... 18 19 20 имея в общей сложности 20 страниц.
<%= 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 может быть общим ключами.
<%= paginate @users, remote: true %> Это добавило бы data-remote="true" ко всем ссылкам внутри.
<%= paginate @users, views_prefix: 'templates' %> Это будет искать частичные в app/views/templates/kaminari . Этот вариант облегчает выполнение таких вещей, как A/B -тестирование шаблонов/тем, используя новые/старые шаблоны одновременно, а также лучшую интеграцию с другими драгоценными камнями, такими как ячейки.
link_to_next_page и link_to_previous_page (псевдоним для link_to_prev_page ) Помощные методы <%= link_to_next_page @items, 'Next Page' %> Это просто отображает ссылку на следующую страницу. Это было бы полезно для создания функции страниц, похожей на Twitter.
Помощные методы поддерживают опцию params для дальнейшего указания ссылки. Если необходимо установить format , включите его в хэш params .
<%= 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 totalrel_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 %>Это возвращает относительный путь сервера на предыдущую страницу.
Ярлыки по умолчанию для «First», «last», «pret», «...» и «Next» хранятся в I18N YAML внутри двигателя и отображаются через API I18N. Вы можете переключить значение метки в соответствии с i18n.locale для вашего интернационализированного приложения. Ключи и значения по умолчанию являются следующими. Вы можете переопределить их, добавив в файл YAML в вашем каталоге 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 " Если вы используете неанглийскую локализацию, см. Правила i18n для изменения блока one_page:display_entries .
Каминари включает в себя удобный шаблонный генератор.
Сначала запустить генератор,
% rails g kaminari:views default Затем отредактируйте частичные в app/views/kaminari/ Directory.
Вы можете использовать драгоценный камень HTML2HAML или драгоценный камень HTML2SLIM для преобразования шаблонов ERB. Gem Kaminari автоматически забирает шаблоны Haml/Slim, если вы разместите их в app/views/kaminari/ .
В случае, если вам нужны разные шаблоны для вашего пагинатора (например, публичный и администратор), вы можете передать --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Чтобы использовать несколько тем изнутри одного приложения, создайте каталог в приложении/представлениях/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' %> Настройте!
ПРИМЕЧАНИЕ. Если тема не присутствует или не указана, Kaminari вернется к представлениям, включенным в драгоценность.
Как правило, пагинатор должен знать общее количество записей для отображения ссылок, но иногда нам не нужно общее количество записей и просто нужно ссылки «предыдущая страница» и «следующая страница». Для такого варианта использования Kaminari предоставляет режим without_count , который создает страстную коллекцию без подсчета количества всех записей. Это может быть полезно, когда вы имеете дело с очень большим набором данных, потому что подсчет на большой стол, как правило, становится медленным на RDBMS.
Просто .without_count .
User . page ( 3 ) . without_count В вашем файле просмотра вы можете использовать только простых помощников, например, следующие вместо полнофункционального paginate помощника:
<%= link_to_prev_page @users, 'Previous Page' %>
<%= link_to_next_page @users, 'Next Page' %> Kaminari предоставляет класс обертки массива, который адаптирует общий объект массива к атмосферу paginate . Тем не менее, paginate помощник не обрабатывает ваш объект массива (это преднамеренное и по дизайну). Kaminari::paginate_array Метод преобразует ваш объект массива в странный массив, который принимает метод page .
@paginatable_array = Kaminari . paginate_array ( my_array_object ) . page ( params [ :page ] ) . per ( 10 ) Вы можете указать значение total_count с помощью вариантов. Это было бы полезно при обработке объекта массива, который имеет другое значение count из фактического count такого как результаты поиска RSOLR или когда вам нужно генерировать пользовательскую страницу. Например:
@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 ) Из-за параметра 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 Это создаст URL -адреса, такие как /my_resources/page/33 вместо /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 строкам (от адаптеров ссылается kaminari-core):
gem 'kaminari-activerecord'
gem 'kaminari-actionview'Если вы хотите использовать другие поддерживаемые ORM вместо Activerecord, например, Mongoid, свяжите его адаптер вместо Kaminari-Activerecord.
gem 'kaminari-mongoid'
gem 'kaminari-actionview'Kaminari в настоящее время предоставляет адаптеры для следующих ORM:
Если вы хотите использовать другие веб-структуры вместо представления Rails + Action, например, Sinatra, свяжите его адаптер вместо Kaminari-Actionview.
gem 'kaminari-activerecord'
gem 'kaminari-sinatra'Kaminari в настоящее время предоставляет адаптеры для следующих веб -структур:
Проверьте рецепты Kaminari на Github Wiki для более продвинутых советов и методов. https://github.com/kaminari/kaminari/wiki/kaminari-recipes
Не стесняйтесь написать мне на GitHub (Amatsuda) или Twitter (@a_matsuda) ☇☇☇ :)
Вилка, исправить, затем отправьте запрос на вытягивание.
Чтобы запустить тестовый набор локально против всех поддерживаемых фреймворков:
% bundle install
% rake test:allЧтобы ориентироваться на тестовый набор против одной структуры:
% 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 Авторские права (с) 2011- Акира Мацуда. Смотрите MIT-License для получения более подробной информации.
