2.0 Base Class Proposal

[jhollinger]

A proposed V2 base class.

Overview

• Combines concepts of "blueprint" and "view" (from Designs for 2.0 base class #430).
  • A view is just a subclass of the Blueprint.
  • A nested view is a sublcass of its parent view.
  • The :default view is just an alias to self (i.e. the Blueprint class).
• object = singular association, collection = multiple (names up for debate)
• Fields, partials, extensions, and options are inherited from the parent class/view, but can then be customized.
• Fields and associations are just structs.
• "Partials" can be defined and included in views.

Notes

• There's no MyBlueprint < Blueprinter[2.0] syntax in this PR, but we can add it later if we want.
• More options for views and fields/associations will need to be added in later PRs.

Defining

# "global" config goes here
class ApplicationBlueprint < Blueprinter::V2::Base
  extensions << MyExtension.new
  options[:exclude_nil] = true

  field :id
end

class MyBlueprint < ApplicationBlueprint
  field :name
  object :category, CategoryBlueprint

  # inherits from "default" view
  view :extended do
    exclude :name
    collection :widgets, WidgetBlueprint[:extended]

    # inherits from "extended" view
    view :plus do
      # Uses a legacy blueprint
      object :foo, LegacyFooBlueprint, view: :plus
    end
  end
end

# inherits from "MyBlueprint extended plus" view
class MyOtherBlueprint < MyBlueprint["extended.plus"]
  ...
end

# Much like in Rails, you can define partials for your views
class WidgetBlueprint < ApplicationBlueprint
  field :name

  partial :parts do
    # Defining fields is the obvious use-case
    collection :parts, WidgetPartBlueprint
    # But they can also use the full V2 API, including extensions, views and including other partials
    extensions << MyExt.new
  end

  view :foo do
    # Include the partial
    use :parts
    field :foo
  end

  view :bar do
    # Include the partial
    use :parts
    field :bar
  end
end

Rendering

# Render the default view
MyBlueprint.render(obj, opts)
MyBlueprint[:default].render(obj, opts)

# Render a named view
MyBlueprint[:extended].render(obj, opts)
MyBlueprint["extended"].render(obj, opts)

# Render a nested view
MyBlueprint["extended.plus"].render(obj, opts)
# which is syntactic sugar for:
MyBlueprint[:extended][:plus].render(obj, opts)

# Universal render call
view = "default" # or :foo, "foo.bar", :"foo.bar", etc
MyBlueprint[view].render(obj, opts)

# It COULD be made backwards-compatible, although I dislike the "Hash soup" approach.
# Maybe have this in 1.x to ease adoption then remove in 2.0?
MyBlueprint.render(obj, view: "extended.plus")

Reflection

# Here, default refers to MyBlueprint
MyBlueprint.reflections.keys
=> [:default, :extended, :"extended.plus"]

# If you reflect from a child view, the keys are relative
MyBlueprint[:extended].reflections.keys
=> [:default, :plus]

[jhollinger]

Alt view options:

WidgetBlueprint.render(obj, view: "extended.plus")
WidgetBlueprint["extended.plus"].render(obj)

[william-stacken]

What about extractor classes that could be provided to fields and associations? Is that something that is addressed in this PR?

blueprinter/lib/blueprinter/field.rb

Line 11 in b90d251

@extractor = extractor

We are currently using custom extractors to cache the values of extracted fields, and to detect infinite recursion while extracting a field (field references itself). See the related issue about extractor configurability.
#404

[jhollinger]

What about extractor classes that could be provided to fields and associations? Is that something that is addressed in this PR?

We're still looking at how we want to implement extractors, and a few other things, in V2. Those will be follow-up PRs.

[lessthanjacob]

I plan on giving this another thorough review, but I'm inclined to suggest that we try breaking this apart, and introduce each component separately, as there's a lot of new concepts at play here. I know we're merging into a release branch, but I believe it'd make it easier to break down iterate on moving forward.

[lessthanjacob]

Reading through this again with fresh eyes, I'm less inclined to want to codify the version as part of the class itself, especially since it doesn't quite describe what the class is as much.

The versioning system we were originally going with does seem over-engineered based on our current expectations, but I'm curious if we could have a more expressive name, and then introduce those versioning semantics later on if needed (e.g. class Blueprint -> Blueprint[3.0]).

Otherwise, I'd lean more towards BlueprintV2 if we want to stick with the explicit version in the name.

[jhollinger]

I've made V2 a module and moved this code to V2::Base for now.

[lessthanjacob]

nb: I'd expect DEFAULT_OPTIONS to be encapsulated solely within Options, and that simply calling Options.new would initialize it with the defaults.

[jhollinger]

For posterity (as discussed in the meeting): In my mind, the important part of this PR is the view/class inheritance structure and associated DSL. That is: how fields, associations, partials, options, and extensions are inherited from a parent class/view into child classes/views in a consistent, predictable manner, obviating the need for global config and unifying the "blueprint" and "view" concepts.

The included implementations of field, V2::Field, V2::Options etc are meant as starting points for follow up discussions and PRs. (Not to mention extension hooks, extractors, etc.) My suspicion is that we'll want to design the renderer/serializer sooner rather than later, and that will tell us a lot about how we'll want to handle those details.