Server-side data with Ruby on Rails

This tutorial shows how to wire Handsontable’s dataProvider plugin to a Ruby on Rails API-only backend. The backend handles pagination, sorting, and filtering on the server. The frontend displays results and sends every edit back to the API.

View full example on GitHub

Difficulty: Intermediate
Time: ~30 minutes
Backend: Ruby 3.2+, Rails 7.1+, kaminari for pagination, rack-cors for CORS

What you’ll build

An Order Management grid that:

Loads orders page by page from a Rails API
Sorts orders by any column on the server
Filters orders by column value on the server
Creates, updates, and deletes rows via dedicated collection endpoints
Handles Rails’ default snake_case payloads without mismatching Handsontable column keys

Before you begin

Install Ruby and Rails (see the Rails installation guide), then generate a new API-only project:

1
rails new orders-api --api
2
cd orders-api

Install the JavaScript dependency:

1
npm install handsontable

Step 1 — Add the Ruby gems

Add kaminari (pagination) and rack-cors (cross-origin requests) to the Gemfile:

1
# Gemfile
2
gem "kaminari"
3
gem "rack-cors"

Install them:

1
bundle install

Why these two gems?

kaminari gives you a .page(n).per(size) query method on any ActiveRecord relation. It also exposes total_count, which you return to Handsontable as totalRows.
rack-cors lets the Rails API accept requests from a different origin than the frontend dev server. Without it, the browser blocks the requests before Rails sees them.

Step 2 — Generate the `Order` model

Use the generator to create the model, the migration, and a matching controller file:

1
rails generate model Order order_number:string customer:string status:string total:decimal
2
rails db:migrate

The generated migration adds id and created_at / updated_at columns automatically. The final schema has the six fields referenced throughout this recipe: id, order_number, customer, status, total, and created_at.

What’s happening:

Rails’ decimal type stores currency values without floating-point rounding. For production, specify precision and scale: total:decimal{10,2}.
The primary key id is auto-incremented by the database. It becomes the rowId value on the Handsontable side.
created_at is filled automatically by ActiveRecord on insert.

See server/order.rb for a minimal model with validations and a status enum.

Step 3 — Seed the database

Add realistic seed data in db/seeds.rb (see server/seeds.rb in this recipe), then run:

1
rails db:seed

The seed script inserts 50 orders across realistic statuses (pending, paid, shipped, delivered, cancelled). It checks whether data already exists, so running it twice does not duplicate rows.

Step 4 — Configure the routes

Open config/routes.rb and register the orders resource inside an api namespace:

1
Rails.application.routes.draw do
2
  namespace :api do
3
    resources :orders, only: [:index] do
4
      collection do
5
        post   :create_rows
6
        patch  :update_rows
7
        delete :remove_rows
8
      end
9
    end
10
  end
11
end

What’s happening:

namespace :api prefixes all routes with /api and scopes the controller under Api::OrdersController. This keeps the API separate from any server-rendered views you might add later.
only: [:index] restricts the generated RESTful routes to GET /api/orders — standard per-resource create/update/destroy routes are replaced by the batch collection routes below.
collection do ... end registers three custom routes at the collection URL (/api/orders/...) instead of the detail URL (/api/orders/:id). Handsontable’s dataProvider sends every mutation as an array in a single request, so batch endpoints are what you want.

The three resulting routes are:

Method	URL	Controller action
`POST`	`/api/orders/create_rows`	`create_rows`
`PATCH`	`/api/orders/update_rows`	`update_rows`
`DELETE`	`/api/orders/remove_rows`	`remove_rows`

Step 5 — Configure CORS

Create config/initializers/cors.rb:

1
Rails.application.config.middleware.insert_before 0, Rack::Cors do
2
  allow do
3
    origins "http://localhost:5173", "http://localhost:3000"
4

5
    resource "/api/*",
6
      headers: :any,
7
      methods: [:get, :post, :patch, :put, :delete, :options],
