props_template 1.0.0.alpha.3 → 1.0.0.alpha.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47eaa94bedc38645ef945eb7308cdc257497b063b5a9df481d491ec3bb1ae3ca
-  data.tar.gz: 48da4764807eb7924b224e98175f81c822a67e6ead927904df452d620d39e6e0
+  metadata.gz: dd22916bd76997bbac899cc2c7f3ee1dde0de4d757d508bde300c665fefffed2
+  data.tar.gz: 3ed18e6266e026ba545b5389cd70ebd215e825be1aa268afd3510a1c695a633f
 SHA512:
-  metadata.gz: 40c1e3bfc2c99a3b37834abec4e9b8463d4585203583f9f2f7ba710d775e714a7950bf1bf60f9d86b67c34de6742a5b5a0d249e0154fb50736288123e9ebb1e4
-  data.tar.gz: 70953db156e838cf72b220f9549c3a4abc6684d5bf0b0ad8a6305b15abf56cd1bd876635248fa2c8f1e43f21241475716d1dca49605fe65279951a8f2e59ed84
+  metadata.gz: e036c21457b476fb4554d7d5e5420a88659da3767750eaa70cabc05bd8f5c6924d23aaeb7e76e3640bf8d05558c2b6ac8e1eed9e4cf437d8f19e3960495cb199
+  data.tar.gz: cc7a63fc308d9b3c5e3c3c49286cf7c69e06d76eca3d51c04255eebf68c8158f44d76768396b1f0750adc204d0cae75dc7bfeb1cebd14e806bf690b50013f02e

data/README.md

@@ -36,7 +36,7 @@ json.menu do
   end
 end
 
-json.dashboard(defer: :auto) do
+json.dashboard(with.defer(:auto)) do
   sleep 5
   json.complexPostMetric 500
 end
@@ -46,7 +46,7 @@ json.posts do
   paged_posts = @posts.page(page_num).per(20)
 
   json.list do
-    json.array! paged_posts, key: :id do |post|
+    json.array! paged_posts, with.id_key(:id) do |post|
       json.id post.id
       json.description post.description
       json.commentsCount post.comments.count
@@ -59,8 +59,7 @@ json.posts do
   json.total @posts.count
 end
 
-json.footer partial: 'shared/footer' do
-end
+json.footer with.partial('shared/footer')
 ```
 
 ## Installation
@@ -96,13 +95,13 @@ You can also add a [layout](#layouts).
 Defines the attribute or structure. All keys are not formatted by default. See [Change Key Format](#change-key-format) to change this behavior.
 
 ```ruby
-json.set! :authorDetails, {...options} do
+json.set! :authorDetails, with.some_option do
   json.set! :firstName, 'David'
 end
 
 # or
 
-json.authorDetails, {...options} do
+json.authorDetails, with.some_option do
   json.firstName 'David'
 end
 
@@ -115,7 +114,7 @@ The inline form defines key and value
 | Parameter | Notes |
 | :--- | :--- |
 | key | A json object key|
