Skip to content

Commit

Permalink
refactoring extras:
Browse files Browse the repository at this point in the history
- moved pagy-extra files into the extras dir
- moved the templates dir into the extras dir
- updated the documentation
  • Loading branch information
ddnexus committed May 29, 2018
1 parent 61893bb commit f764cc1
Show file tree
Hide file tree
Showing 26 changed files with 386 additions and 96 deletions.
10 changes: 5 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,37 +74,37 @@ Or - if you prefer - render the navigation links with a template:

## Easy to extend

Use the official extras contained in the [pagy-extras](https://github.com/ddnexus/pagy-extras) gem, or write your own in just a few lines.
Use the official extras, or write your own in just a few lines.

### Frontend Extras

#### Bootstrap Extra

Nav helper and templates for Bootstrap pagination. ([More info...](http://ddnexus.github.io/pagy/pagy-extras/bootstrap))
Nav helper and templates for Bootstrap pagination. ([More info...](http://ddnexus.github.io/pagy/extras/bootstrap))

#### Responsive Extra

On resize, the number of page links will adapt in real-time to the available window or container width.

![pagy-responsive](docs/assets/images/pagy-responsive-w.png)

([More info...](http://ddnexus.github.io/pagy/pagy-extras/responsive))
([More info...](http://ddnexus.github.io/pagy/extras/responsive))

#### Compact Extra

An alternative UI that combines the pagination feature with the navigation info in one compact element.

![pagy-compact](docs/assets/images/pagy-compact-w.png)

([More info...](http://ddnexus.github.io/pagy/pagy-extras/compact))
([More info...](http://ddnexus.github.io/pagy/extras/compact))

### Backend Extras

More specialized backend methods for specific types of collection that play well with each other and avoid overriding.

#### Array Extra

Paginate arrays effiently avoiding expensive array-wrapping and wihout overriding. ([More info...](http://ddnexus.github.io/pagy/pagy-extras/array))
Paginate arrays effiently avoiding expensive array-wrapping and wihout overriding. ([More info...](http://ddnexus.github.io/pagy/extras/array))

## Chat Support and Feedback

Expand Down
10 changes: 5 additions & 5 deletions docs/_layouts/default.html
Original file line number Diff line number Diff line change
Expand Up @@ -32,11 +32,11 @@
<a href="{{ site.baseurl }}/api/pagy"><p class="indent1" {% if page.title == 'Pagy' %}id="active"{% endif %} >Pagy</p></a>
<a href="{{ site.baseurl }}/api/backend"><p class="indent1" {% if page.title == 'Pagy::Backend' %}id="active"{% endif %} >Pagy::Backend</p></a>
<a href="{{ site.baseurl }}/api/frontend"><p class="indent1" {% if page.title == 'Pagy::Frontend' %}id="active"{% endif %} >Pagy::Frontend</p></a>
<a href="{{ site.baseurl }}/pagy-extras"><p {% if page.title == 'Pagy Extras' %}id="active"{% endif %} >Pagy Extras</p></a>
<a href="{{ site.baseurl }}/pagy-extras/bootstrap"><p class="indent1" {% if page.title == 'Bootstrap' %}id="active"{% endif %} >Bootstrap</p></a>
<a href="{{ site.baseurl }}/pagy-extras/responsive"><p class="indent1" {% if page.title == 'Responsive' %}id="active"{% endif %} >Responsive</p></a>
<a href="{{ site.baseurl }}/pagy-extras/compact"><p class="indent1" {% if page.title == 'Compact' %}id="active"{% endif %} >Compact</p></a>
<a href="{{ site.baseurl }}/pagy-extras/array"><p class="indent1" {% if page.title == 'Array' %}id="active"{% endif %} >Array</p></a>
<a href="{{ site.baseurl }}/extras"><p {% if page.title == 'Extras' %}id="active"{% endif %} >Extras</p></a>
<a href="{{ site.baseurl }}/extras/bootstrap"><p class="indent1" {% if page.title == 'Bootstrap' %}id="active"{% endif %} >Bootstrap</p></a>
<a href="{{ site.baseurl }}/extras/responsive"><p class="indent1" {% if page.title == 'Responsive' %}id="active"{% endif %} >Responsive</p></a>
<a href="{{ site.baseurl }}/extras/compact"><p class="indent1" {% if page.title == 'Compact' %}id="active"{% endif %} >Compact</p></a>
<a href="{{ site.baseurl }}/extras/array"><p class="indent1" {% if page.title == 'Array' %}id="active"{% endif %} >Array</p></a>
<a href="{{ site.baseurl }}/migration-tips"><p {% if page.title == 'Migration Tips' %}id="active"{% endif %} >Migration Tips</p></a>
<p id="gitter-support"><a href="https://gitter.im/ruby-pagy/Lobby" rel="nofollow" target="_blank">&gt; Chat Support on Gitter &lt;</a></p>
</div>
Expand Down
8 changes: 4 additions & 4 deletions docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ title: API
The whole code structure of pagy is very simple: it is organized around 3 small modules of just ~100 lines of code in total:

| Module | Description | Links |
|:-----------------|:----------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------|
| `Pagy` | The small class that keeps track of the variables involved in the pagination | 













































[source](https://github.com/ddnexus/pagy/blob/master/lib/pagy.rb), 













































[documentation](api/pagy.md) |
| `Pagy::Backend` | The optional module that you can include in your controllers in order to automatically create the Pagy instance | 













































[source](https://github.com/ddnexus/pagy/blob/master/lib/pagy/backend.rb), 













































[documentation](api/backend.md) |
| `Pagy::Frontend` | The module to include in your views in order to get a few helpers for the HTML output | 













































[source](https://github.com/ddnexus/pagy/blob/master/lib/pagy/frontend.rb), 













































[documentation](api/frontend.md) |
|:-----------------|:---------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------|
| `Pagy` | The small class that keeps track of the variables involved in the pagination | [source](https://github.com/ddnexus/pagy/blob/master/lib/pagy.rb), [documentation](api/pagy.md) |
| `Pagy::Backend` | The optional module that you can include in your controllers in order to automatically create the Pagy instance | [source](https://github.com/ddnexus/pagy/blob/master/lib/pagy/backend.rb), [documentation](api/backend.md) |
| `Pagy::Frontend` | The module to include in your views in order to get a few helpers for the HTML output | [source](https://github.com/ddnexus/pagy/blob/master/lib/pagy/frontend.rb), [documentation](api/frontend.md) |
7 changes: 3 additions & 4 deletions docs/api/backend.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,10 @@ title: Pagy::Backend

This module provides a _generic_ pagination method (`pagy`) that works out of the box with any ORM collection (e.g. `ActiveRecord`, `Sequel`, `Mongoid`, ... collections), plus two sub-methods that you may want to override in order to customize it for any type of collection (e.g. Array, elasticsearch results, etc.) _([source](https://github.com/ddnexus/pagy/blob/master/lib/pagy/backend.rb))_

If you use also the `pagy-extras` gem, this module will get extended by a few _specific_ pagination methods, very convenient to use with _specific_ types of collections like Array, elasticsearch results, etc.
You can extend this module with a few _specific_ pagination methods, very convenient to use with _specific_ types of collections like Array, elasticsearch results, etc. _(see the [extras](../extras.md) doc for more details)_

__Notice__: Currently, the only available backend extra is the [array extra](../pagy-extras/array.md), but stay tuned, because there will be more in the near future.
__Notice__: Currently, the only available backend extra is the [array extra](../extras/array.md), but stay tuned, because there will be more in the near future.

_(see the [pagy-extras](../pagy-extras.md) doc for more details)_


## Synopsys
Expand Down Expand Up @@ -91,4 +90,4 @@ def pagy_get_items(array, pagy)
array[pagy.offset, pagy.items]
end
```
__Notice__: in order to paginate arrays, you may want to use the `array` extra.
__Notice__: in order to paginate arrays, you may want to use the [array extra](../extras/array.md).
4 changes: 2 additions & 2 deletions docs/api/frontend.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ title: Pagy::Frontend

This module provides a few methods to deal with the navigation aspect of the pagination. You will usually include it in some helper module, making its methods available (and overridable) in your views. _([source](https://github.com/ddnexus/pagy/blob/master/lib/pagy/frontend.rb))_

If you use also the `pagy-extras` gem, this module will get extended by a few more `nav_*` helpers _(see the [pagy-extras](../pagy-extras.md) doc for more details)_
You can extend this module with a few more `nav_*` helpers _(see the [extras](../extras.md) doc for more details)_

## Synopsys

Expand Down Expand Up @@ -186,7 +186,7 @@ Pagy will define the `pagy_t` method to use the `I18n` gem if available, or the
That works in all conditions, however - for performance reasons - you may want to force using the internal 5x faster implementation even in presence of `I18n` (e.g. with rails). You should do so only in case of single-language apps (e.g. only 'en', or only 'fr'...) since the internal implementation supports only pluralization and interpolation but not translation.
If you want to force the internal faster implementation, you should explicitly set `Pagy::I18N[:gem] = false` in an initializer. In case you are also using the `pagy-extras` you should also ensure to require it only after the `Pagy::I18N[:gem]` variable has been set.
If you want to force the internal faster implementation, you should explicitly set `Pagy::I18N[:gem] = false` in an initializer. In case you are also using some frontend extra, you should also ensure to require the extra only after the `Pagy::I18N[:gem]` variable has been set.
#### Pagy::I18N[:file]
Expand Down
2 changes: 1 addition & 1 deletion docs/api/pagy.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ These are the core-variables (i.e. instance variables that define the pagination
| `:page` | the requested page number | `1` |
| `:items` | the _requested_ number of items for the page | `20` |
| `:outset` | the initial offset of the collection to paginate: pass it only if the collection was pre-offset(ted) | `0` |
| `:size` | the size of the page links to show: array of initial pages, before current page, after current page, final pages. _(see also 











[Control the page links](../how-to.md#controlling-the-page-links))_ | `[1,4,4,1]` |
| `:size` | the size of the page links to show: array of initial pages, before current page, after current page, final pages. _(see also [Control the page links](../how-to.md#controlling-the-page-links))_ | `[1,4,4,1]` |

__Notice__: Pagy replaces the blank values of scalar core variables (so excluding `:size`) with their default values. It also applies `to_i` on the values expected to be integers, so you can use values from request `params` without problems. For example: `pagy(some_scope, items: params[:items])` will work without any additional cleanup.

Expand Down
29 changes: 29 additions & 0 deletions docs/extras.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
---
title: Extras
---

# Extras
Pagy comes with a few optional extensions/extras:

| Extra | Description | Links |
|:-------------|:-------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `bootstrap` | Nav helper and templates for Bootstrap pagination | [bootstrap.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/bootstrap.rb), [documentation](extras/bootstrap.md) |
| `responsive` | On resize, the number of page links will adapt in real-time to the available window or container width | [responsive.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/responsive.rb), [pagy-responsive.js](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/javascripts/pagy-responsive.js), [documentation](extras/responsive.md) |
| `compact` | An alternative UI that combines the pagination feature with the navigation info in one compact element | [compact.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/compact.rb), [pagy-compact.js](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/javascripts/pagy-compact.js), [documentation](extras/compact.md) |
| `array` | Paginate arrays effiently avoiding expensive array-wrapping and wihout overriding | [array.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/array.rb), [documentation](extras/array.md) |

## Synopsys

Extras are not loaded by default, so you should require them explicitly in your initializer:
```ruby
require 'pagy/extras/bootstrap'
require 'pagy/extras/...'
```

## Description

Extras don't define any new module or class, they just re-open the `Pagy` class and modules, adding the extra methods as they were part of the loaded `pagy` gem. This neatly separates the core code from the optional extras, still keeping its usage as simple as it were part of the core gem.

## Methods

All the added methods are documented in the respective extras.
4 changes: 2 additions & 2 deletions docs/pagy-extras/array.md → docs/extras/array.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ That means that you can paginate the array independently from any other kind of

## Synopsys

See [pagy-extras](../pagy-extras.md) for general usage info.
See [extras](../extras.md) for general usage info.

In a controller:

Expand All @@ -25,7 +25,7 @@ In a controller:

This extra is composed of 1 file:

- [array.rb](https://github.com/ddnexus/pagy-extras/blob/master/lib/pagy-extras/array.rb)
- [array.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/array.rb)

## Methods

Expand Down
10 changes: 5 additions & 5 deletions docs/pagy-extras/bootstrap.md → docs/extras/bootstrap.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ This extra adds nav helper and templates for Bootstrap pagination.

## Synopsys

See [pagy-extras](../pagy-extras.md) for general usage info.
See [extras](../extras.md) for general usage info.

Render the navigation links in some view...
with a fast helper:
Expand All @@ -24,10 +24,10 @@ or with a template:

This extra is composed of 4 files:

- [bootstrap.rb](https://github.com/ddnexus/pagy-extras/blob/master/lib/pagy-extras/bootstrap.rb)
- [nav_bootstrap.html.erb](https://github.com/ddnexus/pagy-extras/blob/master/lib/templates/nav_bootstrap.html.erb) (optional template)
- [nav_bootstrap.html.haml](https://github.com/ddnexus/pagy-extras/blob/master/lib/templates/nav_bootstrap.html.haml) (optional template)
- [nav_bootstrap.html.slim](https://github.com/ddnexus/pagy-extras/blob/master/lib/templates/nav_bootstrap.html.slim) (optional template)
- [bootstrap.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/bootstrap.rb)
- [nav_bootstrap.html.erb](https://github.com/ddnexus/pagy/blob/master/lib/templates/nav_bootstrap.html.erb) (optional template)
- [nav_bootstrap.html.haml](https://github.com/ddnexus/pagy/blob/master/lib/templates/nav_bootstrap.html.haml) (optional template)
- [nav_bootstrap.html.slim](https://github.com/ddnexus/pagy/blob/master/lib/templates/nav_bootstrap.html.slim) (optional template)

## Methods

Expand Down
10 changes: 5 additions & 5 deletions docs/pagy-extras/compact.md → docs/extras/compact.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,19 +13,19 @@ Here is an example (bootstrap style):

## Synopsys

See [pagy-extras](../pagy-extras.md) for general usage info.
See [extras](../extras.md) for general usage info.

In an initializer file:

```ruby
# in rails apps: add the assets-path
Rails.application.config.assets.paths << Pagy.root.join('pagy', 'extras')
Rails.application.config.assets.paths << Pagy.root.join('pagy', 'extras', 'javascripts')
```
In rails: add the javascript file to the application.js
```js
//= require pagy-compact
```
In non-rails apps: ensure the `pagy/extra/pagy-compact.js` script gets served with the page
In non-rails apps: ensure the `pagy/extras/javascripts/pagy-compact.js` script gets served with the page

Then use the responsive helper(s) in any view:

Expand All @@ -38,8 +38,8 @@ Then use the responsive helper(s) in any view:

This extra is composed of 2 small files:

- [compact.rb](https://github.com/ddnexus/pagy-extras/blob/master/lib/pagy-extras/compact.rb)
- [pagy-compact.js](https://github.com/ddnexus/pagy-extras/blob/master/lib/javascripts/pagy-compact.js)
- [compact.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagyextras/compact.rb)
- [pagy-compact.js](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/javascripts/pagy-compact.js)

## Methods

Expand Down
10 changes: 5 additions & 5 deletions docs/pagy-extras/responsive.md → docs/extras/responsive.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,20 +12,20 @@ Here is an example of how the same pagination nav might look like by resizing th

## Synopsys

See [pagy-extras](../pagy-extras.md) for general usage info.
See [extras](../extras.md) for general usage info.

```ruby
# set your default custom breakpoints (width/size pairs) globally (it can be overridden per pagy instance)
Pagy::VARS[:breakpoints] = {0 => [1,2,2,1], 450 => [3,4,4,3], 750 => [4,5,5,4]}

# in rails apps: add the assets-path
Rails.application.config.assets.paths << Pagy.extras_root.join('javascripts')
Rails.application.config.assets.paths << Pagy.root.join('pagy', 'extras', 'javascripts')
```
In rails: add the javascript file to the application.js
```js
//= require pagy-responsive
```
In non-rails apps: ensure the `pagy-extras/javascripts/pagy-responsive.js` script gets served with the page
In non-rails apps: ensure the `pagy/extras/javascripts/pagy-responsive.js` script gets served with the page

Then use the responsive helper(s) in any view:

Expand All @@ -38,8 +38,8 @@ Then use the responsive helper(s) in any view:

This extra is composed of 2 small files:

- [responsive.rb](https://github.com/ddnexus/pagy-extras/blob/master/lib/pagy-extras/responsive.rb)
- [pagy-responsive.js](https://github.com/ddnexus/pagy-extras/blob/master/lib/javascripts/pagy-responsive.js)
- [responsive.rb](https://github.com/ddnexus/pagy/blob/master/lib/pagy/extras/responsive.rb)
- [pagy-responsive.js](https://github.com/ddnexus/extras/blob/master/lib/pagy/extras/javascripts/pagy-responsive.js)

## Variables

Expand Down
Loading

0 comments on commit f764cc1

Please sign in to comment.