8
      expose:  ["Content-Type"]
9
  end
10
end

What’s happening:

insert_before 0 puts the middleware at the very front of the stack so it runs before Rails’ routing.
origins lists the URLs that are allowed to call the API. Replace these with your production domain before deploying.
resource "/api/*" scopes the CORS rule to the API endpoints only.
methods must include :options for browsers to complete preflight requests on non-simple methods (PATCH, DELETE).

Production note: Never use origins "*" in production. Pin the list to the exact domains that own your Handsontable deployment.

Step 6 — Decide on the case convention

Rails emits snake_case JSON by default (order_number, created_at). Handsontable’s column data keys must match whatever the server returns.

You have two practical options:

Option A — Keep snake_case (used in this recipe). Set data: 'order_number' on the matching Handsontable column. No transformation on either side.

Option B — Emit camelCase from Rails. Override serialization globally:

1
class ActiveRecord::Base
2
  def as_json(options = {})
3
    super(options).deep_transform_keys { |key| key.to_s.camelize(:lower) }
4
  end
5
end

Then use data: 'orderNumber' on the frontend and also translate the sort_prop and filters[][prop] values back to snake_case in the controller.

Why this matters: mixing conventions — Rails returning order_number while Handsontable columns declare data: 'orderNumber' — silently breaks pagination, sorting, and filtering. The grid renders empty cells and the server receives unknown column names. Pick one convention and stick to it.

The rest of this recipe uses Option A (snake_case everywhere).

Step 7 — Build the controller

Create app/controllers/api/orders_controller.rb. This single file implements paginated index, server-side sort and filter, and the three batch CRUD actions.

Whitelist sortable columns

Sort inputs that flow into order() reach the SQL ORDER BY clause. Treating them as raw strings is an SQL-injection risk. Whitelist them once at the top of the class:

1
SORTABLE_COLUMNS = %w[order_number customer status total created_at].freeze

`index` — paginated list with sort and filter

1
def index
2
  orders = Order.all
3
  orders = apply_filters(orders)
4
  orders = apply_sort(orders)
5
  orders = orders.page(params[:page]).per(params[:page_size] || 10)
6

7
  render json: { rows: orders.as_json, total_rows: orders.total_count }
8
end

What’s happening:

Start from Order.all. This builds a base ActiveRecord relation without hitting the database yet.
apply_filters adds .where(...) clauses from the parsed Handsontable filter list.
apply_sort adds an .order(...) clause if the request includes a whitelisted sort_prop.
kaminari adds LIMIT and OFFSET via .page(n).per(size). The query is still not executed.
as_json triggers the query and serializes results. total_count issues a separate SELECT COUNT(*) that Handsontable uses to size the paginator.

The response shape is exactly what dataProvider expects: { rows, total_rows }. The frontend maps total_rows to totalRows (see Step 9).

Sort helper

1
def apply_sort(scope)
2
  prop  = params[:sort_prop]
3
  order = params[:sort_order] == "desc" ? :desc : :asc
4

5
  return scope unless SORTABLE_COLUMNS.include?(prop)
6

7
  scope.order(prop => order)
8
end

What’s happening:

params[:sort_prop] comes directly from the frontend’s sort_prop= query param (see Step 9).
SORTABLE_COLUMNS.include?(prop) is the whitelist check. Any column not on the list is silently ignored — no SQL is generated for it.
scope.order(prop => order) uses the hash form of .order(), which ActiveRecord quotes safely.
params[:sort_order] falls back to :asc unless the client explicitly sends desc. This prevents arbitrary SQL fragments (for example, created_at; DROP TABLE orders) from reaching the database.

Filter helper

Handsontable sends filters as an indexed structure:

1
?filters[0][prop]=status&filters[0][value]=shipped&filters[0][condition]=eq
2
?filters[1][prop]=total&filters[1][value]=100&filters[1][condition]=gte

