Powered by

# Javascript Setup

# How does it work?

All the pagy*_js helpers render their component on the client side. The helper methods render just a minimal HTML tag that contains a data-pagy attribute.

Your app should serve or bundle a small javascript file and run the Pagy.init() function that will take care of converting the the data-pagy attribute data and make it work in the browser.

# 1. Pick a Javascript File

  • ES6 module to use with webpacker, esbuild, parcel, etc.

pagy.mjs
pagy.mjs 3.85KB 

module_path = Pagy.root.join('javascripts', 'pagy.mjs')

pagy.d.ts
pagy.d.ts 106B 

types_path = Pagy.root.join('javascripts', 'pagy.d.ts')
  • It's an IIFE file meant to be loaded as is, directly in your production pages and without any further processing
  • Minified (~2k) and polyfilled to work also with quite old browsers

pagy.min.js
pagy.min.js 2.04KB 

script_path = Pagy.root.join('javascripts', 'pagy.min.js')

pagy.min.js.map
pagy.min.js.map 8.03KB 

script_path = Pagy.root.join('javascripts', 'pagy.min.js.map')

# 2. Configure

Depending on your environment you have a few ways of configuring your app:

# Rails with assets pipeline

In older versions of Rails, you can configure the app to look into the installed pagy gem javascript files:

pagy.rb (initializer)
Rails.application.config.assets.paths << Pagy.root.join('javascripts') # uncomment.
manifest.js (or "application.js" for old sprocket sprockets):
//= require pagy
pagy.rb (initializer)
Rails.application.config.assets.paths << Pagy.root.join('javascripts') #uncomment
app/assets/config/manifest.js
//= link pagy.mjs
config/importmap.rb
pin 'pagy'
pagy.rb (initializer)
Rails.application.config.assets.paths << Pagy.root.join('javascripts')
application.html.erb
<%= javascript_include_tag "pagy" %>

# Builders

In order to bundle the pagy.mjs your builder has to find it either with a link or local copy, or by looking into the pagy javascript path:

You can create a symlink or a copy of the pagy.mjs file (available in the pagy gem) into an app compiled dir and use it as a regular app file. That way any builder will pick it up. For example:

config/initializers/pagy.rb
# Create/refresh the `app/javascript/pagy.mjs` symlink/copy every time 
# the app restarts (unless in production), ensuring syncing when pagy is updated.
# Replace the FileUtils.ln_sf with FileUtils.cp if your OS doesn't support file linking. 
FileUtils.ln_sf(Pagy.root.join('javascripts', 'pagy.mjs'), Rails.root.join('app', 'javascript')) \
unless Rails.env.production?

Prepend the NODE_PATH environment variable to the scripts.build command:

package.json
{
    "build": "NODE_PATH=\"$(bundle show 'pagy')/javascripts\" <your original command>"
}

Prepend the NODE_PATH environment variable to the scripts.build command:

package.json
{
    "build": "NODE_PATH=\"$(bundle show 'pagy')/javascripts\" <your original command>"
}
webpack.config.js
module.exports = {
  ...,                          // your original config
  resolve: {                    // add resolve.modules
    modules: [
      "node_modules",           // node_modules dir
      process.env.PAGY_PATH     // pagy dir
    ]
  }
}

# Non-Rails apps

  • Just ensure Pagy.root.join('javascripts', 'pagy.js') is served with the page.

# 3. Initialize Pagy

After the helper is loaded you have to initialize Pagy to make it work:
pagy_initializer_controller.js
import {Controller} from "@hotwired/stimulus"
import Pagy from "pagy"  // if using sprockets, you can remove above line, but make sure you have the appropriate directive if your manifest.js file.

export default class extends Controller {
  connect() {
    Pagy.init(this.element)
  }
}
View
<div data-controller="pagy-initializer">
  <%== pagy_nav_js(@pagy) %>
</div>

Import and use the pagy module:

app/javascript/application.js
import Pagy from "pagy";

window.addEventListener("turbo:load", Pagy.init);
 
// if you choose pagy.mjs 
import Pagy from "pagy"

// plain javascript
window.addEventListener("load", Pagy.init)

// Turbo
window.addEventListener("turbo:load", Pagy.init)

// Turbolinks
window.addEventListener("turbolinks:load", Pagy.init)

// custom listener
window.addEventListener(yourEventListener, Pagy.init)

# Caveats