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

Docker and Docker Compose installed
Node.js 18 or later and npm installed

No local Ruby or Rails installation is required — the backend runs inside Docker.

Step 1 — Add the Ruby gems

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

1
# Gemfile -- relevant additions only.
2
# Add these two gems to the Gemfile generated by `rails new orders-api --api`,
3
# then run `bundle install`.
4

5
# Pagination helpers for ActiveRecord.
6
# Provides .page(n).per(size) on any relation and exposes .total_count,
7
# which this recipe returns to Handsontable as `total_rows`.
8
gem "kaminari"
9

10
# Cross-origin request support.
11
# Lets the Rails API accept requests from the frontend dev server
12
# (for example, Vite on http://localhost:5173).
13
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.

The server/order.rb file contains the minimal model with validations and a status enum:

1
# app/models/order.rb
2
#
3
# Order model for the Order Management demo grid.
4
#
5
# Fields match the Handsontable column definitions:
6
#   id           - auto-increment primary key, used as rowId on the frontend
7
#   order_number - short identifier shown in the first column
8
#   customer     - customer display name
9
#   status       - workflow state (pending, paid, shipped, delivered, cancelled)
10
#   total        - order total; DecimalField avoids floating-point rounding
11
#   created_at   - read-only timestamp filled on insert
12
class Order < ApplicationRecord
13
  STATUSES = %w[pending paid shipped delivered cancelled].freeze
14

15
  validates :order_number, presence: true, uniqueness: true
16
  validates :customer,     presence: true
17
  validates :status,       inclusion: { in: STATUSES }
18
  validates :total,        numericality: { greater_than_or_equal_to: 0 }
19

20
  # Keeps the initial grid display predictable before the user sorts.
21
  default_scope -> { order(created_at: :desc) }
22
end

Step 3 — Seed the database

Add realistic seed data in db/seeds.rb:

1
# db/seeds.rb
2
#
3
# Run with: rails db:seed
4
#
5
# Inserts 50 realistic order rows. The check against existing data makes
6
# the seed idempotent -- running it twice does not duplicate rows.
7

8
if Order.exists?
9
  puts "Database already seeded -- skipping."
10
else
11
  customers = [
12
    "Acme Corp", "Vertex Industries", "Harbor Goods", "Alpine Supply Co.",
13
    "Summit Partners", "Meridian Analytics", "Riverstone Ltd.", "Orbit Logistics",
14
    "Beacon Retail", "Northwind Traders"
15
  ]
16

17
  statuses = %w[pending paid shipped delivered cancelled]
18

19
  orders = 50.times.map do |i|
20
    {
21
      order_number: "ORD-#{(1000 + i).to_s.rjust(5, '0')}",
22
      customer:     customers.sample,
23
      status:       statuses.sample,
24
      total:        (50 + rand * 4950).round(2),
25
      created_at:   rand(120).days.ago
26
    }
27
  end
28

29
  Order.insert_all!(orders)
30

31
  puts "Seeded #{orders.size} orders."
32
end

Run it:

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
# config/routes.rb
2
#
3
# All routes are mounted under /api so the controller lives in Api::OrdersController
4
# and the JSON API is clearly separated from any server-rendered views.
5
#
6
# only: [:index] keeps the single built-in RESTful route (GET /api/orders)
7
# and replaces single-resource create/update/destroy with the batch endpoints
8
# below. Handsontable's dataProvider sends every mutation as an array in a
9
# single request, so batch endpoints fit its payload shape naturally.
10
Rails.application.routes.draw do
11
  namespace :api do
12
    resources :orders, only: [:index] do
13
      collection do
14
        # POST /api/orders/create_rows -- insert many rows in one request
15
        post :create_rows
16

17
        # PATCH /api/orders/update_rows -- update many rows in one request
18
        patch :update_rows
19

20
        # DELETE /api/orders/remove_rows -- delete many rows in one request
21
        delete :remove_rows
22
      end
23
    end
24
  end