Rails parses bracket-indexed params into a nested hash automatically. Parse each condition and chain .where calls:

1
def apply_filters(scope)
2
  filters = params[:filters]
3
  return scope if filters.blank?
4

5
  Array(filters.values).each do |filter|
6
    prop      = filter[:prop]
7
    value     = filter[:value]
8
    condition = filter[:condition].presence || "contains"
9

10
    next unless SORTABLE_COLUMNS.include?(prop)
11

12
    case condition
13
    when "contains"     then scope = scope.where("#{prop} ILIKE ?", "%#{value}%")
14
    when "not_contains" then scope = scope.where.not("#{prop} ILIKE ?", "%#{value}%")
15
    when "eq"           then scope = scope.where(prop => value)
16
    when "neq"          then scope = scope.where.not(prop => value)
17
    when "begins_with"  then scope = scope.where("#{prop} ILIKE ?", "#{value}%")
18
    when "ends_with"    then scope = scope.where("#{prop} ILIKE ?", "%#{value}")
19
    when "gt"           then scope = scope.where("#{prop} > ?", value)
20
    when "gte"          then scope = scope.where("#{prop} >= ?", value)
21
    when "lt"           then scope = scope.where("#{prop} < ?", value)
22
    when "lte"          then scope = scope.where("#{prop} <= ?", value)
23
    end
24
  end
25

26
  scope
27
end

What’s happening:

The SORTABLE_COLUMNS check is reused as a filter whitelist. Column names that reach the raw SQL fragment (ILIKE, >=, etc.) must be validated against a fixed list.
ILIKE is PostgreSQL-specific. On SQLite or MySQL, use LIKE with a COLLATE clause or case-normalize the input.
Each condition rebinds scope, so multiple filters combine with AND. dataProvider does not send OR groups by default.

Batch CRUD actions

1
def create_rows
2
  payload = params.permit!.to_h
3

4
  rows = Array(payload[:rows]).map do |row|
5
    Order.create!(row.slice(*Order.column_names - %w[id created_at updated_at]))
6
  end
7

8
  render json: { rows: rows.as_json }, status: :created
9
end
10

11
def update_rows
12
  updated = Array(params[:rows]).map do |row|
13
    record  = Order.find(row[:id])
14
    changes = row[:changes].to_unsafe_h.slice(*Order.column_names)
15
    record.update!(changes)
16
    record
17
  end
18

19
  render json: { rows: updated.as_json }
20
end
21

22
def remove_rows
23
  ids = Array(params[:row_ids])
24
  Order.where(id: ids).delete_all
25
  head :no_content
26
end

What’s happening:

create_rows — receives { rows: [...] }. Each row is inserted with create!, which raises on validation errors. column_names - ['id', 'created_at', 'updated_at'] blocks the client from setting system-managed fields. Status 201 tells dataProvider the rows were created.
update_rows — receives { rows: [{ id, changes: { ... } }] }. changes.slice(*Order.column_names) drops any unknown keys so stray fields never reach the ORM. Returning the updated rows lets dataProvider reconcile its internal row map.
remove_rows — receives { row_ids: [1, 2, 3] }. delete_all issues a single DELETE ... WHERE id IN (...) statement, which is faster than deleting each row one by one. Status 204 signals a successful delete with no response body.

The full controller file lives at server/orders_controller.rb.

Step 8 — CSRF in API mode

ApplicationController in API mode inherits from ActionController::API, which does not include RequestForgeryProtection. That means CSRF verification is off by default for this project, and fetch() requests from the browser do not need an X-CSRF-Token header.

When does CSRF matter?

If you mount the Rails API under the same origin as a classic Rails app that uses cookie-based sessions, the classic app enforces CSRF protection — your fetch calls will need the token.
Token-based auth (for example, a Authorization: Bearer header) does not require CSRF protection because the browser never attaches the token automatically.

This recipe assumes a stateless API and an Authorization header (or no auth) in production. Add protect_from_forgery with: :null_session inside the controller only if you re-enable session-based auth.

