Class: IronAdmin::Adapters::Base Abstract

Inherits:
Object
  • Object
show all
Defined in:
lib/iron_admin/adapters/base.rb

Overview

This class is abstract.

Subclass and implement all methods to create a custom adapter.

Abstract base class defining the interface every data source adapter must implement.

IronAdmin uses this interface to introspect schemas, build queries, perform CRUD operations, and search records. The default ActiveRecord adapter wraps Rails' ActiveRecord ORM. Future adapters (Mongoid, HTTP, etc.) implement this same interface.

Direct Known Subclasses

ActiveRecord, Http, Mongoid

Defined Under Namespace

Classes: ColumnDescriptor

Constant Summary collapse

TRUTHY_VALUES =

Casts a string value to a boolean. Default implementation for non-AR adapters. ActiveRecord overrides to use ActiveModel::Type::Boolean.

Returns:

  • (Boolean) 
%w[true 1 yes].freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(model_class) ⇒ Base

Returns a new instance of Base.

Parameters:

  • model_class (Class) —

    The model class to wrap



17
18
19
 
# File 'lib/iron_admin/adapters/base.rb', line 17

def initialize(model_class)
  @model_class = model_class
end

Instance Attribute Details

#model_class ⇒ Class (readonly)

Returns The underlying model/data class this adapter wraps.

Returns:

  • (Class) —

    The underlying model/data class this adapter wraps



14
15
16
 
# File 'lib/iron_admin/adapters/base.rb', line 14

def model_class
  @model_class
end

Instance Method Details

#all ⇒ Object

Returns a base scope/collection of all records.

Returns:

  • (Object) —

    A chainable query object

Raises:

  • (NotImplementedError) 


116
117
118
 
# File 'lib/iron_admin/adapters/base.rb', line 116

def all
  raise NotImplementedError
end

#association(_name) ⇒ #name, ...

Returns a single association descriptor by name.

Parameters:

  • name (Symbol) —

    Association name