25
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
# config/initializers/cors.rb
2
#
3
# Allow cross-origin requests from the frontend dev servers.
4
# Without rack-cors the browser blocks the preflight OPTIONS request
5
# before Rails ever sees it.
6
#
7
# insert_before 0 puts this middleware at the very front of the stack
8
# so it runs before Rails' routing can reject a cross-origin preflight.
9
#
10
# Replace the dev-server origins with your actual production domain(s)
11
# before deploying. Never use `origins "*"` with credentialed requests.
12
Rails.application.config.middleware.insert_before 0, Rack::Cors do
13
  allow do
14
    origins "http://localhost:5173", # Vite dev server
15
            "http://localhost:3000"  # Create React App / Next.js dev server
16

17
    resource "/api/*",
18
      headers: :any,
19
      methods: [:get, :post, :patch, :put, :delete, :options],
20
      expose:  ["Content-Type"]
21

22
    # If the frontend sends credentials (cookies, Authorization headers),
23
    # also set `credentials: true` here and pin `origins` to exact URLs --
24
    # wildcards are not allowed with credentialed requests.
25
  end
26
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:

1
# app/controllers/api/orders_controller.rb
2
#
3
# API controller providing paginated, sortable, and filterable order data,
4
# plus three batch CRUD actions that match Handsontable's dataProvider
5
# payload shape.
6
#
7
# The standard RESTful routes would operate on single resources at a time.
8
# Handsontable sends all row mutations as arrays, so we expose dedicated
9
# collection endpoints: create_rows / update_rows / remove_rows.
10
module Api
11
  class OrdersController < ApplicationController
12
    # Whitelist of columns that are allowed to appear in `order()` and
13
    # raw SQL fragments. Values that reach these positions are not quoted
14
    # as bind parameters, so anything that is not validated is an
15
    # SQL-injection risk. Keep this list tight.
16
    SORTABLE_COLUMNS = %w[order_number customer status total created_at].freeze
17

18
    # ------------------------------------------------------------------
19
    # GET /api/orders
20
    #
21
    # Accepts:
22
    #   page, page_size        -- pagination
23
    #   sort_prop, sort_order  -- single-column sort
24
    #   filters[N][prop|value|condition] -- column filters
25
    #
26
    # Returns:
27
    #   { rows: [...], total_rows: 123 }
28
    #
29
    # The JSON shape is converted to { rows, totalRows } on the frontend
30
    # (or you can override serialization globally to emit camelCase --
31
    # see the recipe for the trade-offs).
32
    # ------------------------------------------------------------------
33
    def index
34
      scope = Order.all
35
      scope = apply_filters(scope)
36
      scope = apply_sort(scope)
37
      scope = scope.page(params[:page]).per(params[:page_size] || 10)
38

39
      render json: {
40
        rows:       scope.as_json,
41
        total_rows: scope.total_count
42
      }
43
    end
44

45
    # ------------------------------------------------------------------
46
    # POST /api/orders/create_rows
47
    #
48
    # Accepts the onRowsCreate payload: { rows: [ { ... }, ... ] }.
49
    # Returns the created rows with their database-assigned ids so
50
    # dataProvider can replace client-side placeholders in its row map.
51
    # ------------------------------------------------------------------
52
    def create_rows
53
      payload = Array(params[:rows])
54
      allowed = Order.column_names - %w[id created_at updated_at]
55

56
      rows = Order.transaction do
57
        payload.map do |row|
58
          Order.create!(row.to_unsafe_h.slice(*allowed))
59
        end
60
      end
61

62
      render json: { rows: rows.as_json }, status: :created
63
    rescue ActiveRecord::RecordInvalid => e
64
      render json: { error: e.message }, status: :unprocessable_entity
65
    end
66

67
    # ------------------------------------------------------------------
68
    # PATCH /api/orders/update_rows
69
    #
70
    # Accepts { rows: [ { id, changes: { ... } }, ... ] }.
71
    # `changes` only contains the fields that the user edited.
72
    # ------------------------------------------------------------------
73
    def update_rows
74
      payload = Array(params[:rows])