Step 9 — Build the request URL on the frontend

Handsontable’s dataProvider calls fetchRows with { page, pageSize, sort, filters }. Map those to the Rails parameter names:

1
function buildUrl(base, { page, pageSize, sort, filters }) {
2
  const params = new URLSearchParams();
3

4
  params.set('page', page);
5
  params.set('page_size', pageSize);
6

7
  if (sort?.prop) {
8
    params.set('sort_prop', sort.prop);
9
    params.set('sort_order', sort.order ?? 'asc');
10
  }
11

12
  if (filters?.length) {
13
    filters.forEach(({ prop, value, condition }, i) => {
14
      params.set(`filters[${i}][prop]`, prop);
15
      params.set(`filters[${i}][value]`, value);
16
      params.set(`filters[${i}][condition]`, condition);
17
    });
18
  }
19

20
  return `${base}?${params.toString()}`;
21
}

What’s happening:

pageSize is converted to page_size because Rails and kaminari use snake_case parameter names.
sort is split into two flat params, sort_prop and sort_order. The controller’s apply_sort reads them directly.
Each filter condition becomes a filters[N][prop], filters[N][value], filters[N][condition] triplet. Rails converts the bracket notation to a nested hash automatically.

Step 10 — Initialize Handsontable

Wire everything into dataProvider:

1
const hot = new Handsontable(container, {
2
  dataProvider: {
3
    rowId: 'id',
4

5
    fetchRows: async ({ page, pageSize, sort, filters }, { signal }) => {
6
      const url = buildUrl('http://localhost:3000/api/orders', {
7
        page, pageSize, sort, filters,
8
      });
9
      const res = await fetch(url, { signal });
10

11
      if (!res.ok) throw new Error(`Fetch failed: ${res.status}`);
12

13
      const json = await res.json();
14

15
      // Rails returns snake_case; dataProvider expects camelCase for totalRows.
16
      return { rows: json.rows, totalRows: json.total_rows };
17
    },
18

19
    onRowsCreate: async (rows) => {
20
      const res = await fetch('http://localhost:3000/api/orders/create_rows', {
21
        method: 'POST',
22
        headers: { 'Content-Type': 'application/json' },
23
        body: JSON.stringify({ rows }),
24
      });
25
      const json = await res.json();
26

27
      return json.rows; // dataProvider updates its row map with server-assigned ids
28
    },
29

30
    onRowsUpdate: async (rows) => {
31
      await fetch('http://localhost:3000/api/orders/update_rows', {
32
        method: 'PATCH',
33
        headers: { 'Content-Type': 'application/json' },
34
        body: JSON.stringify({ rows: rows.map((r) => ({ id: r.id, changes: r })) }),
35
      });
36
    },
37

38
    onRowsRemove: async (rowIds) => {
39
      await fetch('http://localhost:3000/api/orders/remove_rows', {
40
        method: 'DELETE',
41
        headers: { 'Content-Type': 'application/json' },
42
        body: JSON.stringify({ row_ids: rowIds }),
43
      });
44
    },
45
  },
46

47
  pagination:     { pageSize: 10 },
48
  columnSorting:  true,
49
  filters:        true,
50
  dropdownMenu:   ['filter_by_condition', 'filter_action_bar'],
51
  emptyDataState: true,
52
  notification:   true,
53

54
  colHeaders: ['Order #', 'Customer', 'Status', 'Total', 'Created'],
55
  columns: [
56
    { data: 'order_number', type: 'text' },
57
    { data: 'customer',     type: 'text' },
58
    { data: 'status',       type: 'text' },
59
    { data: 'total',        type: 'numeric', numericFormat: { pattern: '$0,0.00' } },
60
    { data: 'created_at',   type: 'date', dateFormat: 'YYYY-MM-DD', readOnly: true },
61
  ],
62

63
  rowHeaders: true,
64
  licenseKey: 'non-commercial-and-evaluation',
65
});

