module Card::Set::Format

Card::Set::Format is responsible for handling ‘format` blocks within the set module DSL, which is used in {Cardio::Mod Set module} files found in {Cardio::Mod mods’} set directories. Monkeys use the DSL to define views that apply to specific sets of cards in specific formats. The views can then be used by Monkeys in code and by Sharks via the UI.

For example, imagine you have a set module file in ‘mod/mymod/type/my_type.rb`. There you can define a view like this:

format :html do
  view :hello do
    greeting
  end
end

{AbstractFormat#view Learn more about defining views}

This view will now be available to MyType cards in HTML – but not in other formats. Similarly, you can define other methods in format blocks:

format :html do
  def greeting
    :rocks
  end
end

The magic that happens here is that the method greeting is now applicable (and available) only to the cards in the {Card::Set set} specified by the mod, and only when rendering a view of the card in the HTML format. {Card::Format Learn more about formats}.

So if, for example, I had a card “MyCard” with the type “MyType”, the following should use the method above:

““ “MyCard”.card.format(:html).greeting ““

…but if the card had a different type, or if I tried to use the method in, say, the JSON format, this beethoven method wouldn’t be available.

Under the hood, the DSL creates a ruby module that looks something like ‘Card::Set::Type::MyType::HtmlFormat`. This module will then be dynamically included in HTML format objects for MyCard.

As monkeys, we don’t usually think about all that much, because we work in the set module space, which lets us focus on the card patterns.

Speaking of which, there are a few key patterns to be aware of:

  1. Just as in {Card::Set sets}, format methods for narrower sets will override format methods for more general sets. So if a greeting method is defined for all cards and again for a specific card type, then the type method will override the all method when both apply.

  2. Similarly, specific formats inherit from more general formats, and all formats inherit from the base format. If a format is not specified, the format block will define methods on the base format class.

    format do
      def farewell
        "goodbye"
      end
    end
    
  3. It is possible to use super to refer to overridden methods. For example

        format :html do
          def goodbye
            "<em>#{super}</em>"
          end
        end
    
    Note: Set precedence has a higher priority than Format precedence.
  4. Some very powerful API calls (including {AbstractFormat#view view} and

{AbstractFormat#before before}) are defined in {AbstractFormat}. These methods are always available in format blocks.

  1. {#view} and {#before}, however, can ALSO both be called outside of a format

block. They will be defined on the base format.