Module: Formalist::Element::ClassInterface

Included in:
Formalist::Element
Defined in:
lib/formalist/element/class_interface.rb

Overview

Class-level API for form elements.

Class Method Summary collapse

Class Method Details

.attribute(name, type, default: nil) ⇒ Object

Define a form element attribute.

Form element attributes can be set when the element is defined, and can be further populated by the form element object itself, when the form is being built, using both the user input and any dependencies passed to the element via the form.

Attributes are the way to ensure the form renderer has all the information it needs to render the element appropriately. Attributes are type-checked in order to ensure they’re being passed appropriate values. Attributes can hold any type of value as long as it can be reduced to an abstract syntax tree representation by ‘Form::Element::Attributes#to_ast`.

Parameters:

  • name (Symbol) —

    attribute name

  • type (Dry::Data::Type, #call) —

    value type coercer/checker

  • default (defaults to: nil) —

    default value (applied when the attribute is not explicitly populated)

Returns:

  • void

See Also:



51
52
53
 
# File 'lib/formalist/element/class_interface.rb', line 51

def attribute(name, type, default: nil)
  attributes(name => {type: type, default: default})
end

.attributes_schema ⇒ Hash<Symbol, Hash>

Returns the attributes schema for the form element.

Each item in the schema includes a type definition and a default value (nil if none specified).

Examples:

Formalist::Elements::Field.attributes_schema
# => {
  :name => {:type => #<Dry::Data::Type>, :default => "Default name"},
  :email => {:type => #<Dry::Data::Type>, :default => "default email"}
}

Returns:

  • (Hash<Symbol, Hash>) —

    the attributes schema



69
70
71
72
 
# File 'lib/formalist/element/class_interface.rb', line 69

def attributes_schema
  super_schema = superclass.respond_to?(:attributes_schema) ? superclass.attributes_schema : {}
  super_schema.merge(@attributes_schema || {})
end

.permitted_children(policy) ⇒ Object .permitted_children(element_type, ...) ⇒ Object .permitted_children ⇒ #permitted?

Sets or fetches the policy for the element’s permitted child form elements.

Overloads:

  • .permitted_children(policy) ⇒ Object

    Set a policy for whether the element permits child form elements.

    Specify :all to allow all children, or :none to permit no children.

    Examples:

    Permitting all children

    permitted_children :all

    Permitting no children

    permitted_children :none

    Returns:

    • void

  • .permitted_children(element_type, ...) ⇒ Object

    Permit the element to contain only the specified element types as children.

    Examples:

    permit_children :section, :field

    Parameters:

    • element_type (Symbol) —

      the name of a child element type to permit

    • ... (Symbol) —

      more child element types to permit

    Returns:

    • void

  • .permitted_children ⇒ #permitted?

    Returns the permitted child element types for the element.

    If no permitted_children policy was previously specified, then it allows all children by default.

    Returns:

    • (#permitted?) —

      permissions object.

    See Also:



111
112
113
114
115
116
117
118
119
 
# File 'lib/formalist/element/class_interface.rb', line 111

def permitted_children(*args)
  return @permitted_children ||= PermittedChildren.all if args.empty?

  @permitted_children = if %i[all none].include?(args.first)
    PermittedChildren.send(args.first)
  else
    PermittedChildren[args]
  end
end

.type ⇒ Symbol

Returns the element’s type, which is a symbolized, camlized representation of the element’s class name.

This is a critical hook for customising form rendering when using custom form elements, since the type in this case will be based on the name of form element’s sublass.

Examples:

Basic element

Formalist::Elements::Field.type # => :field

Custom element

class MyField < Formalist::Elements::Field
end

MyField.type # => :my_field

Returns:

  • (Symbol) —

    the element type.



26
27
28
 
# File 'lib/formalist/element/class_interface.rb', line 26

def type
  Inflecto.underscore(Inflecto.demodulize(name)).to_sym
end