nice_partials 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 80f4ce71d7a0d70adfd7f7c6775178df6705bd74fc520d7d81e1f28ab2b4b831
-  data.tar.gz: 37bfd17903477aad2e7cdfc2a0eb8a42a36749851e445be88c1172a013b58fba
+  metadata.gz: ace03ad5f6583df5b8545c3045f72c606a1cfbef879913633d9e2ef4f38a3fb0
+  data.tar.gz: e7284461cae24a294fb95b5517f0b639793e4802307903dea3a8014a9c1f6ebc
 SHA512:
-  metadata.gz: 44aeee28bb6aaa22fcb7f3021c49142d6c463ab7f72e083a73c0f0465a7dd96296e5a13271ea74e711ae4905d2f7deadfe89e1b12886c5af6332a3d75b8ce595
-  data.tar.gz: 90262c8cb7eafae7d7f0b88b4a36ac2e4e41acd1d3e78957e4a6016136b4f788de9d0cd274480774f0f63e9a81cc43e8b040ac980ce91bc0b343dfcd417387e2
+  metadata.gz: 60b93b1de86b5031f2b91f7d9c2f9461bba4511ebf7a33fb6d6b6d7f32f07d49793b1e6aa55543013fb3fb2ad88a8e5d915797e25605609560b409b9786cb9e1
+  data.tar.gz: 93a6f1a3db7ed2221fdf0f343e612872c3dda91de4115210d67352fd216fd7eb404b9daa5c34ee398cc6c332b4f173c5d6803be07b8696e0df4250358340f28f

data/README.md

@@ -1,6 +1,16 @@
 # 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)
 
-TODO
+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.
+
+
+## Benefits
+
+ - 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.
 
 
 ## Setup
@@ -14,9 +24,74 @@ gem "nice_partials"
 
 ## Usage
 
+### Defining a Nice Partial
+
+We'll define an example Nice Partial in `app/views/partials/card`. We start by invoking Nice Partials like so:
+
+```
+<% yield p = np %>
+```
+
+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.
+
+After that, you can define your partial content and define your content areas:
+
+```
+<div class="card">
+  <%= p.yield :image %>
+  <div class="card-body">
+    <h5 class="card-title"><%= title %></h5>
+    <p class="card-text">
+      <%= p.yield :body %>
+    </p>
+  </div>
+</div>
+```
+
+That's it!
+
+### Utilizing a Nice Partial
+
+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 %>
+
+  <% p.content_for :image %>
+    <%= image_tag image_path('example.jpg'), alt: 'An example image' %>
+  <% end %>
+<% end %>
+```
+
+### Defining and Using Well Isolated Helper Methods
+
+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:
+
 ```
+<% 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)
+    if can? :show, user
+      link_to user.name, user
+    else
+      object.name
+    end
+  end
+
+end %>
+```
+
+Then later in the partial you can use the helper method like so:
+
+```
+<td><%= p.reference_to(user) %></td>
+```
 
 ## MIT License
 

data/lib/nice_partials.rb

@@ -2,6 +2,7 @@
 
 require_relative "nice_partials/version"
 require_relative "nice_partials/helper"
+require_relative "partials"
 
 module NicePartials
 end

data/lib/nice_partials/helper.rb

@@ -1,23 +1,7 @@
+require_relative "partial"
+
 module NicePartials::Helper
   def np
-    # self in this context is the context of the view partial we're being called from.
-    DecoratedViewContext.new(self)
-  end
-
-  private
-  class DecoratedViewContext
-    def initialize(view_context)
-      @view_context = view_context
-      @key = SecureRandom.uuid
-    end
-
-    def yield(name = nil)
-      raise "You can only use Nice Partial's yield method to retrieve the content of named content area blocks. If you're not trying to fetch the content of a named content area block, you don't need Nice Partials! You can just call the vanilla Rails `yield`." unless name
-      content_for(name)
-    end
-
-    def content_for(name, content = nil, options = {}, &block)
-      @view_context.content_for("#{name}_#{@key}".to_sym, content, options, &block)
-    end
+    NicePartials::Partial.new(self)
   end
 end

data/lib/nice_partials/partial.rb

@@ -0,0 +1,21 @@
+module NicePartials
+  class Partial
+    def initialize(view_context)
+      @view_context = view_context
+      @key = SecureRandom.uuid
+    end
+
+    def yield(name = nil)
+      raise "You can only use Nice Partial's yield method to retrieve the content of named content area blocks. If you're not trying to fetch the content of a named content area block, you don't need Nice Partials! You can just call the vanilla Rails `yield`." unless name
+      content_for(name)
+    end
+
+    def helpers(&block)
+      class_eval &block
+    end
+
+    def content_for(name, content = nil, options = {}, &block)
+      @view_context.content_for("#{name}_#{@key}".to_sym, content, options, &block)
+    end
+  end
+end

data/lib/nice_partials/version.rb

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

data/lib/partials.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nice_partials
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Andrew Culver
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-12-01 00:00:00.000000000 Z
+date: 2020-12-02 00:00:00.000000000 Z
 dependencies: []
 description: A little bit of magic to make partials perfect for components.
 email:
@@ -29,7 +29,9 @@ files:
 - Rakefile
 - lib/nice_partials.rb
 - lib/nice_partials/helper.rb
+- lib/nice_partials/partial.rb
 - lib/nice_partials/version.rb
+- lib/partials.rb
 - nice_partials.gemspec
 - spec/nice_partials_spec.rb
 homepage: https://github.com/bullet-train-co/nice_partials