Grape Listing

Gem Version

Гем для пагинации и фильтрации записей с возможностью формирования электронных таблиц (XLSX) на базе Grape.

Установка

Добавить в Gemfile

gem 'grape-listing'

И выполнить:

bundle

Использование

Использование с помощью вызова метода-хелпера listing и передачи в него необходимых опций.

Например:

get 'users' do
  listing model: User,
          entity: UserEntity
end

Опции (с примерами):

model: User - модель, записи которой нужно обработать

preload: [:posts] - связи, которые нужно подгрузить для eager load

entity: UserEntity - класс Grape Entity, который обработает каждую запись (передается вместо fields)

scopes: proc {...} - блок кода для применения

fields: %i[...] - список полей, которые должны присутствовать в списке записей (передается вместо entity)

search: %w[...] - список полей, по которым должна осуществляться фильтрация (поиск)

sortable: %w[...] - список полей, по которым может осуществляться сортировка

paginate: false - отдавать результат без пагинации, сразу всей коллекцией (по умолчанию - с пагинацией)

Параметры HTTP запроса

Некоторые функции, такие, как поиск (фильтрация), сортировка и формирование эл. таблиц осуществляется путем обработки параметров HTTP запроса.

Поиск

Для возможности поиска необходимо передать названия полей, по которым может осуществляться поиск, в виде массива в опции search.

Для осуществления фильтрации необходимо передать параметры в запросе в виде ?field=value. Для поиска по нескольким полям, параметры должны быть перечислены через &, например: ?field_1=value&field_2=value.

В общем случае, названия полей соответствуют названиями параметров (например поле name и параметр name).

Пример использования с осуществлением поиска по полю name с полным совпадением:

get 'users' do
  listing model: User,
          entity: UserEntity,
          search: %w[name]
end

GET http://localhost:3000/api/users?name=Ivan

Сортировка

Для сортировки выдачи необходимо передать в параметрах запроса:

  • sort_by - название поля, по которому должна осуществляться сортировка.

  • sort_order направление, по которому должна осуществляться сортировка (asc/desc).

По умолчанию сортировка осуществляется по id записей в направлении DESC.

Ограничение полей

При передаче параметра columns[]= результаты в ответе ограничиваются переданным массив колонок.

Формирование эл. таблиц

При передаче параметра spreadsheet=true происходит формирование эл. таблицы в виде XLSX файла с учетом всех остальных переданных параметров.

Заголовки эл. таблицы будут взяты из описаний полей таблицы БД с соответствующими названиями или описаний полей Grape Entity.

Конфигурация

Добавьте файл конфигурации config/initializers/grape_listing.rb с содержимым:

GrapeListing.configure do |config|
end