-| value | A value |
+| value | A value or an [options][#options] object enabled with [partial](#partials)|
 
 ```ruby
 
@@ -133,7 +132,7 @@ The block form defines key and structure
 | Parameter | Notes |
 | :--- | :--- |
 | key | A json object key|
-| options | Additional [options](#options)|
+| options | Additional hash [options](#options) or a [options](#options) object|
 | block | Additional `json.set!`s or `json.array!`s|
 
 ```ruby
@@ -149,11 +148,12 @@ end
 ```
 
 The difference between the block form and inline form is
-  1. The block form is an internal node. Functionality such as Partials,
-  Deferment and other [options](#options) are only available on the
-  block form.
-  2. The inline form is considered a leaf node, and you can only [dig](#digging)
-  for internal nodes.
+
+1. Passing options as a [hash](#hash-options) is only available for the
+block form (also called an internal node)
+2. The inline form is considered a leaf node, if you need features like
+partials you may use [options](#options) objects only.
+3. Only internal nodes may dug for [digging](#digging)
 
 ### json.extract!
 Extracts attributes from object or hash in 1 line
@@ -189,7 +189,7 @@ Generates an array of json objects.
 collection = [ {name: 'john'}, {name: 'jim'} ]
 
 json.details do
-  json.array! collection, {...options} do |person|
+  json.array! collection, with.some_option do |person|
     json.firstName person[:name]
   end
 end
@@ -306,11 +306,29 @@ option.
 `application.json.props` when first running `rails superglue:install:web`
 
 ## Options
-Options Functionality such as Partials, Deferments, and Caching can only be
-set on a block. It is normal to see empty blocks.
+
+PropsTemplate provides a `with` helper to build a `Props::Option` object that enable
+functionality such as Partials, Deferments, and Caching
+
+The following are equivalent:
+
+```ruby
+json.post(with.partial('blog_post') 
+```
+
+or 
+
+```ruby
+json.post(Props::Options.new.partial('blog_post') 
+```
+### Hash options
+
+Previously, a normal hash was supported for internal nodes as long as an empty
+block accompanied the option. This option is still supported, but its
+recommended to use the `with` option builder.
 
 ```ruby
-json.post(partial: 'blog_post') do
+json.post(partial: 'blog_post', locals: {post: @post}) do
 end
 ```
 
@@ -321,8 +339,7 @@ Partials are supported. The following will render the file
 with @post, which you can use inside the partial.
 
 ```ruby
-json.one_post partial: ["posts/blog_post", locals: {post: @post}] do
-end
+json.one_post(with.partial("posts/blog_post", locals: {post: @post}))
 ```
 
 Usage with arrays:
@@ -332,8 +349,7 @@ Usage with arrays:
 # Without `as:` option you can use blog_post variable (name is based on partial's name) inside partial
 
 json.posts do
-  json.array! @posts, partial: ["posts/blog_post", locals: {foo: 'bar'}, as: 'post'] do
-  end
+  json.array! @posts, with.partial("posts/blog_post", locals: {foo: 'bar'}, as: 'post')
 end
 ```
 
@@ -344,16 +360,14 @@ cause performance problems. It's best used for things like a shared header or fo
 Do:
 
 ```ruby
-json.partial! partial: "header", locals: {user: @user} do
-end
+json.partial! with.partial("header", locals: {user: @user}) 
 ```
 
 or
 
 ```ruby
 json.posts do
-  json.array! @posts, partial: ["posts/blog_post", locals: {post: @post}] do
-  end
+  json.array! @posts, with.partial("posts/blog_post", locals: {post: @post})
 end
 ```
 
@@ -374,8 +388,7 @@ update cross cutting concerns like a header bar.
 
 ```ruby
 # index.json.props
-json.header partial: ["profile", fragment: "header"] do
-end
+json.header with.partial("profile").fragment("header")
 
 # _profile.json.props
 json.profile do
@@ -390,8 +403,7 @@ When using fragments with Arrays, the argument **MUST** be a lamda:
 ```ruby
 require 'props_template/core_ext'
 
-json.array! ['foo', 'bar'], partial: ["footer", fragment: ->(x){ x == 'foo'}] do
-end
+json.array! ['foo', 'bar'], with.partial("footer").fragment(->(x){ x == 'foo'})
 ```
 
 ### Caching
@@ -402,19 +414,18 @@ use [push_json](http://www.ohler.com/oj/doc/Oj/StringWriter.html#push_json-insta
 Usage:
 
 ```ruby
-json.author(cache: "some_cache_key") do
+json.author(with.cache("some_cache_key")) do
   json.firstName "tommy"
 end
 
 # or
 
-json.profile(cache: "cachekey", partial: ["profile", locals: {foo: 1}]) do
-end
+json.profile(with.cache("cachekey").partial("profile", locals: {foo: 1}))
 
 # or nest it
 
-json.author(cache: "some_cache_key") do
-  json.address(cache: "some_other_cache_key") do
+json.author(with.cache("some_cache_key")) do
+  json.address(with.cache("some_other_cache_key")) do
     json.zip 11214
   end
 end
@@ -425,7 +436,7 @@ When used with arrays, PropsTemplate will use `Rails.cache.read_multi`.
 ```ruby
 require 'props_template/core_ext'
 
-opts = { cache: ->(i){ ['a', i] } }
+opts = with.cache(->(i){ ['a', i] } )
 
 json.array! [4,5], opts do |x|
   json.top "hello" + x.to_s
@@ -433,7 +444,7 @@ end
 
 # or on arrays with partials
 
-opts = { cache: (->(d){ ['a', d.id] }), partial: ["blog_post", as: :blog_post] }
+opts = with.cache(->(d){ ['a', d.id] }).partial("blog_post", as: :blog_post)
 
 json.array! @options, opts do
 end
@@ -457,7 +468,7 @@ store.
 Usage:
 
 ```ruby
-json.dashboard(defer: :manual) do
+json.dashboard(with.defer(:manual)) do
   sleep 10
   json.someFancyMetric 42
 end
@@ -465,7 +476,7 @@ end
 
 # or you can explicitly pass a placeholder
 
-json.dashboard(defer: [:manual, placeholder: {}]) do
+json.dashboard(with.defer(:manual, placeholder: {})) do
   sleep 10
   json.someFancyMetric 42
 end
@@ -476,7 +487,7 @@ A auto option is available:
 **Note** This is a [SuperglueJS][1] specific functionality.
 
 ```ruby
-json.dashboard(defer: :auto) do
+json.dashboard(with.defer(:auto)) do
   sleep 10
   json.someFancyMetric 42
 end
@@ -514,11 +525,11 @@ data = [
 ]
 
 json.posts
-  json.array! data, key: :some_id do |item|
+  json.array! data, with.id_key(:some_id) do |item|
     # By using :key, props_template will append `json.some_id item.some_id`
     # automatically
 
-    json.contact(defer: :auto) do
+    json.contact(with.defer(:auto)) do
       json.address '123 example drive'
     end
   end
@@ -623,7 +634,10 @@ A single layout is supported. To use, create an `application.json.props` in
 ```ruby
 json.data do
   # template runs here.
-  yield json
+  _.call(json)
+  # NOTE: you can also use `yield json` instead, but prism sees this as
+  # a syntax error, so the `_.call(json)` is a workaround.
+  # See: https://github.com/thoughtbot/props_template/issues/58
 end
 
 json.header do

data/lib/props_template/base.rb

@@ -14,7 +14,7 @@ module Props
       @scope = nil
     end
 
-    def set_block_content!(options = {})
+    def set_content!(options = {})
       @scope = nil
       yield
       if @scope.nil?
@@ -26,7 +26,7 @@ module Props
     def handle_set_block(key, options)
       key = format_key(key)
       @stream.push_key(key)
-      set_block_content!(options) do
+      set_content!(options) do
         yield
       end
     end
@@ -64,7 +64,7 @@ module Props
     end
 
     def handle_collection_item(collection, item, index, options)
-      set_block_content!(options) do
+      set_content!(options) do
         yield
       end
     end
@@ -97,13 +97,20 @@ module Props
         raise InvalidScopeForArrayError.new("array! expects exclusive use of this block")
       end
 
-      if collection.nil?
-        @child_index = nil
-        yield
-      else
-        handle_collection(collection, options) do |item, index|
-          yield item, index
+      if block_given?
+        if collection.nil?
+          @child_index = nil
+          yield
+        else
+          handle_collection(collection, options) do |item, index|
+            yield item, index
+          end
         end
+      elsif options.is_a?(Props::Options)
+        options.valid_for_set!
+        handle_collection(collection, options) {}
+      else
+        raise ArgumentError.new("array! requires a block when no Props::Options object is given")
       end
 
       @scope = :array
@@ -147,7 +154,7 @@ module Props
       child_index += 1
 
       # this changes the scope to nil so child in a child will break
-      set_block_content!(options) do
+      set_content!(options) do
         yield
       end
 

data/lib/props_template/base_with_extensions.rb

@@ -26,7 +26,7 @@ module Props
       @traveled_path.join(".")
     end
 
-    def set_block_content!(options = {})
+    def set_content!(options = {})
       return super if !@em.has_extensions(options)
 
       @em.handle(options) do
@@ -51,11 +51,16 @@ module Props
     end
 
     def set!(key, options = {}, &block)
-      if block
+      if block || options.is_a?(Props::Options)
         options = @em.refine_options(options)
       end
 
-      super
+      if !block && options.is_a?(Props::Options)
+        options.valid_for_set!
+        super {}
+      else
+        super
+      end
     end
 
     def handle_set_block(key, options)

data/lib/props_template/extension_manager.rb

@@ -53,7 +53,7 @@ module Props
         @fragment.handle(options)
       else
         handle_cache(options) do
-          base.set_block_content! do
+          base.set_content! do
             if options[:partial]
               @fragment.handle(options)
               @partialer.handle(options)

data/lib/props_template/extensions/partial_renderer.rb

@@ -167,4 +167,3 @@ module Props
     end
   end
 end
-

data/lib/props_template/helper.rb

@@ -0,0 +1,7 @@
+module Props
+  module Helper
+    def with
+      Props::Options.new
+    end
+  end
+end

data/lib/props_template/options.rb

@@ -0,0 +1,39 @@
+module Props
+  class Options < Hash
+    class InvalidOptionError < StandardError; end
+
+    def partial(partial_name, opts = {})
+      self[:partial] = [partial_name, opts]
+      self
+    end
+
+    def defer(type, placeholder: {}, **opts)
+      self[:defer] = [type, {placeholder: placeholder}.merge(opts)]
+      self
+    end
+
+    def fragment(fragment)
+      raise "Fragment can't be defined without a partial. Please use `partial` first" if !self[:partial]
+
+      self[:partial][1][:fragment] = fragment
+      self
+    end
+
+    def cache(id_or_block)
+      return unless id_or_block
+
+      self[:cache] = id_or_block
+      self
+    end
+
+    def id_key(key_name)
+      self[:key] = key_name
+      self
+    end
+
+    def valid_for_set!
+      raise InvalidOptionError.new("Props::Options can't be empty") if empty?
+      raise InvalidOptionError.new("The partial option must be used with an inline `set!`") if !key?(:partial)
+    end
+  end
+end

data/lib/props_template/railtie.rb

@@ -6,6 +6,7 @@ module Props
     initializer :props_template do
       ActiveSupport.on_load :action_view do
         ActionView::Template.register_template_handler :props, Props::Handler
+        ActionView::Base.include Props::Helper
         require "props_template/dependency_tracker"
         require "props_template/layout_patch"
         require "props_template/partial_patch"

data/lib/props_template/searcher.rb

@@ -41,12 +41,12 @@ module Props
       [@found_block, @traveled_path, pass_opts, @fragment_path, fragment_context]
     end
 
-    def set_block_content!(*args)
+    def set_content!(*args)
       yield
     end
 
     def set!(key, options = {}, &block)
-      return if @found_block || !block
+      return if @found_block || !block && !options.is_a?(Props::Options)
 
       if @search_path[@depth] == key.to_s
         @traveled_path.push(key)

data/lib/props_template/version.rb

@@ -1,3 +1,3 @@
 module Props
-  VERSION = "1.0.0.alpha.3".freeze
+  VERSION = "1.0.0.alpha.4".freeze
 end

data/lib/props_template.rb

@@ -9,6 +9,8 @@ require "active_support/core_ext/string/output_safety"
 require "active_support/core_ext/array"
 require "props_template/searcher"
 require "props_template/handler"
+require "props_template/options"
+require "props_template/helper"
 require "props_template/version"
 
 require "active_support"
@@ -28,7 +30,7 @@ module Props
       :deferred!,
       :fragments!,
       :disable_deferments!,
-      :set_block_content!,
+      :set_content!,
       :traveled_path!,
       :fragment_context!,
       to: :builder!

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: props_template
 version: !ruby/object:Gem::Version
-  version: 1.0.0.alpha.3
+  version: 1.0.0.alpha.4
 platform: ruby
 authors:
 - Johny Ho
@@ -83,7 +83,9 @@ files:
 - lib/props_template/extensions/fragment.rb
 - lib/props_template/extensions/partial_renderer.rb
 - lib/props_template/handler.rb
+- lib/props_template/helper.rb
 - lib/props_template/layout_patch.rb
+- lib/props_template/options.rb
 - lib/props_template/partial_patch.rb
 - lib/props_template/railtie.rb
 - lib/props_template/searcher.rb