plutonium-behavior

Plutonium Behavior — Controllers, Policies, Interactions

The behavior layer is intentionally thin: controllers route, policies authorize, interactions act. Registering an action and rendering it lives in [[plutonium-resource]] — this skill covers how to write the controller hook, policy method, or interaction class behind it.

For tenant-scoped relation_scope and entity scoping, load [[plutonium-tenancy]].

🚨 Critical (read first)

• Use generators. pu:res:scaffold creates the base trio (controller/policy/interaction-base); pu:res:conn creates portal-specific versions. Never hand-write them.
• Don't override CRUD actions. Use hooks (resource_params, redirect_url_after_submit, presentation hooks). Overriding create/update usually breaks authorization, params filtering, or both.
• create? and read? default to false. Always override them explicitly. Derived methods (update?, show?, etc.) inherit automatically.
• permitted_attributes_for_* must be explicit in production. Dev auto-detection works; production raises.
• ActiveRecord::RecordInvalid is NOT rescued automatically in interactions. Always rescue when using create! / update! / save!, return failed(e.record.errors).
• Return succeed(...) or failed(...) from execute — the controller can't tell what happened otherwise.
• An interaction is a presentation object (it can only be built with a view_context). Logic may start in execute; the second caller — a job, an API controller, a rake task, the console — is the trigger to move it onto the model. Don't pre-extract, and don't invent a service layer. See Part 3 › Where the logic goes.
• Redirect is automatic on success — only use with_redirect_response for a different destination.
• relation_scope must end up calling default_relation_scope(relation) somewhere in the chain. Prefer calling it explicitly. super works when extending a parent policy (e.g., a package base) that itself calls it. See [[plutonium-tenancy]].
• For has_cents fields, use the virtual name (:price), not :price_cents in permitted_attributes_for_*.
• Custom action ⇒ policy method. action :publish needs def publish? on the policy (undefined methods return false).
• Named custom routes. When adding custom routes, always pass as: so resource_url_for can build URLs.

🛑 Before you write behavior: place it in the right layer (ASK — don't infer)

"Make X happen" doesn't say where X lives. Put it in the wrong layer and you get authorization that doesn't authorize, a 500 on the happy path, or a CRUD override that breaks params/auth. First place the requirement, then confirm names against the real code (next section):

Then resolve the specifics:

1. A custom action needs BOTH: an interaction (the work) and a policy def <action>? (the authorization). Miss the policy method ⇒ the action silently returns false (dead button). Put the role check in condition: ⇒ it isn't enforced — a direct POST still runs.
2. create?/read? default to false — override explicitly; derived methods (update?/show?/…) inherit.
3. Any create!/update!/save! in execute ⇒ rescue ActiveRecord::RecordInvalid → failed(e.record.errors). Not auto-rescued — otherwise a validation failure 500s.
4. has_cents ⇒ permit :price, never :price_cents.
5. New vs editing — never re-scaffold a controller/policy/interaction that's been customized.

Never ship a guessed role method, column, enum value, or association as applied code. user.finance?, record.status_approved?, expense.submitted_by either exist in the app or they don't — confirm them before writing, don't assume. Fall back to AskUserQuestion only for genuine product choices (what the rule should be), never for facts you can read.

✅ Before you edit: verify the ground truth (CHECK — read it, don't ask for it)

You have file access — inspect; don't ask the user to describe their own app.

Inspect with your own tools before proposing code.

🛠 Use the generator — and know what's hand-authored

Part 1 — Controllers

Plutonium controllers ship full CRUD out of the box; nearly all customization lives in definitions / policies / interactions. The controller stays thin.

Base classes

# app/controllers/resource_controller.rb (installed once)
class ResourceController < ApplicationController
  include Plutonium::Resource::Controller
end

# app/controllers/posts_controller.rb (per resource, generated by pu:res:scaffold)
class PostsController < ::ResourceController
  # Empty — all CRUD inherited
end

What you get for free

Plus interactive-action routes for every action declared in the definition.

Where customization belongs

Override hooks

All hooks are private methods. Override only the ones you need.

Redirect hooks

class PostsController < ::ResourceController
  private

  # Where to go after create/update: "show" (default), "edit", "new", "index"
  def preferred_action_after_submit = "edit"

  # Custom URL after create/update (overrides preferred_action_after_submit)
  def redirect_url_after_submit = posts_path

  # Custom URL after destroy
  def redirect_url_after_destroy = posts_path
end

Parameter hook

def resource_params
  params = super
  params[:tags] = params[:tags].split(",") if params[:tags].is_a?(String)
  params
end

Index query hook

def filtered_resource_collection
  base = current_authorized_scope
  base = base.featured if params[:featured]
  current_query_object.apply(base, raw_resource_query_params)
end

Don't add eager loading unprompted. Which associations a page renders is decided by the definition, so an includes list written now is a guess that goes stale when a column is added. Adding one is a performance change the user didn't ask for.

When a user actually reports a slow index or an N+1: suggest goldiloader first — it eager-loads on traversal, so it tracks whatever the definition renders and needs no list to maintain. Only hand-write def filtered_resource_collection = super.includes(...) if they decline the gem, and use the policy's relation_scope instead when the association is also read on show/export/typeahead. Full detail: [Guides › Perfor

Content truncated.