75
      allowed = Order.column_names - %w[id created_at updated_at]
76

77
      updated = Order.transaction do
78
        payload.map do |row|
79
          record = Order.find(row[:id])
80
          changes = row[:changes].to_unsafe_h.slice(*allowed)
81
          record.update!(changes)
82
          record
83
        end
84
      end
85

86
      render json: { rows: updated.as_json }
87
    rescue ActiveRecord::RecordNotFound => e
88
      render json: { error: e.message }, status: :not_found
89
    rescue ActiveRecord::RecordInvalid => e
90
      render json: { error: e.message }, status: :unprocessable_entity
91
    end
92

93
    # ------------------------------------------------------------------
94
    # DELETE /api/orders/remove_rows
95
    #
96
    # Accepts { row_ids: [1, 2, 3] }.
97
    # Uses delete_all so the whole batch runs in a single SQL statement.
98
    # Returns 204 No Content on success.
99
    # ------------------------------------------------------------------
100
    def remove_rows
101
      ids = Array(params[:row_ids])
102
      Order.where(id: ids).delete_all
103
      head :no_content
104
    end
105

106
    private
107

108
    # Translate Handsontable's sort state into ActiveRecord's .reorder() call.
109
    # Uses .reorder (not .order) so any default_scope ordering is replaced
110
    # rather than appended, which guarantees a single deterministic sort.
111
    # The hash form quotes the column name safely.
112
    # Values that are not on the whitelist are silently ignored -- no SQL
113
    # is generated for them.
114
    def apply_sort(scope)
115
      prop  = params[:sort_prop]
116
      order = params[:sort_order] == "desc" ? :desc : :asc
117

118
      return scope unless SORTABLE_COLUMNS.include?(prop)
119

120
      scope.reorder(prop => order)
121
    end
122

123
    # Translate Handsontable's filters[] param into chained .where calls.
124
    # Each condition is validated against the same whitelist used for sort.
125
    # Multiple conditions combine with AND.
126
    #
127
    # Conditions supported:
128
    #   contains / not_contains -- case-insensitive substring match (ILIKE)
129
    #   eq / neq                -- exact match
130
    #   begins_with / ends_with -- case-insensitive prefix / suffix match
131
    #   gt / gte / lt / lte     -- numeric comparisons
132
    #   empty / not_empty       -- checks for NULL or empty string
133
    def apply_filters(scope)
134
      filters = params[:filters]
135
      return scope if filters.blank?
136

137
      Array(filters.values).each do |filter|
138
        prop      = filter[:prop]
139
        value     = filter[:value]
140
        condition = filter[:condition].presence || "contains"
141

142
        next unless SORTABLE_COLUMNS.include?(prop)
143

144
        safe = Order.sanitize_sql_like(value.to_s)
145
        scope = case condition
146
                when "contains"     then scope.where("#{prop} ILIKE ?", "%#{safe}%")
147
                when "not_contains" then scope.where.not("#{prop} ILIKE ?", "%#{safe}%")
148
                when "eq"           then scope.where(prop => value)
149
                when "neq"          then scope.where.not(prop => value)
150
                when "begins_with"  then scope.where("#{prop} ILIKE ?", "#{safe}%")
151
                when "ends_with"    then scope.where("#{prop} ILIKE ?", "%#{safe}")
152
                when "gt"           then scope.where("#{prop} > ?", value)
153
                when "gte"          then scope.where("#{prop} >= ?", value)
154
                when "lt"           then scope.where("#{prop} < ?", value)
155
                when "lte"          then scope.where("#{prop} <= ?", value)
156
                when "empty"
157
                  string_col?(prop) ? scope.where("#{prop} IS NULL OR #{prop} = ''") : scope.where(prop => nil)
158
                when "not_empty"
159
                  string_col?(prop) ? scope.where.not("#{prop} IS NULL OR #{prop} = ''") : scope.where.not(prop => nil)
160
                else scope
161
                end
162
      end
163

164
      scope
165
    end
166

167
    def string_col?(prop)
