nice_partials 0.1.1 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ace03ad5f6583df5b8545c3045f72c606a1cfbef879913633d9e2ef4f38a3fb0
-  data.tar.gz: e7284461cae24a294fb95b5517f0b639793e4802307903dea3a8014a9c1f6ebc
+  metadata.gz: d42a736129588d106251452b5d8357a54b610105302f7fddd25d4658211f6b1b
+  data.tar.gz: 66788e79de27fbddefaaef582dc4768bb3bd9a4e50eb43dd306c5c39919dac08
 SHA512:
-  metadata.gz: 60b93b1de86b5031f2b91f7d9c2f9461bba4511ebf7a33fb6d6b6d7f32f07d49793b1e6aa55543013fb3fb2ad88a8e5d915797e25605609560b409b9786cb9e1
-  data.tar.gz: 93a6f1a3db7ed2221fdf0f343e612872c3dda91de4115210d67352fd216fd7eb404b9daa5c34ee398cc6c332b4f173c5d6803be07b8696e0df4250358340f28f
+  metadata.gz: 0dfd842004c659c711e34675fd57a555e75dba71dd73990f73b1b8a37071c93e0ac8441b4248100b0faf6d930a70216e5d927b5aa9692ee13be9ffc6fc3507ff
+  data.tar.gz: 65c451b1ddca8dab4bc9d523e6d9f14095c33cfe59df34f321b724445c60ab68e4aab23c26fd153929d48d5dfdad351cc230a0a0cb7970de32410e078e380bfd

data/.gitignore

@@ -1,2 +1,3 @@
 Gemfile.lock
 /pkg
+*~

data/.travis.yml

@@ -2,6 +2,7 @@ sudo: false
 language: ruby
 
 rvm:
+- 3.0
 - 2.7
 - 2.6
 - 2.5

data/CHANGELOG.md

@@ -1,5 +1,8 @@
 ## CHANGELOG
 
+* Rely on `ActiveSupport.on_load :action_view`
+* Add support for Ruby 3.0
+
 ### 0.1.0
 
 * Initial release

data/README.md

@@ -1,82 +1,139 @@
 # nice_partials [![[version]](https://badge.fury.io/rb/nice_partials.svg)](https://badge.fury.io/rb/nice_partials)  [![[travis]](https://travis-ci.org/andrewculver/nice_partials.svg)](https://travis-ci.org/andrewculver/nice_partials)
 
