Nested Resources

Plutonium auto-generates nested routes from has_many and has_one associations on a registered parent. No manual route wiring — belongs_to on the child plus register_resource for both is enough.

🚨 Critical

• One level only. Grandparent → parent → child nested routes are NOT supported. Use top-level routes for deeper relationships.
• Parent scoping beats entity scoping. When a parent is present, default_relation_scope scopes via the parent, NOT via entity_scope. Don't double-scope.
• Named custom routes. When adding member/collection routes on a nested resource, always pass as: — otherwise resource_url_for will fail.
• The parent is authorized for :read? before current_parent returns. The child policy receives the parent in its context.

Setup

rails g pu:res:scaffold Company name:string --dest=main_app
rails g pu:res:scaffold Property company:belongs_to name:string --dest=main_app
rails g pu:res:conn Company Property --dest=admin_portal

Then register both in the portal:

# packages/admin_portal/config/routes.rb
register_resource ::Company
register_resource ::Property        # has belongs_to :company
register_resource ::CompanyProfile  # has_one :company_profile on Company

Generated routes

Plutonium prefixes nested routes with nested_ so they don't conflict with the top-level routes:

Route	Purpose
/companies/:company_id/nested_properties	has_many index
/companies/:company_id/nested_properties/new	new
/companies/:company_id/nested_properties/:id	show
/companies/:company_id/nested_company_profile	has_one show (no :id)
/companies/:company_id/nested_company_profile/new	has_one new

For has_one:

• Routes are singular (no :id param).
• Index redirects to show (or new if no record exists).
• Only one record can exist per parent.
• Forms don't show the parent field (determined by URL).

Automatic behavior on nested routes

When the controller is hit via a nested route, Plutonium automatically:

1. Resolves the parent via current_parent, authorized for :read?.
2. Scopes queries via the parent association:
   • has_many → parent.send(parent_association) (e.g. company.properties)
   • has_one → relation.where(foreign_key => parent.id) with limit
3. Assigns the parent on create (injected into resource_params).
4. Hides the parent field in forms and displays (already determined by URL).

You don't add hidden parent fields or filter queries manually.

Controller methods

current_parent              # parent record (e.g. Company instance)
current_parent_class        # parent class (e.g. Company)
current_nested_association  # association name (e.g. :properties)
parent_input_param          # form param / association name (e.g. :company)

Each nested route carries the key of its own registration, so the parent class and association are read from the route rather than reconstructed from the URL. That is what lets a resource registered singular: true act as a parent at all — it contributes no id parameter, so there is nothing in the path to infer from.

Parent vs entity scoping

When a parent is present, parent scoping wins: default_relation_scope scopes via the parent association, NOT entity_scope. The parent was already authorized and entity-scoped during its own authorization — double-scoping is redundant.

In the child's policy, just call default_relation_scope — it handles both cases:

class PropertyPolicy < ResourcePolicy
  relation_scope do |relation|
    default_relation_scope(relation)    # parent when present, entity_scope otherwise
  end
end

For composite filtering on top of the default:

relation_scope do |relation|
  default_relation_scope(relation).where(archived: false)
end

URL generation

resource_url_for(...) with the parent: option:

# Child collection (has_many)
resource_url_for(Property, parent: company)
# => /companies/123/nested_properties

# Child record
resource_url_for(property, parent: company)
# => /companies/123/nested_properties/456

# New child
resource_url_for(Property, action: :new, parent: company)
# => /companies/123/nested_properties/new

# Edit child
resource_url_for(property, action: :edit, parent: company)
# => /companies/123/nested_properties/456/edit

# Singular (has_one)
resource_url_for(company_profile, parent: company)
# => /companies/123/nested_company_profile

resource_url_for(CompanyProfile, action: :new, parent: company)
# => /companies/123/nested_company_profile/new

# Interactions compose with parent
resource_url_for(property, parent: company, interaction: :archive)
resource_url_for(Property, parent: company, interaction: :import)
resource_url_for(Property, parent: company, interaction: :bulk_delete, ids: [1, 2])

Cross-package URLs

# From AdminPortal, generate URL to a CustomerPortal resource
resource_url_for(property, parent: company, package: CustomerPortal)

Authorization context

The child policy receives the parent automatically:

class PropertyPolicy < ResourcePolicy
  # parent              => the Company instance
  # parent_association  => :properties

  def create?
    parent.present? && user.member_of?(parent)
  end

  def read?
    parent.present? && record.company == parent
  end
end

The parent is authorized for :read? before current_parent returns — children inherit the parent's access requirements.

Parameter handling

The parent is injected into resource_params automatically:

# When creating a property under /companies/123/nested_properties
resource_params
# => { name: "...", company: <Company:123>, company_id: 123 }

No hidden parent fields needed in forms.

Presentation hooks

Control whether the parent field appears in views/forms:

class PropertiesController < ::ResourceController
  private

  def present_parent?  = true     # show on displays (default: false)
  def submit_parent?   = false    # include in forms (defaults to present_parent?)
end

Conditional — show parent only when accessed standalone:

def present_parent?
  current_parent.nil?
end

Custom parent resolution

Override current_parent for non-default lookup:

class PropertiesController < ::ResourceController
  private

  def current_parent
    @current_parent ||= Company.friendly.find(params[:company_id])
  end
end

Custom routes on nested resources

register_resource ::Property do
  member do
    get  :analytics, as: :analytics
    post :archive,   as: :archive
  end
  collection do
    get  :report,    as: :report
  end
end

Generates /companies/:company_id/nested_properties/:id/analytics, etc.

Always pass as:

Without as:, resource_url_for(property, parent: company, action: :analytics) fails — there's no named route to look up.

Compound uniqueness

Scope uniqueness to the parent FK:

class Property < ResourceRecord
  belongs_to :company
  validates :code, uniqueness: {scope: :company_id}
end

Without the scope, the same code in different companies would collide.

Custom association scope (for complex relationships)

When the parent path isn't a direct belongs_to, define a custom scope on the child:

class Property < ResourceRecord
  scope :associated_with_organization, ->(org) {
    joins(:company).where(companies: {organization_id: org.id})
  }
end

Useful when the child is nested under a grandparent-style entity. See Entity scoping › Three model shapes.

Breadcrumbs

Auto-include the parent: Companies > Acme Corp > Properties > Property #123.

Nesting limitations

Plutonium supports one level of nesting:

• ✅ /companies/:company_id/nested_properties (parent → child)
• ❌ /companies/:company_id/nested_properties/:property_id/nested_units (grandparent → parent → child)

For deeper hierarchies, use top-level routes plus association tabs on the show page (see Behavior › Policy › Association permissions and Resource › Definition › Custom page classes).

Related

• Entity scoping — what happens when no parent is present
• Invites — membership-based onboarding
• Behavior › Policy — relation_scope, parent context
• Behavior › Controllers — current_parent, presentation hooks
• App › Portals — register_resource and custom member/collection routes