props_template 0.13.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d1594043556583c84e0d4406165c623183b5843200c5fcdcac84f86ef7c30cc
-  data.tar.gz: 1b9cf4b6fa1accad65dee696ba8b3b998dc1f1687c1ef010980def63fceed882
+  metadata.gz: ad98bb076e592658c137fd423771b211760ba047a1f6f394efa7a531a25eedc5
+  data.tar.gz: f5495c4eca8b7015ac5d18714a10a16735769128fac62b5693824b1ef0c6e505
 SHA512:
-  metadata.gz: 25f9e1f56cead08969fa97f7b010059bfc073e67977c20d0b71977ada79a8282b9c037d8a9f9b3f744cfe48f09ae2a91e2442e2738433a124977bd04eea6d5eb
-  data.tar.gz: 0442331012ade9ae49c2adc2a34e2c4b2ac5d809030622334fb71ad98db221be1f8c1032e4c81d2874e519ab676fa467f333457124f92df24a710c4e0b5c1663
+  metadata.gz: 629b8dc24b25dc596ee6f2bb9d03abce69e5af292121d118a83e3d53b83f38ef7ccc155e4cc79d4469a6e588c2efa3231ac02b05447ed11aa6c4642fca833d6f
+  data.tar.gz: 83d0aed77e8cba7cf1730307f15a6fed2b972a181a1722c0dbba85a03489c12ca8b47f89b515e48f8a776564f3c35b58c6118be9396e0eb270c48cfbe21794c9

data/README.md

