props_template 1.0.2 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d701cbf0bc05a74ec52fcab3e939b795bdb99eefc436b1bb5029d24deff16aac
-  data.tar.gz: da5e8ab92010fcf43d147cd677527024904fa57a0914f17737cccdf81e014bc5
+  metadata.gz: 3dc53f3b47d33c98b7fc04e82ef1bcc711529a30c5631627ba2bbd55eeb47ded
+  data.tar.gz: 4c13c7771bfc1ef0d2a2848b0c24d03f029f47751625f18151c23702d0a42376
 SHA512:
-  metadata.gz: 4a0e09a2b3845cfb26a682f0fa4cde60bcfb156d671e96c8a0cba443bfcd65b30017202bd174e649055bc5b7971317b5b8bc9a60185721d4fc94adb48744a441
-  data.tar.gz: f4ad6bdd2ac66c9504ed79f0bc28b1a2a486432be47b31700b31783fa93d7c8d4826eeea33d4de1d00fc281b21345db5cc563e2e66d22282792d98a8fa9a03ec
+  metadata.gz: c08a1f263224c6b4902ac849d7bded7b8e22d4520f3520a82cf7eac231f645ee9109dc8ac95649e2b8f5695c369f71868687482802113712daa3b18cd261bfbe
+  data.tar.gz: 6b3b68733f7b740be73438aff7602d30919798aa2d7693bc36437b096ff1e88a4414d4e93618ca90a74627897f96bc8ec781f0e84718b79a5ac925096a829900

data/README.md

