Controllers

Authenticated Lesli engine controllers inherit shared request, response, customization, security, and audit behavior from Lesli::ApplicationLesliController.

Define one application controller inside the engine namespace, then inherit resource controllers from it:

module MyEngine
    class ApplicationController < Lesli::ApplicationLesliController
    end

    class TicketsController < ApplicationController
    end
end

Use Lesli::ApplicationController instead for public pages that do not need the authenticated engine lifecycle.

Controllers are HTTP adapters. Each CRUD action calls the corresponding resource service operation: index, show, create, update, or destroy. Selector endpoints call the service's list method for lightweight id/name options. Use find before operations on an existing record. new and edit prepare forms, and do not require placeholder service methods.

Keep persistence calls and business workflows out of controller actions. Delegate resource CRUD to services and named business actions to operators. The complete responsibility and dependency rules are documented in Application Architecture.


Controller Lifecycle

Lesli::ApplicationLesliController runs the following callbacks:

  1. Select the locale from the session or Require-Language request header.
  2. Authenticate and authorize the request when LesliShield is installed.
  3. Prepare customization state.
  4. Normalize common query parameters into query.
  5. Log the completed request when LesliAudit is installed.

It also uses the lesli/layouts/application-lesli layout and includes the requester and responder interfaces described in Controller Interfaces.

Security and audit callbacks are conditional. Inheriting from this controller does not install LesliShield or LesliAudit.


Query Parameters

The requester interface exposes normalized request options through the query reader:

{
    search: params[:search],
    pagination: {
        perPage: params[:perPage]&.to_i || 12,
        page: params[:page]&.to_i || 1
    },
    order: {
        by: params[:orderBy] || "id",
        dir: params[:order] || "desc"
    }
}

Pass this hash into service objects instead of repeating pagination and ordering parsing in every controller:

def index
    scope = TicketService.new(current_user, query).index
    @tickets = respond_with_pagination(scope)
end

The service remains responsible for allowlisting sortable columns and safe order directions before using request-derived values in a database query.


Multi-format Responses

Use respond_with_lesli when an action supports HTML, JSON, or Turbo Stream requests:

def update
    ticket = TicketService.new(current_user, query).find(id: params[:id])
    return respond_with_not_found unless ticket.found?

    ticket.update(ticket_params)
    @ticket = ticket.result

    if ticket.successful?
        respond_with_lesli(
            turbo: stream_notification_success("Ticket updated"),
            json: ticket.result,
            redirect: ticket_path(ticket.result)
        )
    else
        respond_with_lesli(
            turbo: stream_notification_danger(ticket.errors_as_sentence),
            json: { errors: ticket.errors },
            html: "my_engine/tickets/edit",
            status: :unprocessable_entity
        )
    end
end

html: identifies a template or renderable, while redirect: identifies an HTML redirect destination. Do not pass the result of redirect_to through html: and do not provide both options in one call. When neither is present, Rails renders the current action's HTML template.

status: applies to HTML, JSON, and Turbo Stream renders and defaults to :ok. HTML redirects use redirect_status: :see_other by default. Only provide formats the action is expected to serve; the responder selects the payload matching the request format.

See Controller Interfaces for complete examples covering multiple Turbo Stream actions, redirects, JSON payloads, default HTML rendering, and validation errors.


Custom Business Actions

Use an operator for a controller action that does not represent CRUD. Resolve the resource through its account-scoped service before invoking the operator:

def close
    service = TicketService.new(current_user, query).find(id: params[:id])
    return respond_with_not_found unless service.found?

    ticket = TicketOperator.new(
        ticket: service.result,
        actor: current_user
    ).close!

    respond_with_lesli(
        turbo: stream_notification_success("Ticket closed"),
        json: ticket
    )
end

The controller selects the response. The operator owns the close workflow and must not render, redirect, or construct Turbo Streams.


Pagination Responses

respond_with_pagination expects a paginated collection that responds to Kaminari's pagination methods:

records = Ticket
    .order(id: :desc)
    .page(query[:pagination][:page])
    .per(query[:pagination][:perPage])

payload = respond_with_pagination(records)

The returned hash has this shape:

{
    pagination: {
        page: 1,
        pages: 4,
        total: 42,
        results: 12
    },
    records: records
}

Passing an ordinary, unpaginated Active Record relation raises an error because the required pagination methods are absent.


Errors and Notifications

The shared controller provides:

  • respond_with_not_found(message = nil) for HTML, JSON, and Turbo Stream 404 responses
  • respond_with_forbidden(details = {}) for authorization failures after a user has authenticated
  • info, success, warning, and danger for flash messages
  • stream_notification_info, stream_notification_success, stream_notification_warning, and stream_notification_danger for Turbo Stream notifications
  • stream_redirection(path) for redirects initiated from a Turbo Stream response

Authorization failures return HTTP 403. respond_with_unauthorized remains available as a backwards-compatible alias, but new code should use respond_with_forbidden. Authentication failures are separate: an unauthenticated browser request is handled by LesliShield's authentication interface and redirected to login.

Avoid returning authorization details in production. The built-in forbidden responder suppresses its diagnostic details when Rails runs in production.


Strong Parameters

Use standard Rails strong parameters at the controller boundary:

private

def ticket_params
    params.require(:ticket).permit(:subject, :description, :priority_id)
end

Keep required parameter names aligned with the form and API payload.

 Edit this page

Last Update: 2026/11/16