controller-guide.md

Controller Guide

The ActiveDataSource::Controller concern provides all standard REST actions with zero boilerplate.

---

Basic Setup

class UsersController < ApplicationController
  include ActiveDataSource::Controller
  resource UserResource
end

---

Provided Actions

Action	Route	Description
index	GET /users	Paginated, filtered, sorted, searched collection
show	GET /users/:id	Single record with authorization
create	POST /users	Create + validate + broadcast
update	PATCH /users/:id	Update + validate + broadcast
destroy	DELETE /users/:id	Delete + broadcast
bulk_update	PATCH /users/bulk_update	Batch update with ids[] param
bulk_delete	DELETE /users/bulk_delete	Batch delete with ids[] param
export	GET /users/export	CSV or JSON export (requires exportable flag)
schema	GET /users/schema	Resource metadata for dynamic forms
metadata	GET /users/metadata	Alias for schema
statistics	GET /users/statistics	Aggregate statistics

---

Routes

resources :users do
  collection do
    get    :schema
    get    :statistics
    get    :export
    patch  :bulk_update
    delete :bulk_delete
  end
end

---

Overridable Hooks

All private helpers are designed to be overridden in subclasses:

ads_permitted_params

class UsersController < ApplicationController
  include ActiveDataSource::Controller
  resource UserResource

  private

  def ads_permitted_params
    params.require(:user).permit(:name, :email, :status, :organization_id)
  end
end

ads_current_user

By default calls current_user. Override if your method name differs:

def ads_current_user
  @current_admin
end

ads_current_tenant

def ads_current_tenant
  @current_organization
end

---

Customising Individual Actions

Override any action to add custom logic before or after the default behaviour:

class UsersController < ApplicationController
  include ActiveDataSource::Controller
  resource UserResource

  def create
    # Custom before-create logic
    super
    # Custom after-create logic
  end

  def index
    # Completely custom index
    result = UserResource.execute(
      UserResource.build_context(params, user: current_user)
    )
    ads_renderer.render_collection(result)
  end
end

---

Error Handling

Errors are automatically rescued and rendered as JSON:

Error Class	HTTP Status	Trigger
Errors::Authorization	403	Pundit/CanCanCan denies access
Errors::Validation	422	AR model fails validation
Errors::Base	422	Invalid filter/sort/operator
ActiveRecord::RecordNotFound	404	Record not found

---

Skipping Actions

Use standard Rails before_action to restrict actions:

class UsersController < ApplicationController
  include ActiveDataSource::Controller
  resource UserResource

  before_action :require_admin!, only: [:bulk_delete, :export]
end

---

Bulk Actions

Bulk update:

PATCH /users/bulk_update
Content-Type: application/json

{
  "ids": [1, 2, 3],
  "status": "inactive"
}

Bulk delete:

DELETE /users/bulk_delete
Content-Type: application/json

{
  "ids": [4, 5, 6]
}

---

Export

When exportable is set on the resource:

GET /users/export.csv
GET /users/export.json?filter[status][eq]=active