Module: Alba::Resource::ClassMethods

Included in:
Alba::Resource
Defined in:
lib/alba/resource.rb

Overview

Class methods

Instance Method Summary collapse

Instance Method Details

#association(name, condition = nil, resource: nil, key: nil, params: {}, **options, &block) ⇒ void Also known as: one, many, has_one, has_many

This method returns an undefined value.

Set association

Parameters:

  • name (String, Symbol) —

    name of the association, used as key when ‘key` param doesn’t exist

  • condition (Proc, nil) (defaults to: nil) —

    a Proc to modify the association

  • resource (Class<Alba::Resource>, String, Proc, nil) (defaults to: nil) —

    representing resource for this association

  • key (String, Symbol, nil) (defaults to: nil) —

    used as key when given

  • params (Hash) (defaults to: {}) —

    params override for the association

  • options (Hash<Symbol, Proc>)
  • block (Block)

Options Hash (**options):

  • if (Proc) —

    a condition to decide if this association should be serialized

See Also:



373
374
375
376
377
378
379
 
# File 'lib/alba/resource.rb', line 373

def association(name, condition = nil, resource: nil, key: nil, params: {}, **options, &block)
  transformation = @_key_transformation_cascade ? @_transform_type : :none
  assoc = Association.new(
    name: name, condition: condition, resource: resource, params: params, nesting: nesting, key_transformation: transformation, helper: @_helper, &block
  )
  @_attributes[key&.to_sym || name.to_sym] = options[:if] ? ConditionalAttribute.new(body: assoc, condition: options[:if]) : assoc
end

#attribute(name, **options, &block) ⇒ void

This method returns an undefined value.

Set an attribute with the given block

Parameters:

  • name (String, Symbol) —

    key name

  • options (Hash<Symbol, Proc>)
  • block (Block) —

    the block called during serialization

Options Hash (**options):

  • if (Proc) —

    a condition to decide if this attribute should be serialized

Raises:

  • (ArgumentError) —

    if block is absent



355
356
357
358
359
 
# File 'lib/alba/resource.rb', line 355

def attribute(name, **options, &block)
  raise ArgumentError, 'No block given in attribute method' unless block

  @_attributes[name.to_sym] = options[:if] ? ConditionalAttribute.new(body: block, condition: options[:if]) : block
end

#attributes(*attrs, if: nil, **attrs_with_types) ⇒ void

This method returns an undefined value.

Set multiple attributes at once

Parameters:

  • attrs (Array<String, Symbol>)
  • if (Proc) (defaults to: nil) —

    condition to decide if it should serialize these attributes

  • attrs_with_types (Hash<[Symbol, String], [Array<Symbol, Proc>, Symbol]>) —

    attributes with name in its key and type and optional type converter in its value



321
322
323
324
325
 
# File 'lib/alba/resource.rb', line 321

def attributes(*attrs, if: nil, **attrs_with_types)
  if_value = binding.local_variable_get(:if)
  assign_attributes(attrs, if_value)
  assign_attributes_with_types(attrs_with_types, if_value)
end

#collection_key(key) ⇒ Object

Sets key for collection serialization

Parameters:

  • key (String, Symbol) 


471
472
473
 
# File 'lib/alba/resource.rb', line 471

def collection_key(key)
  @_collection_key = key.to_sym
end

#helper(mod = @_helper || Module.new, &block) ⇒ Object

Define helper methods

Parameters:

  • mod (Module) (defaults to: @_helper || Module.new) —

    a module to extend



508
509
510
511
512
 
# File 'lib/alba/resource.rb', line 508

def helper(mod = @_helper || Module.new, &block)
  mod.module_eval(&block) if block
  extend mod
  @_helper = mod
end

#layout(file: nil, inline: nil) ⇒ Object

Set layout

Parameters:

  • file (String) (defaults to: nil) —

    name of the layout file

  • inline (Proc) (defaults to: nil) —

    a proc returning JSON string or a Hash representing JSON



445
446
447
 
# File 'lib/alba/resource.rb', line 445

def layout(file: nil, inline: nil)
  @_layout = Layout.new(file: file, inline: inline)
end

#meta(&block) ⇒ Object

Set metadata



437
438
439
 
# File 'lib/alba/resource.rb', line 437

def meta(&block)
  @_meta = block
end

#nested_attribute(name, **options, &block) ⇒ void Also known as: nested

This method returns an undefined value.

Set a nested attribute with the given block

Parameters:

  • name (String, Symbol) —

    key name

  • options (Hash<Symbol, Proc>)
  • block (Block) —

    the block called during serialization

Options Hash (**options):

  • if (Proc) —

    a condition to decide if this attribute should be serialized

Raises:

  • (ArgumentError) —

    if block is absent



402
403
404
405
406
407
408
 
# File 'lib/alba/resource.rb', line 402

def nested_attribute(name, **options, &block)
  raise ArgumentError, 'No block given in attribute method' unless block

  key_transformation = @_key_transformation_cascade ? @_transform_type : :none
  attribute = NestedAttribute.new(key_transformation: key_transformation, &block)
  @_attributes[name.to_sym] = options[:if] ? ConditionalAttribute.new(body: attribute, condition: options[:if]) : attribute
end

#on_error(handler = nil, &block) ⇒ Object

Set error handler If this is set it’s used as a error handler overriding global one

Parameters:

  • handler (Symbol) (defaults to: nil) —

    ‘:raise`, `:ignore` or `:nullify`

  • block (Block)

