Skip to content

Commit

Permalink
Alias dig to search.
Browse files Browse the repository at this point in the history
Search is a bit of a confusing way to describe what traversing is. Dig
seems more appropriate and is consistent with how superglue describes it.
  • Loading branch information
jho406 committed Dec 31, 2024
1 parent 0c75588 commit 964b8d4
Show file tree
Hide file tree
Showing 4 changed files with 71 additions and 47 deletions.
26 changes: 13 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ gem 'props_template'
and run `bundle`.

Optionally add the [core ext](#array-core-extension) to an initializer if you
want to [dig](#traversing) into your templates.
want to [dig](#digging) into your templates.

```ruby
require 'props_template/core_ext'
Expand Down Expand Up @@ -152,7 +152,7 @@ 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 [search](#traversing)
2. The inline form is considered a leaf node, and you can only [dig](#digging)
for internal nodes.

### json.extract!
Expand Down Expand Up @@ -202,7 +202,7 @@ end
| collection | A collection that responds to `member_at` and `member_by` |
| options | Additional [options](#options)|

To support [traversing nodes](#traversing), any list passed
To support [digging](#digging), any list passed
to `array!` MUST implement `member_at(index)` and `member_by(attr, value)`.

For example, if you were using a delegate:
Expand Down Expand Up @@ -276,7 +276,7 @@ end
```

PropsTemplate does not know what the elements are in your collection. The
example above will be fine for [traversing](#traversing)
example above will be fine for [digging](#digging)
by index, but will raise a `NotImplementedError` if you query by attribute. You
may still need to implement `member_by`.

Expand Down Expand Up @@ -447,7 +447,7 @@ entirely and replace the value with a placeholder. A common use case would be
tabbed content that does not load until you click the tab.

When your client receives the payload, you may issue a second request to the
same endpoint to fetch any missing nodes. See [traversing nodes](#traversing)
same endpoint to fetch any missing nodes. See [digging](#digging)

There is also an `defer: :auto` option that you can use with [SuperglueJS][1]. [SuperglueJS][1]
will use the metadata from `json.deferred!` to issue a `remote` dispatch to fetch
Expand Down Expand Up @@ -502,7 +502,7 @@ 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 [searching nodes](#traversing)
by PropsTemplate to when [digging](#digging)

For example:

Expand All @@ -528,7 +528,7 @@ end
If you are using [SuperglueJS][1], SuperglueJS will, it will automatically kick off
`remote(?props_at=posts.some_id=1.contact)` and `remote(?props_at=posts.some_id=2.contact)`.

## Traversing
## Digging

PropsTemplate has the ability to walk the tree you build, skipping execution of
untargeted nodes. This feature is useful for selectively updating your frontend
Expand All @@ -537,7 +537,7 @@ state.
```ruby
traversal_path = ['data', 'details', 'personal']

json.data(search: traversal_path) do
json.data(dig: traversal_path) do
json.details do
json.employment do
...more stuff
Expand Down Expand Up @@ -571,13 +571,13 @@ The above will output:
}
```

Searching only works with blocks, and will NOT work with Scalars
Digging 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.data(dig: traversal_path) do
json.details do
json.personal do
json.name 'james'
Expand All @@ -588,12 +588,12 @@ end

## Nodes that do not exist

Nodes that are not found will remove the branch where search was enabled on.
Nodes that are not found will remove the branch where digging was enabled on.

```ruby
traversal_path = ['data', 'details', 'does_not_exist']

json.data(search: traversal_path) do
json.data(dig: traversal_path) do
json.details do
json.personal do
json.name 'james'
Expand Down Expand Up @@ -642,7 +642,7 @@ will render Layout first, then the template when `yield json` is used.

## Change key format
By default, keys are not formatted. This is intentional. By being explicity with your keys,
it makes your views quicker and more easily searchable when working in Javascript land.
it makes your views quicker and more easily diggable when working in Javascript land.

If you must change this behavior, override it in an initializer and cache the value:

Expand Down
8 changes: 6 additions & 2 deletions lib/props_template.rb
Original file line number Diff line number Diff line change
Expand Up @@ -36,11 +36,15 @@ def initialize(context = nil, options = {})
end

def set!(key, options = {}, &block)
if block && options[:search] && !@builder.is_a?(Searcher)
if block && (options[:search] || options[:dig]) && !@builder.is_a?(Searcher)
search = options[:search] || options[:dig]

prev_builder = @builder
@builder = Searcher.new(self, options[:search], @context)
@builder = Searcher.new(self, search, @context)

options.delete(:search)
options.delete(:dig)

@builder.set!(key, options, &block)
found_block, found_options = @builder.found!
@builder = prev_builder
Expand Down
2 changes: 1 addition & 1 deletion spec/extensions/partial_render_spec.rb
Original file line number Diff line number Diff line change
Expand Up @@ -257,7 +257,7 @@
end
PROPS
}.to raise_error { |e|
expect(e.message).to match(/undefined local variable or method `customer'/)
expect(e.message).to match(/undefined local variable or method 'customer'/)
}
end

Expand Down
Loading

0 comments on commit 964b8d4

Please sign in to comment.