Key options explained:

Option	What it does
`rowId: 'id'`	Tells `dataProvider` which field uniquely identifies a row. Must match the Rails primary key name.
`{ signal }` in `fetchRows`	Pass the `AbortSignal` to `fetch()` so in-flight requests are cancelled when the user sorts or filters before the previous response arrives.
Returning `json.rows` from `onRowsCreate`	Lets `dataProvider` replace client-side placeholder ids with the ids assigned by Rails.
`pagination: { pageSize: 10 }`	Enables the pagination toolbar. `dataProvider` passes the current page and size to `fetchRows` automatically.
`columnSorting: true`	Enables column header click-to-sort. The sort state is passed to `fetchRows`.
`filters: true` with `dropdownMenu`	Renders the column filter UI. Active conditions are passed to `fetchRows`.
`emptyDataState: true`	Shows a friendly illustration when the API returns zero rows (for example, when a filter matches nothing).
`notification: true`	Shows automatic error toasts when `fetchRows` or a mutation callback throws. Fetch failures include a Refetch action.

How it works — Complete flow

Initial load: dataProvider calls fetchRows({ page: 1, pageSize: 10 }). Rails returns the first 10 orders and the total row count.
User clicks a column header: columnSorting updates its sort state and dataProvider calls fetchRows again with sort: { prop: 'total', order: 'desc' }. The controller’s apply_sort checks SORTABLE_COLUMNS, then issues order(total: :desc).
User applies a column filter: Filters updates its condition list and dataProvider calls fetchRows with the filters array. The controller’s apply_filters parses the indexed hash and chains .where calls.
User navigates to page 2: dataProvider calls fetchRows({ page: 2, pageSize: 10, ... }). kaminari returns rows 11-20.
User edits a cell: dataProvider collects the changed cells for each row and calls onRowsUpdate with [{ id: 7, total: 142.5 }]. The frontend wraps each row in { id, changes } before sending. update_rows applies the change.
User adds a row: dataProvider calls onRowsCreate. create_rows inserts the row and returns it with the database-assigned id. dataProvider updates its row map so subsequent edits target the correct id.
User deletes rows: dataProvider calls onRowsRemove([3, 7, 14]). remove_rows issues a single DELETE ... WHERE id IN (3, 7, 14).

What you learned

Rails API mode (rails new ... --api) skips middleware you do not need for a JSON API and leaves CSRF protection off by default.
kaminari adds .page(n).per(size) plus .total_count to any ActiveRecord relation — exactly what you need to build a { rows, total_rows } response.
Validate every column name that reaches order() or a raw SQL fragment against a fixed whitelist. Never trust params[:sort_prop] or params[:filters] directly.
Pick one case convention (snake_case or camelCase) for the whole round trip. Mixing conventions silently breaks pagination, sorting, and filtering.
Translate sort: { prop, order } on the frontend to flat sort_prop / sort_order query params. This matches Rails’ parameter-naming conventions and keeps the controller focused.
Handsontable’s indexed filters[N][...] format parses directly into Rails’ nested hash params — no custom decoder is required.
Use rack-cors to allow requests from the frontend dev server. Place the middleware before 0 so it runs before Rails’ routing.

Server-side data with Ruby on Rails

What you’ll build

Before you begin

Step 1 — Add the Ruby gems

Step 2 — Generate the Order model

Step 3 — Seed the database

Step 4 — Configure the routes

Step 5 — Configure CORS

Step 6 — Decide on the case convention

Step 7 — Build the controller

Whitelist sortable columns

index — paginated list with sort and filter

Sort helper

Filter helper

Batch CRUD actions

Step 8 — CSRF in API mode

Step 9 — Build the request URL on the frontend

Step 10 — Initialize Handsontable

How it works — Complete flow

What you learned

Next steps

Step 2 — Generate the `Order` model

`index` — paginated list with sort and filter