168
      Order.column_for_attribute(prop)&.type&.in?(%i[string text])
169
    end
170
  end
171
end

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 (SORTABLE_COLUMNS in orders_controller.rb).

`index` — paginated list with sort and filter

See the index action in orders_controller.rb.

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

See apply_sort in orders_controller.rb.

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.reorder(prop => order) uses the hash form of .reorder(), which ActiveRecord quotes safely. reorder is used instead of order because the Order model has a default_scope that sorts by created_at DESC — reorder replaces that default, while order would append to it.
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. See apply_filters and string_col? in orders_controller.rb.

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.
sanitize_sql_like escapes LIKE metacharacters (%, _, \) in the user-supplied value so they are treated as literals, not wildcards.
ILIKE is PostgreSQL-specific. On SQLite or MySQL, use LIKE with a COLLATE clause or case-normalize the input.
empty/not_empty distinguish between string columns (check for NULL and blank string) and non-string columns (check for NULL only) via the string_col? helper.
Each condition rebinds scope, so multiple filters combine with AND. dataProvider does not send OR groups by default.

Batch CRUD actions

See create_rows, update_rows, and remove_rows in orders_controller.rb.

What’s happening:

create_rows — receives { rows: [...] }. Each row is inserted with create! inside a transaction, which raises on validation errors and rolls back all inserts if one fails. 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(*allowed) (where allowed also excludes id, created_at, updated_at) drops any unknown or system-managed keys so they never reach the ORM. All updates run inside a transaction. 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.

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.

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.
Filters are flattened from DataProviderFilterColumn[] (each with prop and conditions: [{name, args}]) into one bracket-notation entry per condition. Rails converts the bracket notation to a nested hash automatically.

Step 10 — Initialize Handsontable

Start the backend and the Vite dev server with bash setup.sh (or make setup), then open http://localhost:5173. The Rails API runs on http://localhost:3000 inside Docker; Vite proxies all /api/* requests to it. The complete frontend code is in the files below.

1
/* file: app.component.ts */
2
import {
3
  Component,
4
  ViewChild,
5
  ViewEncapsulation,
6
  CUSTOM_ELEMENTS_SCHEMA,
7
} from '@angular/core';
8
import { HotTableModule, HotTableComponent } from '@handsontable/angular-wrapper';
9
import type {
10
  DataProviderQueryParameters,
11
  RowsCreatePayload,
12
  RowUpdatePayload,
13
  RowMutationPayload,
14
  RowMutationRemovePayload,
15
} from 'handsontable/plugins/dataProvider';
16

17
const API_BASE = '/api/orders';
18

19
// Rails reads: page_size, sort_prop, sort_order, filters[N][prop/condition/value]
20
function buildUrl(base: string, params: DataProviderQueryParameters): string {
21
  const query = new URLSearchParams();
22

23
  query.set('page', String(params.page));
24
  query.set('page_size', String(params.pageSize));
25

26
  if (params.sort?.prop) {
27
    query.set('sort_prop', params.sort.prop);
28
    query.set('sort_order', params.sort.order ?? 'asc');
29
  }
30

31
  if (params.filters?.length) {
32
    let idx = 0;
33
    params.filters.forEach(({ prop, conditions }) => {
34
      conditions.forEach((cond) => {
35
        if (!cond?.name) return;
36
        query.set(`filters[${idx}][prop]`, prop);
37
        query.set(`filters[${idx}][condition]`, cond.name);
38
        if (cond.args?.[0] != null) {
39
          query.set(`filters[${idx}][value]`, String(cond.args[0]));
40
        }
41
        idx++;
42
      });
43
    });
44
  }
45

46
  return `${base}?${query}`;
47
}
48