Raises:

  • (ArgumentError) 


480
481
482
483
484
485
 
# File 'lib/alba/resource.rb', line 480

def on_error(handler = nil, &block)
  raise ArgumentError, 'You cannot specify error handler with both Symbol and block' if handler && block
  raise ArgumentError, 'You must specify error handler with either Symbol or block' unless handler || block

  @_on_error = block || validated_error_handler(handler)
end

#on_nil(&block) ⇒ Object

Set nil handler

Parameters:

  • block (Block) 


501
502
503
 
# File 'lib/alba/resource.rb', line 501

def on_nil(&block)
  @_on_nil = block
end

#prefer_object_method! ⇒ Object

DSL for alias, purely for readability



520
521
522
 
# File 'lib/alba/resource.rb', line 520

def prefer_object_method!
  alias_method :fetch_attribute_from_object_and_resource, :_fetch_attribute_from_object_first
end

#prefer_resource_method! ⇒ Object

DSL for alias, purely for readability



515
516
517
 
# File 'lib/alba/resource.rb', line 515

def prefer_resource_method!
  alias_method :fetch_attribute_from_object_and_resource, :_fetch_attribute_from_resource_first
end

#root_key(key, key_for_collection = nil) ⇒ Object

Set root key

Parameters:

  • key (String, Symbol)
  • key_for_collection (String, Symbol) (defaults to: nil)

Raises:

  • (NoMethodError) —

    when key doesn’t respond to ‘to_sym` method



416
417
418
419
 
# File 'lib/alba/resource.rb', line 416

def root_key(key, key_for_collection = nil)
  @_key = key.to_sym
  @_key_for_collection = key_for_collection&.to_sym
end

#root_key! ⇒ Object

Set root key to true



431
432
433
434
 
# File 'lib/alba/resource.rb', line 431

def root_key!
  @_key = true
  @_key_for_collection = true
end

#root_key_for_collection(key) ⇒ Object

Set root key for collection

Parameters:

  • key (String, Symbol)

Raises:

  • (NoMethodError) —

    when key doesn’t respond to ‘to_sym` method



425
426
427
428
 
# File 'lib/alba/resource.rb', line 425

def root_key_for_collection(key)
  @_key = true
  @_key_for_collection = key.to_sym
end

#transform_keys(type, root: true, cascade: true) ⇒ Object

Transform keys as specified type

Parameters:

  • type (String, Symbol) —

    one of ‘snake`, `:camel`, `:lower_camel`, `:dash` and `none`

  • root (Boolean) (defaults to: true) —

    decides if root key also should be transformed

  • cascade (Boolean) (defaults to: true) —

    decides if key transformation cascades into inline association Default is true but can be set false for old (v1) behavior

Raises:



456
457
458
459
460
461
462
463
464
465
466
 
# File 'lib/alba/resource.rb', line 456

def transform_keys(type, root: true, cascade: true)
  type = type.to_sym
  unless %i[none snake camel lower_camel dash].include?(type)
    # This should be `ArgumentError` but for backward compatibility it raises `Alba::Error`
    raise ::Alba::Error, "Unknown transform type: #{type}. Supported type are :camel, :lower_camel and :dash."
  end

  @_transform_type = type
  @_transforming_root_key = root
  @_key_transformation_cascade = cascade
end