https://github.com/beam-community/scrivener_headers

Scrivener pagination with headers and web linking
https://github.com/beam-community/scrivener_headers

elixir-lang hex http-headers pagination pagination-headers scrivener

Last synced: about 2 months ago
JSON representation

Scrivener pagination with headers and web linking

• Host: GitHub
• URL: https://github.com/beam-community/scrivener_headers
• Owner: beam-community
• License: mit
• Created: 2016-03-09T16:10:39.000Z (over 8 years ago)
• Default Branch: master
• Last Pushed: 2022-03-27T06:07:43.000Z (about 2 years ago)
• Last Synced: 2024-04-19T05:51:11.257Z (about 2 months ago)
• Topics: elixir-lang, hex, http-headers, pagination, pagination-headers, scrivener
• Language: Elixir
• Size: 34.2 KB
• Stars: 50
• Watchers: 15
• Forks: 9
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • License: LICENSE.md
  • Codeowners: .github/CODEOWNERS

Lists

• awesome-elixir - scrivener_headers - Helpers for paginating API responses with Scrivener and HTTP headers. (Framework Components)

README

        
# Scrivener.Headers

[![Continuous Integration](https://github.com/beam-community/scrivener_headers/actions/workflows/ci.yml/badge.svg)](https://github.com/beam-community/scrivener_headers/actions/workflows/ci.yml)

[![Module Version](https://img.shields.io/hexpm/v/scrivener_headers.svg)](https://hex.pm/packages/scrivener_headers)

[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/scrivener_headers/)

[![Total Download](https://img.shields.io/hexpm/dt/scrivener_headers.svg)](https://hex.pm/packages/scrivener_headers)

[![License](https://img.shields.io/hexpm/l/scrivener_headers.svg)](https://github.com/beam-community/scrivener_headers/blob/master/LICENSE.md)

[![Last Updated](https://img.shields.io/github/last-commit/beam-community/scrivener_headers.svg)](https://github.com/beam-community/scrivener_headers/commits/master)

Helpers for paginating API responses with [Scrivener](https://github.com/drewolson/scrivener) and HTTP headers.  Implements [RFC-5988](https://tools.ietf.org/html/rfc5988), the proposed standard for Web linking.

## Setup

Add `:scrivener_headers` to `mix.exs`:

```elixir

defp deps do

  [

    # ...

    {:scrivener_headers, "~> 3.2"}

    # ...

  ]

end

```

## Usage

With `Scrivener.Headers.paginate/2` we can easily set our pagination headers:

```elixir

def index(conn, params) do

  page = MyApp.Person

         |> where([p], p.age > 30)

         |> order_by([p], desc: p.age)

         |> preload(:friends)

         |> MyApp.Repo.paginate(params)

  conn

  |> Scrivener.Headers.paginate(page)

  |> render("index.json", people: page.entries)

end

```

With `curl --include` we can see our new headers:

```shell

$ curl --include 'https://localhost:4000/people?page=5'

HTTP/1.1 200 OK

Link: ; rel="first",

  ; rel="last",

  ; rel="next",

  ; rel="prev"

Total: 300

Per-Page: 10

```

### Using Custom Header Names

Override any number of pagination header names by passing opts with a `:header_keys` keyword list like so:

```elixir

Screenever.Headers.paginate(page,

  header_keys: [

    total: "total",

    link: "link",

    per_page: "per-page",

    total_pages: "total-pages",

    page_number: "page-number"

  ]

)

```

## Contributing

Contributions of all types are welcomed and encouraged.  Please

make appropriate use of [Issues][issues] and [Pull Requests][pulls].  All code

should have test coverage.

[issues]: https://github.com/beam-community/scrivener_headers/issues

[pulls]: https://github.com/beam-community/scrivener_headers/pulls

## Copyright and License

Copyright (c) 2016 Sean Callan

Released under the [MIT License](./LICENSE.md).