Returns:

  • (#name, #klass, #foreign_key, nil)

Raises:

  • (NotImplementedError) 


58
59
60
 
# File 'lib/iron_admin/adapters/base.rb', line 58

def association(_name)
  raise NotImplementedError
end

#associations(_kind = nil) ⇒ Array<#name, #klass, #foreign_key, #polymorphic?>

Returns association descriptors.

Parameters:

  • kind (Symbol, nil) —

    Filter by :belongs_to, :has_many, :has_one, :has_and_belongs_to_many

Returns:

  • (Array<#name, #klass, #foreign_key, #polymorphic?>)

Raises:

  • (NotImplementedError) 


51
52
53
 
# File 'lib/iron_admin/adapters/base.rb', line 51

def associations(_kind = nil)
  raise NotImplementedError
end

#attachments ⇒ Hash

Returns ActiveStorage attachment descriptors.

Returns:

  • (Hash) —

    Attachment name to reflection mapping

Raises:

  • (NotImplementedError) 


64
65
66
 
# File 'lib/iron_admin/adapters/base.rb', line 64

def attachments
  raise NotImplementedError
end

#build(_attrs = {}) ⇒ Object

Builds a new unsaved record.

Parameters:

  • attrs (Hash) —

    Initial attributes

Returns:

  • (Object) —

    New record

Raises:

  • (NotImplementedError) 


221
222
223
 
# File 'lib/iron_admin/adapters/base.rb', line 221

def build(_attrs = {})
  raise NotImplementedError
end

#cast_boolean(value) ⇒ Object

rubocop:disable Naming/PredicateMethod



328
329
330
 
# File 'lib/iron_admin/adapters/base.rb', line 328

def cast_boolean(value) # rubocop:disable Naming/PredicateMethod
  TRUTHY_VALUES.include?(value.to_s.downcase)
end

#column_names ⇒ Array<String>

Returns column name strings.

Returns:

  • (Array<String>)

Raises:

  • (NotImplementedError) 


31
32
33
 
# File 'lib/iron_admin/adapters/base.rb', line 31

def column_names
  raise NotImplementedError
end

#columns ⇒ Array<#name, #type>

Returns column descriptors for the model.

Returns:

  • (Array<#name, #type>) —

    Objects responding to .name (String) and .type (Symbol)

Raises:

  • (NotImplementedError) 


25
26
27
 
# File 'lib/iron_admin/adapters/base.rb', line 25

def columns
  raise NotImplementedError
end

#count(_scope = nil) ⇒ Integer

Returns record count for a scope.

Returns:

  • (Integer)

Raises:

  • (NotImplementedError) 


192
193
194
 
# File 'lib/iron_admin/adapters/base.rb', line 192

def count(_scope = nil)
  raise NotImplementedError
end

#create_record(attrs) ⇒ Object

Builds and persists a record, returning the record with validation errors if any.

Parameters:

  • attrs (Hash) —

    Attributes for the new record

Returns:

  • (Object) 


243
244
245
246
247
 
# File 'lib/iron_admin/adapters/base.rb', line 243

def create_record(attrs)
  record = build(attrs)
  save(record)
  record
end

#destroy!(_record) ⇒ void

This method returns an undefined value.

Destroys a record.

Parameters:

  • record (Object) —

    The record

Raises:

  • (NotImplementedError) 


260
261
262
 
# File 'lib/iron_admin/adapters/base.rb', line 260

def destroy!(_record)
  raise NotImplementedError
end

#distinct_values(_column) ⇒ Array

Returns distinct values for a column.

Parameters:

  • column (Symbol, String) —

    Column name

Returns:

  • (Array) —

    Sorted unique values

Raises:

  • (NotImplementedError) 


178
179
180
 
# File 'lib/iron_admin/adapters/base.rb', line 178

def distinct_values(_column)
  raise NotImplementedError
end

#enums ⇒ Hash{String => Hash}

Returns enum definitions.

Returns:

  • (Hash{String => Hash}) —

    Enum name to values mapping

Raises:

  • (NotImplementedError) 


44
45
46
 
# File 'lib/iron_admin/adapters/base.rb', line 44

def enums
  raise NotImplementedError
end

#filter(_scope, _column, _value) ⇒ Object

Filters a scope by a column value.

Parameters:

  • scope (Object) —

    The current query scope

  • column (Symbol) —

    Column name

  • value (Object) —

    Filter value

Returns:

  • (Object) —

    Filtered scope

Raises:

  • (NotImplementedError) 


146
147
148
 
# File 'lib/iron_admin/adapters/base.rb', line 146

def filter(_scope, _column, _value)
  raise NotImplementedError
end

#find(_id) ⇒ Object

Finds a record by primary key.

Parameters:

  • id (Integer, String) —

    The record ID

Returns:

  • (Object) —

    The record

Raises:

  • (NotImplementedError) 


123
124
125
 
# File 'lib/iron_admin/adapters/base.rb', line 123

def find(_id)
  raise NotImplementedError
end

#find_by(_attrs) ⇒ Object?

Finds a record by attributes.

Parameters:

  • attrs (Hash) —

    Attribute conditions

Returns:

  • (Object, nil) —

    The record or nil

Raises:

  • (NotImplementedError) 


130
131
132
 
# File 'lib/iron_admin/adapters/base.rb', line 130

def find_by(_attrs)
  raise NotImplementedError
end

#find_by_keys(attrs) ⇒ Object?

Finds a record by a configured import key.

Parameters:

  • attrs (Hash) —

    Attribute conditions

Returns:

  • (Object, nil) 


137
138
139
 
# File 'lib/iron_admin/adapters/base.rb', line 137

def find_by_keys(attrs)
  find_by(attrs)
end

#find_each(_scope) {|record| ... } ⇒ void

This method returns an undefined value.

Iterates records in memory-efficient batches.

Parameters:

  • scope (Object) —

    The current query scope

Yields:

  • (record) —

    Each record

Raises:

  • (NotImplementedError) 


289
290
291
 
# File 'lib/iron_admin/adapters/base.rb', line 289

def find_each(_scope, &)
  raise NotImplementedError
end

#has_column?(_name) ⇒ Boolean

Checks if a column exists.

Parameters:

  • name (Symbol, String) —

    Column name

Returns:

  • (Boolean)

Raises:

  • (NotImplementedError) 


38
39
40
 
# File 'lib/iron_admin/adapters/base.rb', line 38

def has_column?(_name) # rubocop:disable Naming/PredicatePrefix
  raise NotImplementedError
end

#human_name ⇒ String

Human-readable model name (e.g., "User"). Uses ActiveModel::Naming (available on both AR and Mongoid models).

Returns:

  • (String) 


94
95
96
 
# File 'lib/iron_admin/adapters/base.rb', line 94

def human_name
  model_class.model_name.human
end

#limit(_scope, _max) ⇒ Object

Limits a scope to N records.

Parameters:

  • scope (Object) —

    The current query scope

  • max (Integer) —

    Max records

Returns:

  • (Object) —

    Limited scope

Raises:

  • (NotImplementedError) 


163
164
165
 
# File 'lib/iron_admin/adapters/base.rb', line 163

def limit(_scope, _max)
  raise NotImplementedError
end

#order_by(_scope, _column, _direction) ⇒ Object

Orders a scope by column and direction.

Parameters:

  • scope (Object) —

    The current query scope

  • column (Symbol, String) —

    Column name

  • direction (Symbol) —

    :asc or :desc

Returns:

  • (Object) —

    Ordered scope

Raises:

  • (NotImplementedError) 


155
156
157
 
# File 'lib/iron_admin/adapters/base.rb', line 155

def order_by(_scope, _column, _direction)
  raise NotImplementedError
end

#pagy_method ⇒ Symbol

Returns the Pagy backend method name for this adapter.

Returns:

  • (Symbol) —

    :pagy or :pagy_mongoid

Raises:

  • (NotImplementedError) 


317
318
319
 
# File 'lib/iron_admin/adapters/base.rb', line 317

def pagy_method
  raise NotImplementedError
end

#pluck(_scope, _column) ⇒ Array

Extracts a single column from a scope.

Parameters:

  • scope (Object) —

    The current query scope

  • column (Symbol) —

    Column name

Returns:

  • (Array) —

    Column values

Raises:

  • (NotImplementedError) 


186
187
188
 
# File 'lib/iron_admin/adapters/base.rb', line 186

def pluck(_scope, _column)
  raise NotImplementedError
end

#polymorphic_inverse_classes(_polymorphic_name) ⇒ Array<Class>

Returns model/document classes that declare an inverse association for a polymorphic belongs_to name.

Parameters:

  • _polymorphic_name (Symbol)

Returns:

  • (Array<Class>) 


78
79
80
 
# File 'lib/iron_admin/adapters/base.rb', line 78

def polymorphic_inverse_classes(_polymorphic_name)
  []
end

#preload(_scope, _association_names) ⇒ Object

Eager loads associations on a scope.

Parameters:

  • scope (Object) —

    The current query scope

  • association_names (Array<Symbol>) —

    Associations to preload

Returns:

  • (Object) —

    Scope with preloading

Raises:

  • (NotImplementedError) 


171
172
173
 
# File 'lib/iron_admin/adapters/base.rb', line 171

def preload(_scope, _association_names)
  raise NotImplementedError
end

#primary_key ⇒ String+

Primary key column name(s) for the underlying model. Returns a String for single-column keys (e.g. "id", "slug") and an Array for composite keys (e.g. ["account_id", "scope_id"]).

Returns:

  • (String, Array<String>) 


108
109
110
 
# File 'lib/iron_admin/adapters/base.rb', line 108

def primary_key
  "id"
end

#query_builder_class ⇒ Class

Returns the query builder class for operator-based filters.

Returns:

  • (Class) —

    A QueryBuilder subclass

Raises:

  • (NotImplementedError) 


311
312
313
 
# File 'lib/iron_admin/adapters/base.rb', line 311

def query_builder_class
  raise NotImplementedError
end

#record_changes(_record) ⇒ Hash

Returns the changes hash after a save/update.

Parameters:

  • record (Object) —

    The record

Returns:

  • (Hash) —

    Changed attributes

Raises:

  • (NotImplementedError) 


298
299
300
 
# File 'lib/iron_admin/adapters/base.rb', line 298

def record_changes(_record)
  raise NotImplementedError
end

#resource_name ⇒ String

URL-friendly plural resource name (e.g., "users"). Uses ActiveModel::Naming (available on both AR and Mongoid models).

Returns:

  • (String) 


87
88
89
 
# File 'lib/iron_admin/adapters/base.rb', line 87

def resource_name
  model_class.model_name.plural
end

#rich_text_attributes ⇒ Array<Symbol>

Returns ActionText rich text attribute names.

Returns:

  • (Array<Symbol>)

Raises:

  • (NotImplementedError) 


70
71
72
 
# File 'lib/iron_admin/adapters/base.rb', line 70

def rich_text_attributes
  raise NotImplementedError
end

#save(_record) ⇒ Boolean

Persists a record.

Parameters:

  • record (Object) —

    The record to save

Returns:

  • (Boolean) —

    Success

Raises:

  • (NotImplementedError) 


228
229
230
 
# File 'lib/iron_admin/adapters/base.rb', line 228

def save(_record)
  raise NotImplementedError
end

#search_column(_scope, _column, _query) ⇒ Object

Searches a single column with LIKE/ILIKE.

Parameters:

  • scope (Object) —

    The current query scope

  • column (Symbol, String) —

    Column to search

  • query (String) —

    Search term

Returns:

  • (Object) —

    Filtered scope

Raises:

  • (NotImplementedError) 


203
204
205
 
# File 'lib/iron_admin/adapters/base.rb', line 203

def search_column(_scope, _column, _query)
  raise NotImplementedError
end

#search_columns(_scope, _columns, _query) ⇒ Object

Searches multiple columns with OR logic.

Parameters:

  • scope (Object) —

    The current query scope

  • columns (Array<Symbol>) —

    Columns to search

  • query (String) —

    Search term

Returns:

  • (Object) —

    Filtered scope

Raises:

  • (NotImplementedError) 


212
213
214
 
# File 'lib/iron_admin/adapters/base.rb', line 212

def search_columns(_scope, _columns, _query)
  raise NotImplementedError
end

#table_name ⇒ String?

Database table name (or nil for non-SQL backends).

Returns:

  • (String, nil)

Raises:

  • (NotImplementedError) 


100
101
102
 
# File 'lib/iron_admin/adapters/base.rb', line 100

def table_name
  raise NotImplementedError
end

#transaction { ... } ⇒ Object

Wraps a block in a transaction.

Yields:

  • The block to run atomically

Returns:

  • (Object) —

    Block return value

Raises:

  • (NotImplementedError) 


269
270
271
 
# File 'lib/iron_admin/adapters/base.rb', line 269

def transaction(&)
  raise NotImplementedError
end

#unscope_column(_scope, _column) ⇒ Object

Removes a WHERE condition on a specific column from a scope.

Parameters:

  • scope (Object) —

    The current query scope

  • column (Symbol) —

    Column to unscope

Returns:

  • (Object) —

    Scope without the column condition

Raises:

  • (NotImplementedError) 


279
280
281
 
# File 'lib/iron_admin/adapters/base.rb', line 279

def unscope_column(_scope, _column)
  raise NotImplementedError
end

#update(_record, _attrs) ⇒ Boolean

Updates a record's attributes.

Parameters:

  • record (Object) —

    The record

  • attrs (Hash) —

    New attributes

Returns:

  • (Boolean) —

    Success

Raises:

  • (NotImplementedError) 


236
237
238
 
# File 'lib/iron_admin/adapters/base.rb', line 236

def update(_record, _attrs)
  raise NotImplementedError
end

#update_record(record, attrs) ⇒ Boolean

Updates a record and returns true when persistence succeeds.

Parameters:

  • record (Object) —

    The record

  • attrs (Hash) —

    New attributes

Returns:

  • (Boolean) 


253
254
255
 
# File 'lib/iron_admin/adapters/base.rb', line 253

def update_record(record, attrs)
  update(record, attrs)
end

#wrap_rollback { ... } ⇒ void

This method returns an undefined value.

Executes a block, converting IronAdmin::Rollback to the adapter-native rollback.

Yields:

  • The block to run

Raises:

  • (NotImplementedError) 


305
306
307
 
# File 'lib/iron_admin/adapters/base.rb', line 305

def wrap_rollback(&)
  raise NotImplementedError
end