diff --git a/README.md b/README.md index aa5366c..a7e1b1c 100644 --- a/README.md +++ b/README.md @@ -18,9 +18,13 @@ In automatic mode, every query (`ActiveRecord::Relation`) passed to a Blueprint Blueprinter.configure do |config| config.extensions << BlueprinterActiveRecord::Preloader.new(auto: true) end + +# Preloading will always happen during render +widgets = Widget.where(...).order(...) +json = WidgetBlueprint.render(widgets) ``` -If you'd prefer to use `includes` rather than `preload`, pass `use: :includes`. +If you'd prefer to use `includes` rather than `preload`, pass `use: :includes` to the initializer. ### Dynamic mode @@ -32,9 +36,14 @@ Blueprinter.configure do |config| # examine q, q.model, blueprint, view, or options and return true or false end end + +# If the above block returns true for q (widgets), preloading will happen during render +widgets = Widget.where(...).order(...) +json = WidgetBlueprint.render(widgets) + ``` -If you'd prefer to use `includes` rather than `preload`, pass `use: :includes`. +If you'd prefer to use `includes` rather than `preload`, pass `use: :includes` to the initializer. ### Manual mode @@ -128,35 +137,31 @@ association :children, blueprint: CategoryBlueprint, max_recursion: 20 ### Pass the *query* to render, not query *results* -If the query runs before being passed to render, no preloading can take place. +If the query runs _before_ being passed to `render`, it's too late for preloading to happen. ```ruby -# Oops - the query already ran :( -widgets = Widget.where(...).to_a -WidgetBlueprint.render(widgets, view: :extended) - -# Yay! :) widgets = Widget.where(...) +widgets.each { |widget| do_something wiget } +# too late to preload b/c the query already ran :( WidgetBlueprint.render(widgets, view: :extended) ``` -The query can also be an ActiveRecord::Associations::CollectionProxy: +But sometimes you have no choice. In those cases, manually call `preload_blueprint` and pass it the Blueprint/view. Then preloading will happen as soon as the query runs. ```ruby - project = Project.find(...) - WidgetBlueprint.render(project.widgets, view: :extended) +widgets = Widget. + where(...). + preload_blueprint(WidgetBlueprint, :extended) +# preloading will happen here, because it knows which Blueprint/view to look at +widgets.each { |widget| do_something wiget } +WidgetBlueprint.render(widgets, view: :extended) ``` -If you **must** run the query first, there is a way: +### Also works for ActiveRecord::Associations::CollectionProxy ```ruby -widgets = Widget. - where(...). - # preloading will happen HERE b/c we gave it all the info it needs - preload_blueprint(WidgetBlueprint, :extended). - to_a -do_something widgets -WidgetBlueprint.render(widgets, view: :extended) +project = Project.find(...) +WidgetBlueprint.render(project.widgets, view: :extended) ``` ### Use strict_loading to find hidden associations