-Nice Partials provides a light layer of magic on top of traditional Rails view partials to try and make them an even better fit for extracting and reusing components in your views. Nice Partials is specifically designed to be a lightweight and more Rails-native alternative to [ViewComponent](http://viewcomponent.org) that hopefully provides many of the same benefits while requiring less ceremony. This specific approach originated with [Bullet Train](https://bullettrain.co)'s "Field Partials" and was later reimagined and reimplemented by Dom Christie.
+Nice Partials extends the concept of [`content_for` blocks and `yield`](https://guides.rubyonrails.org/layouts_and_rendering.html#using-the-content-for-method) for those times when a partial needs to provide one or more named "content areas" or "slots". This thin, optional layer of magic helps make traditional Rails view partials an even better fit for extracting components from your views, like so:
 
+`app/views/components/_card.html.erb`:
+```html+erb
+<div class="card">
+  <%= p.yield :image %>
+  <div class="card-body">
+    <h5 class="card-title"><%= title %></h5>
+    <% if p.content_for? :body %>
+      <p class="card-text">
+        <%= p.yield :body %>
+      </p>
+    <% end %>
+  </div>
+</div>
+```
 
-## Benefits
+These partials can still be utilized with a standard `render` call, but you can specify how to populate the content areas like so:
 
- - They're just partials like you're used to, with a few extra features.
- - Less context switching. Your components are all just rendering in the standard view context.
- - You don't have to upgrade your existing partials. You can still nest them in a Nice Partials content area.
- - Less ceremony. You _can_ spin up a custom class to back your partial if you want to, but you don't have to by default, and we don't suggest it.
- - Instead, skip the component class entirely! You can define appropriately scoped helpers right inline with your partial.
- - It's still testable. There's no reason why these can't be as testable as ViewComponents.
+```html+erb
+<%= render 'components/card', title: 'Some Title' do |p| %>
+  <% p.content_for :body do %>
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
+    tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
+    <strong>quis nostrud exercitation ullamco laboris</strong> nisi ut aliquip
+    ex ea commodo consequat.
+  <% end %>
 
+  <% p.content_for :image do %>
+    <%= image_tag image_path('example.jpg'), alt: 'An example image' %>
+  <% end %>
+<% end %>
+```
 
-## Setup
+Nice Partials is a lightweight and hopefully more Rails-native alternative to [ViewComponent](http://viewcomponent.org). It aims to provide many of the same benefits as ViewComponent while requiring less ceremony. This specific approach originated with [Bullet Train](https://bullettrain.co)'s "Field Partials" and was later reimagined and completely reimplemented by Dom Christie.
 
-Add to your `Gemfile`:
 
-```ruby
-gem "nice_partials"
-```
+## Sponsored By
 
+<a href="https://bullettrain.co" target="_blank">
+  <img src="https://github.com/CanCanCommunity/cancancan/raw/develop/logo/bullet_train.png" alt="Bullet Train" width="400"/>
+</a>
+<br/>
+<br/>
 
-## Usage
+> Would you like to support Nice Partials development and have your logo featured here? [Reach out!](http://twitter.com/andrewculver)
 
-### Defining a Nice Partial
 
-We'll define an example Nice Partial in `app/views/partials/card`. We start by invoking Nice Partials like so:
+## Benefits of Nice Partials
 
-```
-<% yield p = np %>
-```
+Compared to something more heavy-handed, Nice Partials:
 
-We can explain what each thing is doing there later, but just trust us that it's the minimum viable invocation that we're aware of at the moment.
+ - is just regular Rails view partials like you're used to.
+ - reduces the friction when extracting components.
+ - only ends up in the specific partials you need its functionality in.
+ - reduces context switching.
+ - allows isolated helper logic alongside your partial view code.
+ - doesn't require any upgrades to existing partials for interoperability.
+ - are still testable!
 
-After that, you can define your partial content and define your content areas:
 
-```
+## Can't I do the same thing without Nice Partials?
+
+You can almost accomplish the same thing without Nice Partials, but in practice you end up having to flush the content buffers after using them, leading to something like this:
+
+```html+erb
 <div class="card">
-  <%= p.yield :image %>
+  <%= yield :image %>
+  <% content_for :image, flush: true do '' end %>
   <div class="card-body">
     <h5 class="card-title"><%= title %></h5>
-    <p class="card-text">
-      <%= p.yield :body %>
-    </p>
+    <% if content_for? :body %>
+      <p class="card-text">
+        <%= yield :body %>
+        <% content_for :body, flush: true do '' end %>
+      </p>
+    <% end %>
   </div>
 </div>
 ```
 
-That's it!
+Earlier iterations of Nice Partials aimed to simply clean up this syntax with helper methods like `flush_content_for`, but because the named content buffers were in a global namespace, it was also possible to accidentally create situations where two partials with a `:body` content area would end up interfering with each other, depending on the order they're nested and rendered.
 
-### Utilizing a Nice Partial
+Nice Partials resolves the last-mile issues with standard view partials and content buffers by introducing a small, generic object that helps transparently namespace your named content buffers. This same object can also be used to define helper methods specific to your partial that are isolated from the global helper namespace.
 
-To use a Nice Partial, just render it like you would any other partial, but also pass a block that accepts a parameter:
 
-```ruby
-<%= render 'partials/card', title: 'Some Title' do |p| %>
-  <% p.content_for :body %>
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
-    Ut enim ad minim veniam, <strong>quis nostrud exercitation ullamco laboris</strong> nisi ut aliquip ex ea commodo consequat.
-  <% end %>
+## Setup
 
-  <% p.content_for :image %>
-    <%= image_tag image_path('example.jpg'), alt: 'An example image' %>
-  <% end %>
-<% end %>
+Add to your `Gemfile`:
+
+```ruby
+gem "nice_partials"
 ```
 
-### Defining and Using Well Isolated Helper Methods
+## Usage
+
+### When to use Nice Partials
+
+You only need to use Nice Partials when:
+
+ - you want to define one or more named content areas in your partial. If you don't have multiple named content areas in your partial, you could just pass your content into the partial using the standard block and `yield` approach.
 
-To minimize the amount of pollution in the global helper namespace, you can define helper methods specifically for your partials _within your partial_ like so:
+ - you want to specifically isolate your helper methods for a specific partial.
 
+### Use Nice Partials in a partial
+
+To invoke nice partials, start your partial file with the following:
+
+```html+erb
+<% yield p = np %>
 ```
+
+Here's what is happening here:
+
+  - `yield` executes the block we receive when someone uses our partial.
+  - `np` fetches an instance of the generic class that helps isolate our content buffers and helper methods.
+  - `p = np` ensures we have a reference to that object in this partial.
+  - `yield p = np` ensures the developer using this partial also has a reference to that object, so they can define what goes in the various content buffers.
+
+(This is, [as far as we know](https://github.com/bullet-train-co/nice_partials/issues/1), the minimum viable invocation.)
+
+Once you've done this at the top of your partial file, you can then use `<%= p.yield :some_section %>` to render whatever content areas you want to be passed into your partial.
+
+
+### Defining and using well isolated helper methods
+
+To minimize the amount of pollution in the global helper namespace, you can use the shared context object to define helper methods specifically for your partials _within your partial_ like so:
+
+```html+erb
 <% p.helpers do
 
   # references should be a link if the user can drill down, otherwise just a text label.
-  # (this method has access to the scope of the entire view context and all the other helpers that come with it.)
   def reference_to(user)
+    # look! this method has access to the scope of the entire view context and all the other helpers that come with it!
     if can? :show, user
       link_to user.name, user
     else
@@ -89,10 +146,18 @@ end %>
 
 Then later in the partial you can use the helper method like so:
 
-```
+```html+erb
 <td><%= p.reference_to(user) %></td>
 ```
 
+## Development
+
+### Testing
+
+```sh
+bundle exec rake test
+```
+
 ## MIT License
 
 Copyright (C) 2020 Andrew Culver <https://bullettrain.co> and Dom Christie <https://domchristie.co.uk>. Released under the MIT license.

data/Rakefile

@@ -30,8 +30,8 @@ end
 # # #
 # Run specs
 
-desc "#{gemspec.name} | Spec"
-task :spec do
-  sh "for file in spec/*_spec.rb; do ruby $file; done"
+desc "#{gemspec.name} | Test"
+task :test do
+  sh "for file in test/*_test.rb; do ruby $file; done"
 end
-task default: :spec
+task default: :test

data/lib/nice_partials/helper.rb

@@ -4,4 +4,22 @@ module NicePartials::Helper
   def np
     NicePartials::Partial.new(self)
   end
+
+  def nice_partials_push_t_prefix(prefix)
+    @_nice_partials_t_prefixes ||= []
+    @_nice_partials_t_prefixes << prefix
+  end
+
+  def nice_partials_pop_t_prefix
+    @_nice_partials_t_prefixes ||= []
+    @_nice_partials_t_prefixes.pop
+  end
+
+  def t(key, options = {})
+    if @_nice_partials_t_prefixes&.any? && key.first == '.'
+      key = "#{@_nice_partials_t_prefixes.last}#{key}"
+    end
+
+    super(key, **options)
+  end
 end

data/lib/nice_partials/monkey_patch.rb

@@ -0,0 +1,52 @@
+# Monkey patch required to make `t` work as expected. Is this evil?
+# TODO Do we need to monkey patch other types of renderers as well?
+class ActionView::PartialRenderer
+  alias_method :original_render, :render
+
+  # See `content_for` in `lib/nice_partials/partial.rb` for something similar.
+  def render(partial, context, block)
+    if block
+      partial_prefix = nice_partials_locale_prefix_from_view_context_and_block(context, block)
+      context.nice_partials_push_t_prefix partial_prefix
+    else
+      # Render partial calls with no block should disable any prefix magic.
+      context.nice_partials_push_t_prefix ''
+    end
+
+    result = original_render(partial, context, block)
+
+    # Whether there was a block or not, pop off whatever we put on the stack.
+    context.nice_partials_pop_t_prefix
+
+    return result
+  end
+
+  # This and ActionView::Template#render below are for compatibility
+  # with Ruby 3, as opposed to altering the original functionality.
+  def render_partial_template(view, locals, template, layout, block)
+    ActiveSupport::Notifications.instrument(
+      "render_partial.action_view",
+      identifier: template.identifier,
+      layout: layout && layout.virtual_path
+    ) do |payload|
+      content = template.render(view, locals, ActionView::OutputBuffer.new, {add_to_stack: !block}) do |*name|
+        view._layout_for(*name, &block)
+      end
+
+      content = layout.render(view, locals) { content } if layout
+      payload[:cache_hit] = view.view_renderer.cache_hits[template.virtual_path]
+      build_rendered_template(content, template)
+    end
+  end
+end
+
+class ActionView::Template
+  def render(view, locals, buffer = ActionView::OutputBuffer.new, flag = {add_to_stack: true}, &block)
+    instrument_render_template do
+      compile!(view)
+      view._run(method_name, self, locals, buffer, **flag, &block)
+    end
+  rescue => e
+    handle_render_error(view, e)
+  end
+end

data/lib/nice_partials/partial.rb

@@ -1,5 +1,7 @@
 module NicePartials
   class Partial
+    delegate_missing_to :@view_context
+
     def initialize(view_context)
       @view_context = view_context
       @key = SecureRandom.uuid
@@ -14,8 +16,24 @@ module NicePartials
       class_eval &block
     end
 
+    # See the `ActionView::PartialRenderer` monkey patch in `lib/nice_partials/monkey_patch.rb` for something similar.
     def content_for(name, content = nil, options = {}, &block)
-      @view_context.content_for("#{name}_#{@key}".to_sym, content, options, &block)
+      if block_given?
+        partial_prefix = nice_partials_locale_prefix_from_view_context_and_block(@view_context, block)
+        @view_context.nice_partials_push_t_prefix(partial_prefix)
+      end
+
+      result = @view_context.content_for("#{name}_#{@key}".to_sym, content, options, &block)
+
+      if block_given?
+        @view_context.nice_partials_pop_t_prefix
+      end
+
+      return result
+    end
+
+    def content_for?(name)
+      @view_context.content_for?("#{name}_#{@key}".to_sym)
     end
   end
 end

data/lib/nice_partials/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module NicePartials
-  VERSION = "0.1.1"
+  VERSION = "0.1.5"
 end

data/lib/nice_partials.rb

@@ -2,9 +2,19 @@
 
 require_relative "nice_partials/version"
 require_relative "nice_partials/helper"
-require_relative "partials"
+require_relative "nice_partials/monkey_patch"
 
 module NicePartials
 end
 
-ActionView::Base.send :include, NicePartials::Helper
+# TODO Is there somewhere better we can put this?
+def nice_partials_locale_prefix_from_view_context_and_block(context, block)
+  root_paths = context.view_renderer.lookup_context.view_paths.map(&:path)
+  partial_location = block.source_location.first.dup
+  root_paths.each { |path| partial_location.gsub!(/^#{path}\//, '') }
+  partial_location.split('.').first.gsub('/_', '/').gsub('/', '.')
+end
+
+ActiveSupport.on_load :action_view do
+  include NicePartials::Helper
+end

data/nice_partials.gemspec

@@ -17,5 +17,9 @@ Gem::Specification.new do |gem|
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.require_paths = ["lib"]
 
-  gem.required_ruby_version = "~> 2.0"
+  gem.required_ruby_version = ">= 2.0"
+
+  gem.add_dependency "actionview", '>= 4.2.6'
+
+  gem.add_development_dependency "rails"
 end

data/test/fixtures/_basic.html.erb

@@ -0,0 +1,2 @@
+<% yield p = np %>
+<%= p.yield :message %>

data/test/fixtures/_card.html.erb

@@ -0,0 +1,13 @@
+<% yield p = np %>
+
+<div class="card">
+  <%= p.yield :image %>
+  <div class="card-body">
+    <h5 class="card-title"><%= title %></h5>
+    <% if p.content_for? :body %>
+      <p class="card-text">
+        <%= p.content_for :body %>
+      </p>
+    <% end %>
+  </div>
+</div>

data/test/fixtures/card_test.html.erb

@@ -0,0 +1,9 @@
+<%= render "card", title: "Some Title" do |p| %>
+  <% p.content_for :body do %>
+    Lorem Ipsum
+  <% end %>
+
+  <% p.content_for :image do %>
+    <img src="https://example.com/image.jpg" />
+  <% end %>
+<% end %>

data/test/renderer_test.rb

@@ -0,0 +1,57 @@
+require_relative "./test_helper"
+
+class RendererTest < ActiveSupport::TestCase
+  # from actionview/render_test
+  class TestController < ActionController::Base
+  end
+ 
+  def setup_view(paths)
+    ActionView::Base.include(NicePartials::Helper)
+
+    @assigns = { secret: "in the sauce" }
+
+    @view = Class.new(ActionView::Base.with_empty_template_cache) do
+      def view_cache_dependencies; []; end
+
+      def combined_fragment_cache_key(key)
+        [:views, key]
+      end
+    end.with_view_paths(paths, @assigns)
+
+    controller = TestController.new
+    controller.perform_caching = true
+    controller.cache_store = :memory_store
+    @view.controller = controller
+
+    @controller_view = controller.view_context_class.with_empty_template_cache.new(
+      controller.lookup_context,
+      controller.view_assigns,
+      controller)
+  end
+
+  def setup
+    ActionView::LookupContext::DetailsKey.clear
+    path = ActionView::FileSystemResolver.new(FIXTURE_LOAD_PATH)
+    view_paths = ActionView::PathSet.new([path])
+    assert_equal ActionView::FileSystemResolver.new(FIXTURE_LOAD_PATH), view_paths.first
+    setup_view(view_paths)
+  end
+
+  def teardown
+    ActionController::Base.view_paths.map(&:clear_cache)
+  end
+
+  test "render basic nice partial" do
+    rendered = @view.render("basic") { |p| p.content_for :message, "hello from nice partials" }.squish
+
+    assert_equal "hello from nice partials", rendered
+  end
+
+  test "render nice partial in card template" do
+    rendered = @view.render(template: "card_test").squish
+
+    assert_match "Some Title", rendered
+    assert_match "Lorem Ipsum", rendered
+    assert_match "https://example.com/image.jpg", rendered
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,7 @@
+require "active_support"
+require "active_support/testing/autorun"
+require "action_controller"
+require "action_view"
+require "nice_partials"
+
+FIXTURE_LOAD_PATH = File.expand_path("fixtures", __dir__)

metadata

@@ -1,16 +1,44 @@
 --- !ruby/object:Gem::Specification
 name: nice_partials
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.5
 platform: ruby
 authors:
 - Andrew Culver
 - Dom Christie
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-12-02 00:00:00.000000000 Z
-dependencies: []
+date: 2021-11-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actionview
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.2.6
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.2.6
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: A little bit of magic to make partials perfect for components.
 email:
 - andrew.culver@gmail.com
@@ -29,22 +57,26 @@ files:
 - Rakefile
 - lib/nice_partials.rb
 - lib/nice_partials/helper.rb
+- lib/nice_partials/monkey_patch.rb
 - lib/nice_partials/partial.rb
 - lib/nice_partials/version.rb
-- lib/partials.rb
 - nice_partials.gemspec
-- spec/nice_partials_spec.rb
+- test/fixtures/_basic.html.erb
+- test/fixtures/_card.html.erb
+- test/fixtures/card_test.html.erb
+- test/renderer_test.rb
+- test/test_helper.rb
 homepage: https://github.com/bullet-train-co/nice_partials
 licenses:
 - MIT
 metadata: {}
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - "~>"
+  - - ">="
     - !ruby/object:Gem::Version
       version: '2.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
@@ -53,9 +85,13 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.8
-signing_key:
+rubygems_version: 3.0.3
+signing_key: 
 specification_version: 4
 summary: A little bit of magic to make partials perfect for components.
 test_files:
-- spec/nice_partials_spec.rb
+- test/fixtures/_basic.html.erb
+- test/fixtures/_card.html.erb
+- test/fixtures/card_test.html.erb
+- test/renderer_test.rb
+- test/test_helper.rb

data/lib/partials.rb

@@ -1,2 +0,0 @@
-module Partials
-end

data/spec/nice_partials_spec.rb

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "../lib/nice_partials"
-require "minitest/autorun"
-
-describe NicePartials do
-  it "works" do
-    assert_equal true, false
-  end
-end
-