Skip to content

Commit

Permalink
docs markdown normalization and README editing
Browse files Browse the repository at this point in the history
  • Loading branch information
@ddnexus
ddnexus committed May 31, 2018
1 parent 11fbc49 commit 5a5178b
Show file tree
Hide file tree
Showing 14 changed files with 145 additions and 141 deletions.
35 changes: 15 additions & 20 deletions README.md
View file
Expand Up @@ -4,31 +4,31 @@

Pagy is the ultimate pagination gem that outperforms the others in each and every benchmark and comparison.

### Benchmarks
## Benchmarks

The best way to quickly get an idea about its features is comparing it to the other well known gems.

The values shown in the charts below have been recorded while each gem was producing the exact same output: same environment conditions, same task, just different gems _(see the complete [Gems Comparison](http://ddnexus.github.io/pagination-comparison/gems.html))_

#### Pagy is a lot faster
### Faster

![IPS Chart](docs/assets/images/ips-chart.png)

#### Pagy uses a lot less memory
### Less Memory

![Memory Chart](docs/assets/images/memory-chart.png)

#### Pagy is a lot simpler
### Simpler

![Objects Chart](docs/assets/images/objects-chart.png)

#### Pagy is a lot more efficient
### More Efficient

![Efficiency Table](docs/assets/images/efficiency-table.png)

_The [IPS/Kb ratio](http://ddnexus.github.io/pagination-comparison/gems.html#efficiency-ratio) is calculated out of speed (IPS) and Memory (Kb): it shows how well each gem uses any Kb of memory it allocates/consumes._

#### Pagy does not suffer the typical limitations of the other gems
### Unlike the other gems

- it works with collections/scopes that already used `limit` and `offset`
- it works with both helpers or templates (your choice)
Expand All @@ -37,15 +37,15 @@ _The [IPS/Kb ratio](http://ddnexus.github.io/pagination-comparison/gems.html#eff

## Features

### Straightforward code
### Straightforward Code

- Pagy is just ~100 lines of simple ruby, organized in 3 flat modules very easy to understand and use
- it produces its own HTML, URLs, pluralization and interpolation with its own specialized and fast code
- 100% of its methods are public API, accessible and overridable **right where you use them** (no need of monkey patching or subclassing)

### Totally agnostic
### Totally Agnostic

- it doesn't need to know anything about your models, ORM or Storage, so it doesn't add any code to them
- it doesn't need to know anything about your models, ORM or storage, so it doesn't add any code to them
- it works with all kinds of collections, even pre-paginated, records, Arrays, JSON data... and just whatever you can count
- it works with all Rack frameworks (Rails, Sinatra, Padrino, ecc.) out of the box
- it works with any possible non-Rack environment by just overriding one or two two-line methods
Expand Down Expand Up @@ -76,35 +76,29 @@ Or - if you prefer - render the navigation links with a template:

Use the official extras, or write your own in just a few lines.

### Frontend Extras

#### Bootstrap Extra
### Bootstrap Extra

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

#### Responsive Extra
### 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/extras/responsive))

#### Compact Extra
### 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/extras/compact))

### Backend Extras

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

#### Array Extra
### Array Extra

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

## Chat Support and Feedback

Expand All @@ -116,6 +110,7 @@ Paginate arrays effiently avoiding expensive array-wrapping and wihout overridin
- [Gems Comparison](https://ddnexus.github.io/pagination-comparison/gems.html)
- [Benchmarks and Memory Profiles Source](http://github.com/ddnexus/pagination-comparison)
- [Changelog](https://github.com/ddnexus/pagy/blob/master/CHANGELOG.md)
- [Contributors](https://github.com/ddnexus/pagy/graphs/contributors)

## Help Wanted

Expand Down
3 changes: 1 addition & 2 deletions docs/api.md
View file
@@ -1,15 +1,14 @@
---
title: API
---

# API

[![Gem Version](https://badge.fury.io/rb/pagy.svg)](https://badge.fury.io/rb/pagy)

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) |
13 changes: 7 additions & 6 deletions docs/api/backend.md
View file
@@ -1,7 +1,6 @@
---
title: Pagy::Backend
---

# 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))_
Expand All @@ -10,15 +9,13 @@ You can extend this module with a few _specific_ pagination methods, very conven

__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.



## Synopsys

```ruby
# in your controller
include Pagy::Backend

# optional overriding of some sub-method
# optional overriding of some sub-method
def pagy_get_vars(collection, vars)
#...
end
Expand All @@ -35,18 +32,20 @@ All the methods in this module are prefixed with the `"pagy_"` string, to avoid

Please, keep in mind that overriding any method is very easy with pagy. Indeed you can do it right where you are using it: no need of monkey-patching or subclassing or perform any tricky gymnic.


### pagy(collection, vars=nil)

This is the main method of this module. It takes a collection object (e.g. a scope), and an optional hash of variables (passed to the `Pagy.new` method) and returns the `Pagy` instance and the page of records. For example:

```ruby
@pagy, @records = pagy(Product.my_scope, some_option: 'get merged in the pagy object')
```

The built-in `pagy` method is designed to be easy to customize by overriding any of the two sub-methods that it calls internally. You can independently change the default variables (`pagy_get_variables`) and/or the default page of items from the collection `pagy_get_items`).

If you need to use multiple different types of collections in the same app or action, you may want to define some alternative and self contained custom `pagy` method.

For example: here is a `pagy` method that doesn't call any sub-method, that may be enough for your app:

```ruby
def pagy_custom(collection, vars={})
pagy = Pagy.new(count: collection.count, page: params[:page], **vars)
Expand All @@ -68,13 +67,13 @@ def pagy_get_vars(collection, vars)
page: params[vars[:page_param]||VARS[:page_param]] }.merge!(vars)
end
```

Override it if you need to add or change some variable. For example you may want to add the `:item_path` or the `:item_name` to customize the `pagy_info` output, or even cache the `count`.

_IMPORTANT_: `:count` and `:page` are the only 2 required pagy core variables, so be careful not to remove them from the returned hash.

See also the [How To](../how-to.md) wiki page for some usage example.


### pagy_get_items(collection, pagy)

Sub-method called only by the `pagy` method, it returns the page items (i.e. the records belonging to the current page).
Expand All @@ -86,11 +85,13 @@ def pagy_get_items(collection, pagy)
collection.offset(pagy.offset).limit(pagy.items)
end
```

Override it if the extraction of the items from your collection works in a different way. For example, if you need to paginate an array:

```ruby
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](../extras/array.md).
30 changes: 10 additions & 20 deletions docs/api/frontend.md
View file
@@ -1,7 +1,6 @@
---
title: Pagy::Frontend
---

# 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))_
Expand All @@ -19,6 +18,7 @@ def pagy_get_params(params)
params.except(:anything, :not, :useful).merge!(something: 'more useful')
end
```

use some of its method in some view:

```erb
Expand All @@ -32,7 +32,6 @@ All the methods in this module are prefixed with the `"pagy_"` string in order t

Please, keep in mind that overriding any method is very easy with pagy. Indeed you can do it right where you are using it: no need of monkey-patching or subclassing or tricky gymnic.


### pagy_nav(pagy)

This method takes the pagy object and returns the HTML string with the pagination links, which are wrapped in a `nav` tag and are ready to use in your view. For example:
Expand All @@ -45,7 +44,6 @@ The `nav.*` templates produce the same output, and can be used as an easier (but

See also [Using templates](../how-to.md#using-templates).


### pagy_info(pagy)

This method provides the info about the content of the current pagination. For example:
Expand All @@ -68,7 +66,6 @@ Displaying Products <b>476-500</b> of <b>1000</b> in total

See also [Using the pagy_info helper](../how-to.md#using-the-pagy_info-helper).


### pagy_url_for(page, page_param)

This method is called internally in order to produce the url of a page by passing it its number. For standard usage it works out of the box and you can just ignore it.
Expand All @@ -79,21 +76,18 @@ Notice: If you just need to remove or add some param, you may prefer to override

See also [Customizing the URL](../how-to.md#customizing-the-url).


### pagy_get_params(params)

Sub-method called by `pagy_url_for`: it is intended to be overridden when you need to add and/or remove some param from the page URLs. It receives the `params` hash complete with the `"page"` param and should return a possibly modified version of it.

See also [Customizing the params](../how-to.md#customizing-the-params).


### pagy_link_proc(pagy, link_extra='')

This method is called internally to get a very specialized and fast proc that produce the HTML links for the pages.

For standard usage you may just need to read [Customizing the link attributes](../how-to.md#customizing-the-link-attributes), for advanced usage see below.


### Advanced Usage

You need this section only if you are going to override a `pagy_nav*` helper or a template AND you need to customize the HTML attributes of the link tags.
Expand All @@ -105,12 +99,14 @@ You need this section only if you are going to override a `pagy_nav*` helper or
This method returns a specialized proc that you call to produce the page links. The reason it is a 2 steps process instead of a single method call is performance. Indeed the method calls the potentially expensive `pagy_url_for` only once and generates the proc, then calling the proc will just interpolates the strings passed to it.

Here is how you should use it: in your helper or template call the method to get the proc (just once):
```

```ruby
link = pagy_link_proc( pagy [, extra_attributes_string ])
```

Then call the `"link"` proc to get the links (multiple times):
```

```ruby
link.call( page_number [, text [, extra_attributes_string ]])
```

Expand All @@ -125,7 +121,7 @@ If you need to add some HTML attribute to the page links, you can pass some extr
# in an initializer file
Pagy::VARS[:link_extra] = 'data-remote="true"'
# in any view
link = pagy_link_proc(pagy)
link = pagy_link_proc(pagy)
link.call(2)
#=> <a href="...?page=2" data-remote="true">2</a>
```
Expand Down Expand Up @@ -156,13 +152,9 @@ If you need to add some HTML attribute to the page links, you can pass some extr
**WARNING**: we use only strings for performance, so the attribute strings get concatenated level after level, but not merged!
Be careful not to pass the same attribute at different levels multiple times. That would generate a duplicated HTML attribute which is illegal html (although handled by all mayor browsers by ignoring all the duplicates but the first)


### pagy_t(path, vars={})

This method is similar to the `I18n.t` and its equivalent rails `t` helper. It is called internally (from helpers and templates) in order to get the interpolated strings out of a YAML dictionary file.

_(see I18n below)_

This method is similar to the `I18n.t` and its equivalent rails `t` helper. It is called internally (from helpers and templates) in order to get the interpolated strings out of a YAML dictionary file. _(see I18n below)_

## I18n

Expand All @@ -178,12 +170,11 @@ If you need full blown I18n, you should require the `i18n` extra, which will ove

These are the `Pagy::I18N` globally accessible variables used to configure the pagy I18n implementation. They have no effect if you use the `i18n` extra (which uses the `I18n.t` method directly). They are not merged with the pagy object and used only at require time.

| Variable | Description | Default |
|-----------:|:---------------------------------------------------------------|:---------------------------------------------|
| `:file` | The I18n YAML file | `Pagy.root.join('locales', 'pagy.yml').to_s` |
| Variable | Description | Default |
| ---------- | -------------------------------------------------------------- | :------------------------------------------- |
| `:file` | The I18n YAML file | `Pagy.root.join('locales', 'pagy.yml').to_s` |
| `:plurals` | The proc that returns the plural key based on the passed count | `Proc` for English |


#### Pagy::I18N[:file]

This variable contains the path of the YAML file to load: set this variable only if you moved the file from `Pagy.root.join('locales', 'pagy.yml')`.
Expand All @@ -193,4 +184,3 @@ This variable contains the path of the YAML file to load: set this variable only
This variable controls the internal pluralization. If `pagy_t` is defined to use `I18n.t` it has no effect.

By default the variable is set to a proc that receives the `count` as the single argument and returns the plural type string (e.g. something like `'zero'`, `'one'` or `'other'`, depending on the count). You should customize it only for pluralization types different than English.

0 comments on commit 5a5178b

Please sign in to comment.