49
@Component({
50
  standalone: true,
51
  encapsulation: ViewEncapsulation.None,
52
  imports: [HotTableModule],
53
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
54
  selector: 'example1-server-side-rails',
55
  template: `
56
    <div>
57
      <hot-table [settings]="settings"></hot-table>
58
    </div>
59
  `,
60
})
61
export class AppComponent {
62
  @ViewChild(HotTableComponent) readonly hotRef!: HotTableComponent;
63

64
  private removeConfirmed = false;
65

66
  settings = {
67
    dataProvider: {
68
      rowId: 'id',
69

70
      // Called on every page change, sort, and filter.
71
      fetchRows: async (queryParameters: DataProviderQueryParameters, { signal }: { signal: AbortSignal }) => {
72
        const url = buildUrl(API_BASE, queryParameters);
73
        const res = await fetch(url, { signal });
74

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

77
        // Rails returns: { rows: [...], total_rows: n }
78
        const json = await res.json();
79
        return { rows: json.rows, totalRows: json.total_rows };
80
      },
81

82
      // Fires when the user inserts rows via the context menu.
83
      // payload: { position: 'above'|'below', referenceRowId, rowsAmount }
84
      onRowsCreate: async (payload: RowsCreatePayload) => {
85
        const newRows = Array.from({ length: payload.rowsAmount }, () => ({
86
          order_number: `ORD-${Date.now()}-${Math.random().toString(36).slice(2, 6).toUpperCase()}`,
87
          customer: 'New Customer',
88
          status: 'pending',
89
          total: 0,
90
        }));
91

92
        const res = await fetch(`${API_BASE}/create_rows`, {
93
          method: 'POST',
94
          headers: { 'Content-Type': 'application/json' },
95
          body: JSON.stringify({ rows: newRows }),
96
        });
97

98
        if (!res.ok) {
99
          const err = await res.json().catch(() => ({})) as { error?: string };
100
          throw new Error(err.error ?? `Create failed: ${res.status}`);
101
        }
102

103
        const json = await res.json();
104
        const info = json.rows.map((r: { order_number: string }) => `(order: ${r.order_number})`).join(', ');
105
        // eslint-disable-next-line @typescript-eslint/no-explicit-any
106
        (this.hotRef.hotInstance!.getPlugin('notification') as any).showMessage({
107
          variant: 'success',
108
          title: 'Row added',
109
          message: `Created: ${info}`,
110
          duration: 3000,
111
        });
112

113
        return json.rows;
114
      },
115

116
      // Fires after a cell edit, paste, or autofill batch.
117
      onRowsUpdate: async (rows: RowUpdatePayload[]) => {
118
        const res = await fetch(`${API_BASE}/update_rows`, {
119
          method: 'PATCH',
120
          headers: { 'Content-Type': 'application/json' },
121
          body: JSON.stringify({
122
            rows: rows.map((r) => ({ id: r.id, changes: r.changes })),
123
          }),
124
        });
125

126
        if (!res.ok) {
127
          const err = await res.json().catch(() => ({})) as { error?: string };
128
          throw new Error(err.error ?? `Update failed: ${res.status}`);
129
        }
130
      },
131

132
      // Fires after the user confirms deletion.
133
      onRowsRemove: async (rowIds: unknown[]) => {
134
        const res = await fetch(`${API_BASE}/remove_rows`, {
135
          method: 'DELETE',
136
          headers: { 'Content-Type': 'application/json' },
137
          body: JSON.stringify({ row_ids: rowIds }),
138
        });
139

140
        if (!res.ok) throw new Error(`Delete failed: ${res.status}`);
141
      },
142
    },
143

144
    // beforeRowsMutation is sync (checks for a strict `=== false` return), so
145
    // we can't await an async prompt inline. Instead: cancel the original
146
    // attempt, show a notification with Delete/Cancel actions, and on Delete
147
    // re-issue the remove via the DataProvider API. The flag lets the second
148
    // pass through without re-prompting.
149
    beforeRowsMutation: (operation: 'create' | 'update' | 'remove', payload: RowMutationPayload): false | void => {
150
      if (operation === 'remove' && !this.removeConfirmed) {
151
        const { rowsRemove } = payload as RowMutationRemovePayload;
152
        const hot = this.hotRef.hotInstance!;
153
        const count = rowsRemove.length;
154
        // eslint-disable-next-line @typescript-eslint/no-explicit-any
155
        const notification = (hot.getPlugin('notification') as any);
156
        const id = notification.showMessage({
157
          variant: 'warning',
158
          title: 'Delete rows',
159
          message: `Delete ${count} row${count !== 1 ? 's' : ''}? This cannot be undone.`,
160
          duration: 0,
161
          actions: [
162
            {
163
              label: 'Delete',
164
              type: 'primary',
165
              callback: () => {
166
                notification.hide(id);
167
                this.removeConfirmed = true;
168
                // eslint-disable-next-line @typescript-eslint/no-explicit-any
169
                (hot.getPlugin('dataProvider') as any)
170
                  .removeRows(rowsRemove)
171
                  .finally(() => {
172
                    this.removeConfirmed = false;
173
                  });
174
              },
175
            },
176
            {
177
              label: 'Cancel',
178
              type: 'secondary',
179
              callback: () => notification.hide(id),
180
            },
181
          ],
182
        });
183
        return false;
184
      }
185
    },
186

187
    pagination:     { pageSize: 10 },
188
    columnSorting:  true,
189
    filters:        true,
190
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
191
    dropdownMenu:   ['filter_by_condition', 'filter_action_bar'] as any,
192
    contextMenu:    true,
193
    emptyDataState: true,
194
    notification:   true,
195
    dialog:         true,
196
    rowHeaders:     true,
197
    colHeaders: ['Order #', 'Customer', 'Status', 'Total', 'Created'],
198
    columns: [
199
      { data: 'order_number', type: 'text' },
200
      { data: 'customer',     type: 'text' },
201
      { data: 'status',       type: 'text' },
202
      { data: 'total',        type: 'numeric', numericFormat: { pattern: '$0,0.00' } },
203
      { data: 'created_at',   type: 'date', dateFormat: 'YYYY-MM-DD', readOnly: true },
204
    ],
205
    height:      'auto',
206
    licenseKey:  'non-commercial-and-evaluation',
207
  };
208
}
209
/* end-file */
210

