Module: Brainstem::Concerns::ControllerDSL::ClassMethods

Defined in:
lib/brainstem/concerns/controller_dsl.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#brainstem_params_context ⇒ Object

In order to correctly scope the DSL, we must have a context under which keys are stored. The default context is _default (to avoid any potential collisions with methods named ‘default’), and this context is used as the parent context for all other contexts.

The context will change, for example, when we are adding keys to the configuration for actions. In those cases, the context becomes the action_name.

Any methods that change the context should change it back upon conclusion so that the assumption of consistent scope inside a block is possible.



43
44
45
 
# File 'lib/brainstem/concerns/controller_dsl.rb', line 43

def brainstem_params_context
  @brainstem_params_context
end

Instance Method Details

#actions(*axns, &block) ⇒ Object

Invokes action for each symbol in the argument list. Used to specify shared configuration.



105
106
107
 
# File 'lib/brainstem/concerns/controller_dsl.rb', line 105

def actions(*axns, &block)
  axns.flatten.each { |name| action_context name, &block }
end

#brainstem_params(&block) ⇒ Object

Container method that sets up base scoping for the configuration.



49
50
51
52
53
 
# File 'lib/brainstem/concerns/controller_dsl.rb', line 49

def brainstem_params(&block)
  self.brainstem_params_context = DEFAULT_BRAINSTEM_PARAMS_CONTEXT
  class_eval(&block)
  self.brainstem_params_context = nil
end

#description(text, options = { nodoc: false }) ⇒ Object

Specifies a low-level description of a particular context, usually (but not exclusively) reserved for methods.

Setting the :nodoc option marks this description as ‘internal use only’, and causes formatters not to display a description.

Parameters:

  • text (String) —

    The description to set

  • options (Hash) (defaults to: { nodoc: false }) —

    options to record with the description

  • [Boolean] (Hash) —

    a customizable set of options



211
212
213
214
 
# File 'lib/brainstem/concerns/controller_dsl.rb', line 211

def description(text, options = { nodoc: false })
  configuration[brainstem_params_context][:description] = \
    options.merge(info: text)
end

#model_params(root = Proc.new { |klass| klass.brainstem_model_name }, &block) ⇒ Object

Allows the bulk specification of :root options. Useful for denoting parameters which are nested under a resource.

root may be specified as a string or symbol, which will represent the final root key.

However, root can also be specified as a Proc / callable object, in which case it is evaluated at format time, passed the controller constant. By default, if no argument is passed, it will return the controller’s brainstem_model_name dynamically.

We provide this functionality as a way to handle parameter inheritance in subclasses where the brainstem_model_name may not be the same as the parent class.



129
130
131
 
# File 'lib/brainstem/concerns/controller_dsl.rb', line 129

def model_params(root = Proc.new { |klass| klass.brainstem_model_name }, &block)
  with_options({ root: root.is_a?(Symbol) ? root.to_s : root }, &block)
end

#nodoc! ⇒ Object

Specifies that the scope should not be documented. Setting this on the default context will force the controller to be undocumented, whereas setting it within an action context will force that action to be undocumented.



62
63
64
 
# File 'lib/brainstem/concerns/controller_dsl.rb', line 62

def nodoc!
  configuration[brainstem_params_context][:nodoc] = true
end

#presents(target_class = :default, options = { nodoc: false }) ⇒ Object

Specifies which presenter is used for the controller / action. By default, expects presentation on all methods, and falls back to the class derived from brainstem_model_name if a name is not given.

Setting the :nodoc option marks this presenter as ‘internal use only’, and causes formatters to display this as not indicated.

Parameters:

  • target_class (Class) (defaults to: :default) —

    the target class of the presenter (i.e the model it presents)

  • options (Hash) (defaults to: { nodoc: false }) —

    options to record with the presenter

  • [Boolean] (Hash) —

    a customizable set of options



189
190
191
192
193
194
195
196
 
# File 'lib/brainstem/concerns/controller_dsl.rb', line 189

def presents(target_class = :default, options = { nodoc: false })
  raise "`presents` must be a class (in #{self.to_s})" \
    unless target_class.is_a?(Class) || target_class == :default || target_class.nil?

  target_class = brainstem_model_class if target_class == :default
  configuration[brainstem_params_context][:presents] = \
    options.merge(target_class: target_class)
end

#reset_configuration! ⇒ Object 



18
19
20
21
22
23
24
25
26
 
# File 'lib/brainstem/concerns/controller_dsl.rb', line 18

def reset_configuration!
  configuration.nest! :_default
  configuration[:_default].tap do |default|
    default.nest! :valid_params
    default.nest! :transforms
    default.nonheritable! :title
    default.nonheritable! :description
  end
end

#title(text, options = { nodoc: false }) ⇒ Object

Specifies a title to be used in the description of a class. Can also be used for method section titles.

Setting the :nodoc option marks this title as ‘internal use only’, and causes formatters to fall back to the controller constant or to the action name as appropriate. If you are trying to set the entire controller or action as nondocumentable, instead, use the discrete .nodoc! method in the desired context without a block.

Parameters:

  • text (String) —

    The title to set

  • options (Hash) (defaults to: { nodoc: false }) —

    options to record with the title

  • [Boolean] (Hash) —

    a customizable set of options



232
233
234
235
 
# File 'lib/brainstem/concerns/controller_dsl.rb', line 232

def title(text, options = { nodoc: false })
  configuration[brainstem_params_context][:title] = \
    options.merge(info: text)
end

#transform(transformations) ⇒ Object Also known as: transforms

Adds a transform to the list of transforms. Used to rename incoming params to their internal names for usage.

Examples:


brainstem_params do
  transform :param_from_frontend => :param_for_backend
end

Parameters:

  • transformations (Hash) —

    An old_param => new_param mapping.



164
165
166
167
168
169
 
# File 'lib/brainstem/concerns/controller_dsl.rb', line 164

def transform(transformations)
  transformations.each_pair do |k, v|
    transforms = configuration[brainstem_params_context][:transforms]
    transforms[k.to_sym] = v.to_sym
  end
end

#valid(field_name, options = { nodoc: false }) ⇒ Object

Adds a param to the list of valid params, storing the info sent with it.

Parameters:

  • field_name (Symbol) —

    the name of the param

  • options (Hash) (defaults to: { nodoc: false })

Options Hash (options):

  • :info (String) —

    the documentation for the param

  • :root (String, Symbol) —

    if this is a nested param, under which param should it be nested?

  • :nodoc (Boolean) —

    should this param appear in the documentation?



146
147
148
149
 
# File 'lib/brainstem/concerns/controller_dsl.rb', line 146

def valid(field_name, options = { nodoc: false })
  valid_params = configuration[brainstem_params_context][:valid_params]
  valid_params[field_name.to_sym] = options
end