ActiveScaffold Documentation

ActiveScaffold supports both Sprockets and Propshaft. Since version 4.3, colors are primarily managed via CSS variables, though SASS variables are still supported for backward compatibility.

Using Propshaft + dartsass-rails

Because Propshaft does not support .erb files for CSS, ActiveScaffold generates a SCSS file during development and precompilation. You can manually trigger generation using active_scaffold:assets:generate.

To use it in your application.scss:

@use 'active_scaffold/core' with (
  // set values to variables
);

Using Sprockets + dartsass-sprockets

You can load the entire ActiveScaffold suite (including jQuery UI and plugin CSS) with a single directive:

@use 'active_scaffold' with (
  // set values to variables
);

For granular control, you can import individual files:

@use 'active_scaffold/variables' with (...);
@use 'active_scaffold/colours';
@use 'active_scaffold/layout';
@use 'active_scaffold/images';

// Propshaft example
@use 'active_scaffold/core' with (
  // set values to variables
);

// Sprockets example
@use 'active_scaffold' with (
  // set values to variables
);

To set up ActiveScaffold in a new Rails project, add the necessary gems to your Gemfile, run the installation generator, and scaffold a resource.

Requirements:

• Rails >= 7.2.0
• Ruby >= 3.2.0

Steps:

1. Add active_scaffold and jquery-rails to your Gemfile.
2. Run bundle install.
3. Run rails g active_scaffold:install to configure assets and manifests.
4. Create your database and scaffold a resource using rails g active_scaffold:resource Model [attrs].
5. Run migrations.

Important Note: It is highly recommended to call clear_helpers in your ApplicationController. This prevents helper methods (like active_scaffold_enum_options) from being globally available to all controllers, which can cause issues if different controllers need to override them for different models.

# Gemfile
gem 'active_scaffold'
gem 'jquery-rails'

bundle install
rails g active_scaffold:install
rails db:create
rails g active_scaffold:resource Model [attrs]
rails db:migrate

# app/controllers/application_controller.rb
class ApplicationController < ActionController::Base
  clear_helpers
end

ActiveScaffold requires jquery and either jquery_ujs or rails_ujs. The method for loading depends on your asset pipeline.

Propshaft + Importmaps

1. Pin the assets in config/importmap.rb:

pin 'active_scaffold', to: 'active_scaffold/load.js'
pin 'jquery'
pin 'jquery_ujs'

2. Import them in app/javascript/application.js:

import 'jquery'
import 'jquery_ujs'
import 'active_scaffold'

3. In your layout, include the importmap tags and the ActiveScaffold helper:

<%= javascript_importmap_tags %>
<%= active_scaffold_javascript_tag %>

Propshaft (Individual Files)

If not using importmaps, load files manually and use the helper:

<%= javascript_include_tag 'jquery', 'jquery_ujs' %>
<%= active_scaffold_javascript_tag %>

Sprockets

Use the standard require directive in application.js:

//= require active_scaffold

If using importmaps with Sprockets, you do not need to call active_scaffold_javascript_tag as the js.erb file handles the necessary generated code.

# config/importmap.rb
pin 'active_scaffold', to: 'active_scaffold/load.js'
pin 'jquery'
pin 'jquery_ujs'

// app/javascript/application.js
import 'jquery'
import 'jquery_ujs'
import 'active_scaffold'

<%# app/views/layouts/application.html.erb %>
<%= javascript_importmap_tags %>
<%= active_scaffold_javascript_tag %>

ActiveScaffold allows you to override how a column is rendered in a list view by defining specific helper methods in your view context.

There are two ways to trigger an override:

1. Explicit Column Override: Define a method named active_scaffold_column_{column_name}(record, column, ui_options: column.options). ActiveScaffold will automatically detect and use this method for that specific column.
2. UI-based Override: If you specify a list_ui for a column, ActiveScaffold looks for a helper following the pattern active_scaffold_column_{list_ui}(record, column, ui_options: column.options). For example, if list_ui: :checkbox is set, it looks for active_scaffold_column_checkbox.

Note: Overrides receive the record as the first argument. The ui_options hash contains column-specific options (like truncate or format).

# Example: Overriding the 'status' column to use a custom helper
def active_scaffold_column_status(record, column, ui_options: column.options)
  status_color = record.status == 'active' ? 'green' : 'red'
  content_tag(:span, record.status, style: "color: #{status_color}")
end

ActiveScaffold supports field-level searching, which allows users to search against specific columns rather than a single global text box. This implementation uses params[:search] instead of the model instance (@record) to ensure that search conditions can bypass model validations (e.g., performing textual searches against associations via .search_sql).

Requirements:

• The model must have a primary key if you are performing field searches on association columns.
• If a primary key is missing and you attempt to search via association columns, an error will be raised during configuration.

Key Behaviors:

• Search Parameters: Search criteria are passed via params[:search].
• Session Persistence: Search parameters can be stored in the session to persist across requests.
• Default Parameters: You can define default_params for field searches, which can be a static value or a Proc evaluated in the controller context.

ActiveScaffold's FieldSearch allows for "grouped searching," which enables the list view to perform SQL GROUP BY operations and aggregate calculations (like counts or sums) based on search parameters.

How it works:

• Grouping Trigger: Grouping is activated when field_search_params contains an active_scaffold_group key.
• Group Syntax: The group value follows the pattern column_name#function (e.g., created_at#year).
• Supported Functions:
  • year
  • month
  • quarter
  • year_month (calculated via SQL operators)
  • year_quarter (calculated via SQL operators)
• Calculations: The system uses the calculate and grouped_select definitions from your column configuration to build the SELECT clause.

Implementation Note: When grouping is active, custom_finder_options is used to inject group, select, and reorder clauses into the ActiveRecord query.