211
/* file: app.config.ts */
212
import { ApplicationConfig, provideZoneChangeDetection } from '@angular/core';
213
import { registerAllModules } from 'handsontable/registry';
214
import { HOT_GLOBAL_CONFIG, HotGlobalConfig, NON_COMMERCIAL_LICENSE } from '@handsontable/angular-wrapper';
215

216
registerAllModules();
217

218
export const appConfig: ApplicationConfig = {
219
  providers: [
220
    provideZoneChangeDetection({ eventCoalescing: true }),
221
    {
222
      provide: HOT_GLOBAL_CONFIG,
223
      useValue: { license: NON_COMMERCIAL_LICENSE } as HotGlobalConfig,
224
    },
225
  ],
226
};
227
/* end-file */

1
<div>
2
  <example1-server-side-rails></example1-server-side-rails>
3
</div>

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.
`{ rowsAmount }` in `onRowsCreate`	`dataProvider` passes the number of rows to add. The frontend builds default objects and sends them as `{ rows: [...] }`. Returning `json.rows` lets `dataProvider` replace client-side placeholder ids with the ids assigned by Rails.
`beforeRowsMutation`	Intercepts mutations before they run. Return `false` to cancel. Used here to show a delete-confirmation notification with Delete/Cancel actions instead of deleting immediately.
`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`.
`contextMenu: true`	Enables right-click context menu with Insert row above / below and Remove row options.
`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.
`dialog: true`	Enables the Dialog plugin used internally by other plugins for confirmation prompts.

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 calls onRowsUpdate with [{ id: 7, changes: { total: 142.5 } }]. The frontend maps this to { id, changes } and sends it. update_rows applies the change inside a transaction.
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 DataProviderFilterColumn[] ({prop, conditions: [{name, args}]}) must be flattened into indexed filters[N][prop/condition/value] bracket params before sending. Rails parses the bracket notation into a nested hash automatically — no custom decoder is required on the backend.
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