@@ -5,7 +5,7 @@ support for Russian-Doll caching, layouts, and can be queried by giving the
 root a key path.
 
 [![Build
-Status](https://circleci.com/gh/thoughtbot/props_template.svg?style=shield)](https://circleci.com/gh/thoughtbot/props_template)
+Status](https://github.com/thoughtbot/props_template/actions/workflows/build.yml/badge.svg)](https://github.com/thoughtbot/props_template/actions/workflows/build.yml)
 
 It's fast.
 
@@ -98,7 +98,7 @@ json.posts do
   end
 
   json.paginationPath posts_path
-  json.current pagedPosts.current_page
+  json.current paged_posts.current_page
   json.total @posts.count
 end
 
@@ -131,6 +131,12 @@ json.greetings "hello world"
 
 You can also add a [layout](#layouts).
 
+To generate `index` and `show` templates for a resource, use the generator:
+
+```
+rails g props:views Post title:string body:text
+```
+
 ## API
 
 ### json.set! or json.\<your key here\>
@@ -144,13 +150,13 @@ end
 
 # or
 
-json.authorDetails, with.some_option do
+json.authorDetails(with.some_option) do
   json.firstName 'David'
 end
 
 # or with hash options
 
-json.authorDetails, {...options} do
+json.authorDetails({...options}) do
   json.firstName 'David'
 end
 
@@ -163,7 +169,7 @@ The inline form defines key and value
 | Parameter | Notes |
 | :--- | :--- |
 | key | A json object key|
-| value | A value or an [options][#options] object enabled with [partial](#partials)|
+| value | A value or an [options](#options) object enabled with [partial](#partials)|
 
 ```ruby
 
@@ -268,7 +274,7 @@ class ObjectCollection < SimpleDelegator
 
   def member_by(attr, val)
     find do |ele|
-      ele[attr] == val
+      ele[attr.to_sym] == val
     end
   end
 end
@@ -296,7 +302,7 @@ class ApplicationRecord < ActiveRecord::Base
   end
 
   def self.member_by(attr, value)
-    find_by(Hash[attr, val])
+    find_by(Hash[attr, value])
   end
 end
 ```
@@ -309,6 +315,30 @@ json.array! Post.all do
 end
 ```
 
+#### json.child!
+
+To build an array of heterogeneous elements, call `json.array!` without a
+collection and add each element with `json.child!`:
+
+```ruby
+json.items do
+  json.array! do
+    json.child! do
+      json.title "first"
+    end
+
+    json.child! do
+      json.body "second"
+    end
+  end
+end
+
+# => {"items": [{"title": "first"}, {"body": "second"}]}
+```
+
+`json.child!` can be [dug](#digging) into by index, e.g. `items.1`, but not by
+attribute.
+
 #### **Array core extension**
 
 For convenience, PropsTemplate includes a core\_ext that adds these methods to
@@ -321,7 +351,7 @@ data = [
   {id: 2, name: 'bar'}
 ]
 
-json.posts
+json.posts do
   json.array! data do
     # ...
   end
@@ -337,11 +367,11 @@ may still need to implement `member_by`.
 Returns all deferred nodes used by the [deferment](#deferment) option.
 
 **Note** This is a [SuperglueJS][1] specific functionality and is used in
-`application.json.props` when first running `rails superglue:install:web`
+`application.json.props` when first running `rails g superglue:install`
 
 
 ```ruby
-json.deferred json.deferred!
+json.defers json.deferred!
 
 # => [{url: '/some_url?props_at=outer.inner', path: 'outer.inner', type: 'auto'}]
 ```
@@ -353,10 +383,12 @@ to fetch missing data in a second round trip.
 Returns all fragment nodes used by the [partial fragments](#partial-fragments)
 option.
 
-```ruby json.fragments json.fragments!  ```
+```ruby
+json.fragments json.fragments!
+```
 
 **Note** This is a [SuperglueJS][1] specific functionality and is used in
-`application.json.props` when first running `rails superglue:install:web`
+`application.json.props` when first running `rails g superglue:install`
 
 ## Options
 
@@ -366,13 +398,13 @@ functionality such as Partials, Deferments, and Caching
 The following are equivalent:
 
 ```ruby
-json.post(with.partial('blog_post') 
+json.post(with.partial('blog_post'))
 ```
 
 or 
 
 ```ruby
-json.post(Props::Options.new.partial('blog_post') 
+json.post(Props::Options.new.partial('blog_post'))
 ```
 ### Hash options
 
@@ -388,7 +420,7 @@ end
 ### Partials
 
 Partials are supported. The following will render the file
-`views/posts/_blog_posts.json.props`, and set a local variable `post` assigned
+`views/posts/_blog_post.json.props`, and set a local variable `post` assigned
 with @post, which you can use inside the partial.
 
 ```ruby
@@ -456,12 +488,14 @@ json.profile do
 end
 ```
 
-When using fragments with Arrays, the argument **MUST** be a lamda:
+When using fragments with Arrays, the argument can be a String, a Symbol, or a
+lambda that receives each item and returns the fragment name. Return `nil` to
+skip the fragment for that item:
 
 ```ruby
 require 'props_template/core_ext'
 
-json.array! ['foo', 'bar'], with.partial("footer").fragment(->(x){ x == 'foo'})
+json.array! ['foo', 'bar'], with.partial("footer").fragment(->(x){ "footer_#{x}" })
 ```
 
 ### Caching
@@ -557,6 +591,19 @@ Finally in your `application.json.props`:
 json.defers json.deferred!
 ```
 
+To render every deferred node in place (e.g. for a request that should get
+the full page), call `json.disable_deferments!` before the deferred nodes:
+
+```ruby
+json.disable_deferments!
+
+json.dashboard(with.defer(:auto)) do
+  json.someFancyMetric 42
+end
+
+# => {"dashboard": {"someFancyMetric": 42}}
+```
+
 #### Working with arrays
 The default behavior for deferments is to use the index of the collection to
 identify an element.
@@ -570,8 +617,10 @@ If you wish to use an attribute to identify the element. You must:
 your collection item, and is used for `defer: :auto` to generate a keypath for
 [SuperglueJS][1]. If you are NOT using SuperglueJS, you do not need to do this.
 
-2. Implement `member_at`, on the [collection](#jsonarray). This will be called
-by PropsTemplate to when [digging](#digging)
+2. Implement `member_by(attr, value)` on the [collection](#jsonarray). This will
+be called by PropsTemplate when [digging](#digging) with a path like
+`posts.id=1`. Note that `attr` is passed as a String and `value` is coerced
+with `to_i`, so only integer attribute values are supported.
 
 For example:
 
@@ -582,7 +631,7 @@ data = [
   {id: 2, name: 'bar'}
 ]
 
-json.posts
+json.posts do
   json.array! data, with.id_key(:some_id) do |item|
     # By using :key, props_template will append `json.some_id item.some_id`
     # automatically
@@ -686,7 +735,7 @@ The above will render:
 ```
 
 ## Layouts
-A single layout is supported. To use, create an `application.json.props` in
+To use a layout, create an `application.json.props` in
 `app/views/layouts`. Here's an example:
 
 ```ruby
@@ -712,6 +761,23 @@ json.flash flash.to_h
 **NOTE** PropsTemplate inverts the usual Rails rendering flow. PropsTemplate
 will render Layout first, then the template when `yield json` is used.
 
+### Partials with layouts
+
+Partials can also be rendered with a layout. The layout is itself a partial:
+
+```ruby
+# app/views/posts/_stream_message.json.props
+json.greeting "Hello world"
+
+json.data do
+  yield
+end
+```
+
+```ruby
+render partial: "comment", layout: "stream_message"
+```
+
 
 ### Layouts in API-only Rails apps
 
@@ -747,7 +813,7 @@ Props::BaseWithExtensions.class_eval do
   # json.second_value "second"
   #
   # -> { "firstValue" => "first", "second_value" => "second" }
-  def key_format(key)
+  def format_key(key)
     key.to_s
   end
 end
@@ -758,7 +824,7 @@ Props::BaseWithExtensions.class_eval do
   # json.second_value "second"
   #
   # -> { "firstValue" => "first", "secondValue" => "second" }
-  def key_format(key)
+  def format_key(key)
     @key_cache ||= {}
     @key_cache[key] ||= key.to_s.camelize(:lower)
     @key_cache[key]
@@ -777,7 +843,7 @@ Props::BaseWithExtensions.class_eval do
   # json.second_value "second"
   #
   # -> { "first_value" => "first", "second_value" => "second" }
-  def key_format(key)
+  def format_key(key)
     @key_cache ||= {}
     @key_cache[key] ||= key.to_s.underscore
     @key_cache[key]

data/lib/props_template/base.rb

@@ -36,7 +36,7 @@ module Props
     end
 
     def format_key(key)
-      key.to_s
+      (::Symbol === key) ? key.name : key.to_s
     end
 
     def set!(key, value = nil)
@@ -63,6 +63,21 @@ module Props
       nil
     end
 
+    def set_value!(key, value)
+      if @scope == :array
+        raise InvalidScopeForObjError.new("Attempted to set! on an array! scope")
+      end
+
+      if @scope.nil?
+        @scope = :object
+        @stream.push_object
+      end
+
+      @stream.push_value(value, format_key(key))
+
+      nil
+    end
+
     def handle_collection_item(collection, item, index, options)
       @item_context = item
 
@@ -124,7 +139,7 @@ module Props
           [value, value]
         end
 
-        set!(
+        set_value!(
           key,
           object.is_a?(Hash) ? object.fetch(attribute) : object.public_send(attribute)
         )

data/lib/props_template/base_with_extensions.rb

@@ -27,7 +27,7 @@ module Props
     end
 
     def set_content!(options = {})
-      return super if !@em.has_extensions(options)
+      return super if options.empty? || !@em.has_extensions(options)
 
       @em.handle(options, item_context) do
         yield
@@ -46,10 +46,6 @@ module Props
       @em = ExtensionManager.new(self, prev_state[1], prev_state[2])
     end
 
-    def format_key(key)
-      key.to_s
-    end
-
     def set!(key, options = {}, &block)
       if !block && options.is_a?(Props::Options)
         options.valid_for_set!

data/lib/props_template/searcher.rb

@@ -46,6 +46,10 @@ module Props
       yield
     end
 
+    def set_value!(key, value)
+      nil
+    end
+
     def set!(key, options = {}, &block)
       return if @found_block || !block && !options.is_a?(Props::Options)
 

data/lib/props_template/version.rb

@@ -1,3 +1,3 @@
 module Props
-  VERSION = "1.0.2".freeze
+  VERSION = "1.1.0".freeze
 end

data/lib/props_template.rb

@@ -67,8 +67,10 @@ module Props
           @builder.item_context = found_item
           set!(key, found_options, &found_block)
         end
-      else
+      elsif block || options.is_a?(Props::Options)
         @builder.set!(key, options, &block)
+      else
+        @builder.set_value!(key, options)
       end
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: props_template
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.1.0
 platform: ruby
 authors:
 - Johny Ho