@@ -0,0 +1,517 @@
+# PropsTemplate
+
+PropsTemplate is a queryable JSON templating library inspired by JBuilder. It has support for layouts, partials, russian-doll caching, multi-fetch and can selectively render nodes in your tree without executing others.
+
+Example:
+
+```ruby
+json.flash flash.to_h
+
+json.menu do
+  # all keys will be formatted as camelCase
+
+  json.current_user do
+    json.email current_user.email
+    json.avatar current_user.avatar
+    json.inbox current_user.messages.count
+  end
+end
+
+json.dashboard(defer: :auto) do
+  sleep 5
+  json.complex_post_metric 500
+end
+
+json.posts do
+  page_num = params[:page_num]
+  paged_posts = @posts.page(page_num).per(20)
+
+  json.list do
+    json.array! paged_posts, key: :id do |post|
+      json.id post.id
+      json.description post.description
+      json.comments_count post.comments.count
+      json.edit_path edit_post_path(post)
+    end
+  end
+
+  json.pagination_path posts_path
+  json.current paged_posts.current_page
+  json.total @posts.count
+end
+
+
+json.footer partial: 'shared/footer' do
+end
+```
+
+## API
+
+### json.set! or json.<your key here>
+Defines the attribute or stucture. All keys are automatically camelized.
+
+```ruby
+json.set! :author_details, {..options...} do
+  json.set! :first_name, 'David'
+end
+
+or
+
+json.author_details, {..options...} do
+  json.first_name, 'David'
+end
+
+
+# => {"authorDetails": { "firstName": "David" }}
+```
+
+The inline form defines key and value
+
+| Parameter | Notes |
+| :--- | :--- |
+| key | A json object key|
+| value | A value |
+
+```ruby
+json.set! :first_name, 'David'
+
+or
+
+json.first_name 'David'
+
+# => { "firstName": "David" }
+```
+
+The block form defines key and structure
+
+| Parameter | Notes |
+| :--- | :--- |
+| key | A json object key|
+| options | Additional [options](#options)|
+| block | Additional `json.set!`s or `json.array!`s|
+
+```ruby
+json.set! :details do
+ ...
+end
+
+or
+
+json.details do
+ ...
+end
+```
+
+The difference between the block form and inline form is
+1. The block form is an internal node. Partials, Deferement and other [options](#options) are only available on the block form.
+2. The inline form is considered a leaf node, and you can only [search](#traversing) for internal nodes.
+
+### json.array!
+Generates an array of json objects.
+
+```ruby
+collection = [
+  {name: 'john'},
+  {name: 'jim'}
+]
+
+json.details do
+  json.array! collection, {....options...} do |person|
+    json.first_name person[:name]
+  end
+end
+
+# => {"details": [
+  {"firstName": 'john'},
+  {"firstName": 'jim'}
+]}
+```
+
+| Parameter | Notes |
+| :--- | :--- |
+| collection | A collection that responds to `member_at` and `member_by` |
+| options | Additional [options](#options)|
+
+To support [traversing nodes](react-redux.md#traversing-nodes), any list passed to `array!` MUST implement `member_at(index)` and `member_by(attr, value)`.
+
+For example, if you were using a delegate:
+
+```ruby
+class ObjectCollection < SimpleDelegator
+  def member_at(index)
+    at(index)
+  end
+
+  def member_by(attr, val)
+    find do |ele|
+      ele[attr] == val
+    end
+  end
+end
+```
+
+Then in your template:
+
+```ruby
+data = ObjectCollection.new([{id: 1, name: 'foo'}, {id: 2, name: 'bar'}])
+
+json.array! data do
+  ...
+end
+```
+
+Similarly for ActiveRecord:
+
+```ruby
+class ApplicationRecord < ActiveRecord::Base
+  def self.member_at(index)
+    offset(index).limit(1).first
+  end
+
+  def self.member_by(attr, value)
+    find_by(Hash[attr, val])
+  end
+end
+```
+
+Then in your template:
+
+```ruby
+json.array! Post.all do
+  ...
+end
+```
+
+#### **Array core extension**
+
+For convenience, PropsTemplate includes a core\_ext that adds these methods to `Array`. For example:
+
+```ruby
+require 'props_template/core_ext'
+data = [{id: 1, name: 'foo'}, {id: 2, name: 'bar'}]
+
+json.posts
+  json.array! data do
+    ...
+  end
+end
+```
+
+PropsTemplate does not know what the elements are in your collection. The example above will be fine for [traversing](props-template.md#traversing_nodes) by index `\posts?bzq=posts.0`, but will raise a `NotImplementedError` if you traverse by attribute `/posts?bzq=posts.id=1`. You may still need a delegate that implements `member_by`.
+
+### json.deferred!
+Returns all deferred nodes used by the [#deferment](#deferment) option.
+
+```ruby
+json.deferred json.deferred!
+```
+
+This method is normally used in `application.json.props` when first generated by `rails breezy:install:web`
+
+### json.fragments!
+Returns all fragment nodes used by the [partial fragments](#partial-fragments) option.
+
+```ruby
+json.fragments json.fragments!
+```
+
+This method is normally used in `application.json.props` when first generated by `rails breezy:install:web`
+
+### json.fragment_digest!
+
+Returns the digest of the current partial name and the locals passed. Useful for [optimistic updates](#optimistic-updates).
+
+```ruby
+# _some_partial.json.props
+
+json.digest json.fragment_digest!
+```
+
+## Options
+Functionality such as Partials, Deferements, and Caching can only be set on a block. It is normal to see empty blocks.
+
+```ruby
+json.post(partial: 'blog_post') do
+end
+```
+
+### Partials
+
+Partials are supported. The following will render the file `views/posts/_blog_posts.json.props`, and set a local variable `foo` assigned with @post, which you can use inside the partial.
+
+```ruby
+json.one_post partial: ["posts/blog_post", locals: {post: @post}] do
+end
+```
+
+Usage with arrays:
+
+```ruby
+# as an option on an array. The `as:` option is supported when using `array!`
+json.posts do
+  json.array! @posts, partial: ["posts/blog_post", locals: {foo: 'bar'}, as: 'post'] do
+  end
+end
+```
+
+### Partial Fragments
+
+A fragment uses a digest to identify a rendered partial across your page state in Redux. When BreezyJS recieves a payload with a fragment, it will update every fragment with the same digest in your Redux store.
+
+You would need use partials and add the option `fragment: true`.
+
+```ruby
+# index.json.props
+json.header partial: ["profile", fragment: true] do
+end
+
+# _profile.json.props
+json.profile do
+  json.address do
+    json.state "New York City"
+  end
+end
+```
+
+When using fragments with Arrays, the argument **MUST** be a lamda:
+
+```ruby
+require 'props_template/core_ext' #See (lists)[#Lists]
+
+json.array! ['foo', 'bar'], partial: ["footer", fragment: ->(x){ x == 'foo'}]
+```
+
+PropsTemplate creates a name for the partial using a digest of your locals, partial name, and globalId (to_json as fallback if there is no globalId) on objects that you pass. You may override this behavior and use a custom identifier:
+
+```ruby
+# index.js.breezy
+json.header partial: ["profile", fragment: 'me_header'] do
+end
+```
+
+#### Optimisitc Updates
+Breezy uses the digest generated by `fragment: true` to uniquely identify a partial across the redux state. If you need to optimistically update a fragment, use `json.fragment_digest!` to obtain the identifier in your partial, and `updateFragments` from BreezyJS.
+
+For example:
+
+```ruby
+# _header.js.props
+json.fragment_digest json.fragment_digest!
+```
+
+And in your reducer
+
+```javacript
+import {updateFragments} from 'jho406/Breezy';
+
+switch(action.type) {
+case SOME_ACTION: {
+  const {
+    fragmentDigest,
+    prevNode // <- the content of the _header.js.props
+  } = action.payload
+
+  const nextNode = {
+    ...prevNode,
+    foo: 'bar'
+  }
+
+  return updateFragments(state, {
+    [fragmentDigest]: nextNode
+  })
+}
+default:
+  return state
+}
+```
+
+### Caching
+Caching is supported on any node.
+
+Usage:
+
+```ruby
+json.author(cache: "some_cache_key") do
+  json.first_name "tommy"
+end
+
+#or
+
+json.profile(cache: "cachekey", partial: ["profile", locals: {foo: 1}]) do
+end
+
+#or nest it
+
+json.author(cache: "some_cache_key") do
+  json.address(cache: "some_other_cache_key") do
+    json.zip 11214
+  end
+end
+```
+
+When used with arrays, PropsTemplate will use `Rails.cache.read_multi`.
+
+```ruby
+require 'props_template/core_ext' #See (lists)[#Lists]
+
+opts = {
+  cache: ->(i){ ['a', i] }
+}
+json.array! [4,5], opts do |x|
+  json.top "hello" + x.to_s
+end
+
+#or on arrays with partials
+
+opts = {
+  cache: (->(d){ ['a', d.id] }),
+  partial: ["blog_post", as: :blog_post]
+}
+json.array! @options, opts
+```
+
+### Deferment
+
+You can defer rendering of expensive nodes in your content tree using the `defer: :auto` option. Behind the scenes PropsTemplates will no-op the block entirely, replace the value with `{}` as a placeholder.
+When the client recieves the payload, BreezyJS will use the meta data to issue a `remote` dispatch to fetch the missing node and immutibly graft it at the appropriate keypath in your Redux store.
+
+You can access what was deferred with `json.deferred!`. If you use the generators, this will be set up in `application.json.props`.
+
+Usage:
+
+```ruby
+json.dashboard(defer: :auto) do
+  sleep 10
+  json.some_fancy_metric 42
+end
+```
+
+A manual option is also available:
+
+```ruby
+json.dashboard(defer: :manual) do
+  sleep 10
+  json.some_fancy_metric 42
+end
+```
+
+Finally in your `application.json.props`:
+
+```ruby
+json.defers json.deferred!
+```
+
+
+If `:manual` is used, PropsTemplate will no-op the block and will not populate `json.deferred!`. Its up to you to [traverse](props-template.md#traversing_nodes) to fetch the node seperately. A common usecase would be tab content that does not load until you click the tab.
+
+#### Working with arrays
+The default behavior for deferements is to use the index of the collection to identify an element. PropsTemplate will generate `?_bzq=a.b.c.0.title` in its metadata.
+
+If you wish to use an attribute to identify the element. You must:
+1. Implement `:key` to specify which attribute you want to use to uniquely identify the element in the collection. PropsTemplate will generate `?_bzq=a.b.c.some_id=some_value.title`
+2. Implement `member_at`, and `member_key` on the collection to allow for BreezyJS to traverse the tree based on key value attributes.
+
+For example:
+
+```ruby
+require 'props_template/core_ext' #See (lists)[#Lists]
+
+data = [{id: 1, name: 'foo'}, {id: 2, name: 'bar'}]
+
+json.posts
+  json.array! data, key: :some_id do |item|
+    json.contact(defer: :auto) do
+      json.address '123 example drive'
+    end
+
+   # json.some_id item.some_id will be appended automatically to the end of the block
+  end
+end
+```
+
+When BreezyJS receives the response, it will automatically kick off `remote(?bzq=posts.some_id=1.contact)` and `remote(?bzq=posts.some_id=2.contact)`.
+
+# Traversing
+
+PropsTemplate has the ability to walk the tree you build, skipping execution of untargeted nodes. This feature is useful for partial updating your frontend state. See [traversing nodes](react-redux.md#traversing-nodes)
+
+```ruby
+traversal_path = ['data', 'details', 'personal']
+
+json.data(search: traversal_path) do
+  json.details do
+    json.employment do
+      ...more stuff...
+    end
+
+    json.personal do
+      json.name 'james'
+      json.zip_code 91210
+    end
+  end
+end
+
+json.footer do
+ ...
+end
+```
+
+PropsTemplate will will walk breath first, finds the matching key, executes the associated block, then repeats until it the node is found. The above will output the below:
+
+```json
+{
+  data: {
+    name: 'james',
+    zipCode: 91210
+  },
+  footer: {
+    ....
+  }
+}
+```
+
+Breezy's searching only works with blocks, and will NOT work with Scalars ("leaf" values). For example:
+
+```ruby
+traversal_path = ['data', 'details', 'personal', 'name'] <- not found
+
+json.data(search: traversal_path) do
+  json.details do
+    json.personal do
+      json.name 'james'
+    end
+  end
+end
+
+```
+
+## Nodes that do not exist
+
+Nodes that are not found will not define the key where search was enabled on.
+
+```ruby
+traversal_path = ['data', 'details', 'does_not_exist']
+
+json.data(search: traversal_path) do
+  json.details do
+    json.personal do
+      json.name 'james'
+    end
+  end
+end
+
+json.footer do
+ ...
+end
+
+```
+
+The above will render:
+
+```
+{
+  footer: {
+    ...
+  }
+}
+```

data/lib/props_template/base_with_extensions.rb

@@ -78,23 +78,15 @@ module Props
     end
 
     def handle_collection_item(collection, item, index, options)
-      if collection.respond_to? :member_key
-        member_key = collection.member_key
-      end
-
-      if !member_key
+      if !options[:key]
         @traveled_path.push(index)
       else
-        id = if item.respond_to? member_key
-          item.send(member_key)
-        elsif item.is_a? Hash
-          item[member_key] || item[member_key.to_sym]
-        end
+        id, val = options[:key]
 
         if id.nil?
           @traveled_path.push(index)
         else
-          @traveled_path.push("#{member_key.to_s}=#{id}")
+          @traveled_path.push("#{id.to_s}=#{val}")
         end
       end
 
@@ -110,6 +102,16 @@ module Props
 
 
     def refine_item_options(item, options)
+      if key = options[:key]
+        val = if item.respond_to? key
+          item.send(key)
+        elsif item.is_a? Hash
+          item[key] || item[key.to_sym]
+        end
+
+        options[:key] = [options[:key], val]
+      end
+
       @em.refine_options(options, item)
     end
   end

data/lib/props_template/extension_manager.rb

@@ -43,7 +43,7 @@ module Props
     end
 
     def has_extensions(options)
-      options[:defer] || options[:cache] || options[:partial]
+      options[:defer] || options[:cache] || options[:partial] || options[:key]
     end
 
     def handle(commands, options)
@@ -64,6 +64,11 @@ module Props
             else
               yield
             end
+
+            if options[:key]
+              id, val = options[:key]
+              base.set!(id, val)
+            end
           end
         end
       end

data/lib/props_template/extensions/deferment.rb

@@ -35,6 +35,12 @@ module Props
       type, rest = options[:defer]
       placeholder = rest[:placeholder]
 
+      if type.to_sym == :auto && options[:key]
+        key, val = options[:key]
+        placeholder = {}
+        placeholder[key] = val
+      end
+
       request_path = @base.context.controller.request.fullpath
       path = @base.traveled_path.join('.')
       uri = ::URI.parse(request_path)

data/lib/props_template/layout_patch.rb

@@ -18,9 +18,9 @@ module Props
     def render_props_template(view, template, path, locals)
       layout_locals = locals.dup
       layout_locals.delete(:json)
+      layout_locals[:virtual_path_of_template] = template.virtual_path
 
-      layout = resolve_props_layout(path, layout_locals, [formats.first])
-
+      layout = resolve_props_layout(path, layout_locals.keys, [formats.first])
       body = layout.render(view, layout_locals) do |json|
         locals[:json] = json
         template.render(view, locals)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: props_template
 version: !ruby/object:Gem::Version
-  version: 0.13.0
+  version: 0.14.0
 platform: ruby
 authors:
 - Johny Ho
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-03-20 00:00:00.000000000 Z
+date: 2020-06-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -72,6 +72,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- README.md
 - lib/props_template.rb
 - lib/props_template/base.rb
 - lib/props_template/base_with_extensions.rb