Designs for 2.0 base class

[jhollinger]

As discussed elsewhere, one option for easing into 2.0 would be to allow a Blueprint to decide if it inherits from a 1.0 base class or a 2.0 one, allowing them to co-exist.

Open questions:

1. Pros/cons (i.e. should we do this?)
2. What would it look like?
3. How far should V2 be allowed to diverge?

[jhollinger]

What would it looks like?

We could do it flashy like ActiveRecord migrations:

class MyBlueprint < Blueprinter[2.0]
  ...
end

Or in a more boring, obvious way (sometimes boring is good):

class MyBlueprint < Blueprinter::V2
  ...
end

[lessthanjacob]

I was initially more of a proponent of the Blueprint[2.0] syntax, but I think it'd boil down on how these versioned base classes would be implemented moving forward. There's an opportunity to leverage the .[] syntax to dynamically add/extend functionality:

module Blueprinter
  class Blueprint
    class << self
      # Returns the base Blueprint class corresponding to the provided version.
      #
      # @param version [String] The version of the Blueprint class to return.
      # @return [Blueprinter::Base] The base Blueprint class.
      def [](version)
        case version
        when '2.1'
          Blueprint.include(
            Renderer,
            ...
          )
        when '2.0'
          Blueprint 
        else
          Base
        end
      end
    end
  end
end

This certainly starts heading towards "over-engineering" territory, but if functionality is super composable we could potentially version bits of functionality separately in the future.

Otherwise, I'd lean more towards just a static V2 class.

[ritikesh]

Just an FYI -

If we allow multiple versions of blueprinter base classes in the same code as below-

class WidgetBlueprintOld < Blueprinter[2.1]
end

class WidgetBlueprintNew < Blueprinter[2.0]
end

the following wouldn't work -

Blueprint.include(
  Renderer,
  ...
)

This will update the base class for all the blueprints.

[jhollinger]

How far should V2 be allowed to diverge?

A share-nothing approach (at least for the public API) would allow for more innovation. But if it's too different, it could hamper adoption.

[jhollinger]

Here's an extreme (but elegant, IMHO) example of a V2 blueprint that removes the distinction between "blueprints" and "views" for a much simpler and more flexible implementation.

Here, a "view" is just an anonymous subclass of the blueprint. We get inheritance of fields, extensions, etc. basically for free from Ruby. No messy tracking of current_view inside the DSL, no separate View or ViewCollection classes - it's just inherited class methods operating on self all the way down!

class WidgetBlueprint < Blueprinter::V2
  field :name
  association :parts, PartBlueprint

  # an anonymous subclass of WidgetBlueprint, inheriting fields, etc.
  view :extended do
    field :summary
    association :parts, PartBlueprint[:extended]

    # nested views are subclasses of their parent views, inheriting their fields, etc.
    view :plus do
      field :description
    end
  end
end

# Render the main view
WidgetBlueprint.render({foo: "bar"})
WidgetBlueprint[:default].render({foo: "bar"})

# Render a child view
WidgetBlueprint[:extended].render({foo: "bar"})

# Render a nested child view
WidgetBlueprint[:extended][:plus].render({foo: "bar"})

# Since views are part of the class hierarchy, a Blueprint can inherit from one.
# The semantics are identical to `view` - it's just a named class instead of anonymous.
class SpecialWidgetBlueprint < WidgetBlueprint[:extended][:plus]
   ...
end

# The implementation is startlingly simple
module Blueprinter
  class V2
    class << self
      attr_accessor :views, :fields, :extensions, :view_path
    end

    self.views = {}
    self.fields = {}
    self.extensions = []
    self.view_path = []

    # initialize subclass
    def self.inherited(subclass)
      subclass.views = {default: subclass}
      subclass.fields = fields.dup
      subclass.extensions = extensions.dup
      subclass.view_path = subclass.name ? [subclass.name] : view_path.dup
    end

    # access a child view
    def self.[](view)
      views.fetch(view)
    end

    # define a new child view, which is a subclass of self
    def self.view(name, &definition)
      views[name] = Class.new(self)
      views[name].view_path << name
      views[name].class_eval(&definition)
      views[name]
    end

    # add a field
    def self.field(name, options = {})
      fields[name] = "TODO"
    end

    # add an association
    def self.association(name, blueprint, options = {})
      fields[name] = "TODO"
    end

    # show something descriptive, not "#<Class:0x0000000103e7a500>"
    def self.inspect
      view_path.join ":"
    end

    def self.to_s
      inspect
    end

    def self.render(obj, options = {})
      new.render(obj, options)
    end

    def render(obj, options = {})
      # Here, I suspect we'd call an external Render module/class, passing in self, obj, and options.
      "Rendering #{obj}"
    end
  end
end

[lessthanjacob]

This is incredibly clever, and would be a huge win if we could simplify view handling as a byproduct!

[jhollinger]

Draft PR #437

[ritikesh]

views[name].class_eval(&definition) - this part scares me a bit TBH, as it's open for any kind of patching of the blueprinter classes/objects - this is where people often shoot themselves on the foot a lot with messy implementations that can potentially wield weird ruby magic? classic examples could be calling of global methods/objects etc within the view definitions, or defining custom methods etc

[jhollinger]

@ritikesh I can see your point - our internal API would be exposed for easy use/misuse. I think that's true of most DSL though, our current one included. The class_eval doesn't increase the exposed area much, because you can still call internal methods at the top level/default view.

That said...this seemed like a fun challenge, so I mocked something up. It blocks any unapproved methods in both the main class body and in the views. A clever Rubyist could still find a way around it, but it would look pretty hacky.