# Calendar Extra

This method wraps one or more levels of calendar filtering on top of another backend pagination method ( e.g. pagy, pagy_arel, pagy_array, pagy_searchkick, pagy_elasticsearch_rails, pagy_meilisearch, ...).

It filters the collection by the selected time units in the configuration (e.g. year, month, day, ...), and forwards it to the wrapped method.

It returns an array with one more item than the usual two:

@calendar, @pagy, @results = pagy_calendar(...)

The @calendar is the hash of the generated Pagy::Calendar::* objects that can be used in the UI.

It also provides the showtime helper method that returns the DateTime of the smallest time unit currently shown in your calendar. For example:

<!-- Link to go to a specific page in the calendar -->
<a href="<%= pagy_calendar_url_at(@calendar, Time.zone.parse('2022-03-03')) %>">Go to the 2022-03 Page</a>

<!-- Showtime shows the `DateTime` beginning of the smallest time unit currently shown in the calendar -->
<p>Showtime: <%= @calendar.showtime %></p>

The collection argument (from ActiveRecord, ElasticSearchRails, Searchkick, Meilisearch, ...) is filtered by the pagy_calendar_filter and forwarded to the wrapped method for its final pagination, so ensure that you pass the same type of argument expected by the wrapped method.

The configuration argument must be a Hash structure with the keys representing the type of configuration and the values being the Hash of the variables that you want to pass for the creation of the specific pagy object (or a boolean for the Active flag).

The configuration hash can be composed by the following types of configuration:

The calendar configuration determines the calendar objects generated. These are used for filtering the collection to the selected time units.

You can add one or more levels with keys like :year, :quarter, :month, :week, :day. Each key must be set to the hash of the variables that will be used to initialize the relative Pagy::Calendar::* object. Use an empty hash for default values. E.g.: year: {}, month: {}, ....

This is the optional configuration of the final pagination object (produced by the wrapped method) which is always used regardless the value of the Active flag.

You can pass one optional :pagy key, set to the hash of the variables to initialize the Pagy object. It has none of the restriction mentioned in the Calendar configuration.

Besides the usual pagy variables, you can add a :backend variable, set to the name of the backend extra method that you want to use for managing the collection:

{ pagy: { backend: :pagy_searchkick, items: 10, ... } }

Notice that the collection argument must be exactly what you would pass to the wrapped backend method.

If the :pagy key/value is omitted, a default Pagy instance will be created by the default :pagy backend method.

The calendar is active by default, however you can add an optional :active boolean flag to the configuration hash in order to switch it ON or OFF, depending on its usefulness in different conditions (see the Use cases).

It receives a collection argument that must not be changed by the method, but can be used to return the starting and ending local TimeWithZone objects array defining the calendar :period. See the Pagy::Calendar Variables for details.

Depending on the type of storage, the collection argument can contain a different kind of object:

If you use ActiveRecord the collection is going to be an ActiveRecord::Relation object. You can use it to return the starting and ending local TimeWithZone objects array. Here are a few examples with the created_at field (but you can pull the time from anywhere):

# Simpler version (2 queries)
def pagy_calendar_period(collection)
  starting = collection.minimum('created_at')
  ending   = collection.maximum('created_at')
  [starting.in_time_zone, ending.in_time_zone]
end

# Faster version with manual pluck (1 query)
def pagy_calendar_period(collection)
  minmax = collection.pluck('MIN(created_at)', 'MAX(created_at)').first
  minmax.map { |time| Time.parse(time).in_time_zone }
end

# Fastest version (no queries)
# If you have the starting and ending times in the request (from UI selectors), 
# filter the collection by the param before passing it to `pagy_calendar`. 
# In this example you just use the :starting and :ending params to return the period
def pagy_calendar_period(collection)
  params.fetch_values(:starting, :ending).map { |time| Time.parse(time).in_time_zone }
end

See also Time conversion for details.

If you use ElasticSearchRails, Searchkick, Meilisearch the collection argument is just the Array of the captured search arguments that you passed to the Model.pagy_search method. That array is what pagy uses internally to setup its variables before passing it to the standard Model.search method to do the actual search.

So you should use what you need from the collection array and do your own Model.search(...) in order to get the starting and ending local TimeWithZone objects array to return.

It receives the main collection and must return a filtered version of it using the from and to local Time objects.

You should filter your collection with a logic equivalent to storage_time >= from && storage_time < to, adapted to the time zone and syntax of your storage.

Depending on the type of storage, the collection argument can contain a different kind of object:

If you use ActiveRecord the collection is going to be an ActiveRecord::Relation object that you can easily filter. Here is an example with the created_at field again (but you can use anything, of course):

def pagy_calendar_filter(collection, from, to)
  collection.where(created_at: from...to) # 3-dots range excluding the end value
end

See also Time conversion for details.

If you use ElasticSearchRails, Searchkick, Meilisearch the collection argument is just the Array of the captured search arguments that you passed to the Model.pagy_search method. That array is what pagy uses internally to setup its variables before passing it to the standard Model.search method to do the actual search.

So in order to filter the actual search with the from and to local TimeWithZone objects, you should simply return the same array with the filtering added to its relevant item. Pagy will use it to do the actual (filtered) search.