view_component_reflex 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f79604a043d4aa353ade5fec1bb3c1d7f263352304555fe3fe70dfd35fc921b9
-  data.tar.gz: 88259eb0924cf1508df64f5bb3565fac61134871d2ac210c3166c560bb0f028e
+  metadata.gz: aed815b44b0d4708ba9bb85e9a08912f15f4d66442432df5d0933866f66e3aba
+  data.tar.gz: 96262b95434700007b142be8411d115dc50cdd0d5b94baf5200b582317ce858b
 SHA512:
-  metadata.gz: 30d400ca7ace85a4f9bc9b25b6e4cdddfceb6518c980cbcb35f6e6f2216b03a5615cb882b91f9f9097bbce2b2495d306698b4c5bbedecae4259e97750d396bc9
-  data.tar.gz: 1c70cda5b7f89057079b86729d97a47a5b429e5f0bdd56732c4695841fe933c0ff57bf1b5143ec0fb7c54cac67bbc8a9c32d031337f33ec91949eb420eba67ac
+  metadata.gz: 8cdd11ece267f4cc206af3e12d3e62b4881fdde56afb28a23b078437448842eb54e7aa1da43a68dd4f071544bb360e95c15db2b4ea4599da9ee7e57e7887a2d8
+  data.tar.gz: 64c8053422748319fd6460881170c3b5a9b84da0577180ebbf8a3dd3e62e5b1563c5d9e17c617de798141466f85894b42b281377aa553ff9a3840d9c522564d8

data/README.md

@@ -39,7 +39,7 @@ end
 In order to reconcile state to components in collections, you can specify a `collection_key` method that returns some
 value unique to that component.
 
-```
+```ruby
 class TodoComponent < ViewComponentReflex::Component
   def initialize(todo:)
     @todo = todo
@@ -59,16 +59,127 @@ end
 If a new parameter is passed to the component during rendering, it is used instead of what's in state.
 If you're storing instances in state, you can use this to properly compare them.
 
+```ruby
+def permit_parameter?(initial_param, new_param)
+  if new_param.instance_of? MyModel 
+    new_param.id == @my_model.id
+  else
+    super
+  end
+end
+```
+
 ### omitted_from_state
 Return an array of instance variables you want to omit from state. Useful if you have an object 
 that isn't serializable as an instance variable, like a form.
 
-```
+```ruby
 def omitted_from_state
   [:@form]
 end
 ```
 
+### reflex_tag(reflex, name, content_or_options_with_block = nil, options = nil, escape = true, &block)
+This shares the same definition as `content_tag`, except it accepts a reflex as the first parameter.
+
+```erb
+<%= reflex_tag :increment, :button, "Click me!" %>
+```
+
+Would add a click handler to the `increment` method on your component.
+
+To use a non-click event, specific that with `->` notiation
+
+```erb
+<%= reflex_tag "mouseenter->increment", :button, "Click me!" %>
+```
+
+### collection_key
+If you're rendering a component as a collection with `MyComponent.with_collection(SomeCollection)`, you must define this method to return some unique value for the component.
+This is used to reconcile state in the background.
+
+```ruby
+def initialize
+  @my_model = MyModel.new
+end
+
+def collection_key
+ @my_model.id
+end
+```
+
+### prevent_refresh!
+By default, VCR will re-render your component after it executes your method. `revent_refresh!` prevents this from happening.
+
+```ruby
+def my_method
+  prevent_refresh!
+  @foo = Lbar
+end # the rendered page will not reflect this change
+```
+
+### refresh_all!
+Refresh the entire body of the page
+
+```ruby
+def do_some_global_action
+  prevent_refresh!
+  session[:model] = MyModel.new
+  refresh_all!
+end
+```
+
+### key
+This is a key unique to a particular component. It's used to reconcile state between renders, and should be passed as a data attribute whenever a reflex is called
+
+```erb
+<button type="button" data-reflex="click->MyComponent#do_something" data-key="<%= key %>">Click me!</button>
+```
+
+### component_controller(options = {}, &blk)
+This is a view helper to properly connect VCR to the component. It outputs `<div data-controller="my-controller" key=<%= key %></div>`
+You *must* wrap your component in this for everything to work properly.
+
+```erb
+<%= component_controller do %>
+  <p><%= @count %></p
+<% end %>
+```
+
+## Common patterns
+A lot of the time, you only need to update specific components when changing instance variables. For example, changing `@loading` might only need
+to display a spinner somewhere on the page. You can define setters to implicitly render the appropriate pieces of dom whenever that variable is set
+
+```ruby
+def initialize
+  @loading = false
+end
+
+def loading=(new_value)
+  @loading = new_value
+  refresh! '#loader'
+end
+
+def do_expensive_action
+  prevent_refresh! 
+
+  self.loading = true
+  execute_it
+  self.loading = false
+end
+```
+
+```erb
+<%= component_controller do %>
+  <div id="loader"> 
+    <% if @loading %>
+      <p>Loading...</p>
+    <% end %>
+  </div>
+
+  <button type="button" data-reflex="click->MyComponent#do_expensive_action" data-key="<%= key %>">Click me!</button>
+<% end
+```
 
 ## Custom State Adapters
 

data/app/components/view_component_reflex/component.rb

@@ -125,6 +125,24 @@ module ViewComponentReflex
       @key = key
     end
 
+    def reflex_tag(reflex, name, content_or_options_with_block = nil, options = nil, escape = true, &block)
+      action, method = reflex.split("->")
+      if method.nil?
+        method = action
+        action = "click"
+      end
+      data_attributes = {
+        reflex: "#{action}->#{self.class.name}##{method}",
+        key: key
+      }
+      if content_or_options_with_block.is_a?(Hash)
+        merge_data_attributes(content_or_options_with_block, data_attributes)
+      else
+        merge_data_attributes(options, data_attributes)
+      end
+      content_tag(name, content_or_options_with_block, options, escape, &block)
+    end
+
     def collection_key
       nil
     end
@@ -163,5 +181,16 @@ module ViewComponentReflex
       end
       @key
     end
+
+    private
+
+    def merge_data_attributes(options, attributes)
+      data = options[:data]
+      if data.nil?
+        options[:data] = attributes
+      else
+        options[:data].merge! attributes
+      end
+    end
   end
 end

data/lib/view_component_reflex/version.rb

@@ -1,3 +1,3 @@
 module ViewComponentReflex
-  VERSION = '1.4.0'
+  VERSION = '1.5.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: view_component_reflex
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Joshua LeBlanc
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-06-21 00:00:00.000000000 Z
+date: 2020-06-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails