Module: Card::Set::Event::Api

Included in:
Card::Set
Defined in:
card/lib/card/set/event.rb

Overview

Events are the building blocks of the three transformative card actions: create, update, and delete.

(The fourth kind of action, read, does not transform cards, and is associated with views, not events).

As described in detail in Director, each act can have many actions, each action has three phases, each phase has three stages, and each stage has many events.

Events are defined in set modules in mods. Learn more about set modules.

A simple event definition looks something like this:

event :append_you_know, :prepare_to_validate, on: :create do
  self.content = content + ", you know?"
end

Note:

  • :append_you_know is a unique event name.
  • :prepare_to_validate is a stage.
  • on: :create specifies the action to which the event applies
  • self, within the event card, is a card object.

Any card within the set on which this event is defined will run this event during the prepare_to_validate stage when it is created.

Events should not be defined within format blocks.

Constant Summary collapse

OPTIONS = 
{
  on: %i[create update delete save read],
  changed: Card::Dirty.dirty_options,
  changing: Card::Dirty.dirty_options,
  skip: [:allowed],
  trigger: [:required],
  when: nil
}.freeze

Instance Method Summary collapse

Instance Method Details

#event(event, stage_or_opts = {}, opts = {}, &final) ⇒ Object

Define an event for a set of cards.

Parameters:

  • event (Symbol) —

    unique event name

  • stage_or_opts (Symbol, Hash) (defaults to: {}) —

    if a Symbol, defines event’s stage. If a Hash, it’s treated as the opts param.

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

    event options

Options Hash (opts):

  • :on (Symbol, Array) —

    one or more actions in which the event should be executed. :save is shorthand for [:create, :update]. If no value is specified, event will fire on create, update, and delete.

  • :changed (Symbol, Array) —

    fire event only if field has changed. valid values: name, content, db_content, type, type_id, left_id, right_id, codename, trash.

  • :changing (Symbol, Array) —

    alias for :changed

  • :skip (Symbol) —

    allow actions to skip this event. (eg. skip: :allowed)

  • :trigger (Symbol) —

    allow actions to trigger this event explicitly. If trigger: :required, then event will not run unless explicitly triggered.

  • :when (Symbol, Proc) —

    method (Symbol) or code (Proc) to execute to determine whether to fire event. Proc is given card as argument.

  • :before (Symbol) —

    fire this event before the event specified.

  • :after (Symbol) —

    fire this event after the event specified.

  • :around (Symbol) —

    fire this event before the event specified. This event will receive a block and will need to call it for the specified event to fire.

  • :stage (Symbol) —

    alternate representation for specifying stage

  • :after_subcards (True/False) —

    run event after running subcard events



72
73
74
 
# File 'card/lib/card/set/event.rb', line 72

def event event, stage_or_opts={}, opts={}, &final
  Event.new(event, self).register stage_or_opts, opts, &final
end