view_component_reflex 1.2.0 → 1.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ed2f845769bba6d5142bef6d6fc601b44841080c49ee47abc0036801f62b145
-  data.tar.gz: 73e625d1948e5b477def8e098a4a4d55b9a02763c575e1d4bdd4c734e0f208b0
+  metadata.gz: 2269d8639ced76028ffe2a5970960d7381c862a75ce36481a84d8cf8886acd6c
+  data.tar.gz: c368a487c3a2d97b4207ecb47558877596f9f9dccc7aa63f363598bc72a4eb82
 SHA512:
-  metadata.gz: 76c5b53b3acb0fa68084b762ad14fddbaa0aee1d0b9bbe67f33910f088e7b60062bf5dcf61c7703932b2cfa228f4bccfc768e6b9ab64253397e3483efd50cfb5
-  data.tar.gz: 077a34955920288651b183d77971d30eb4fbfeabe45aaa799d78f2ea242cb46f328d23223508d053e53210c00e9aeb570e9d234b571aba3005e57b6448afd5fc
+  metadata.gz: 4822e9370947d8881b8f33ca8a00df19a9458ca31f9da4bc84bcfb438e768f37226a2790f489efe94ec36418f77ed4d32a122a003653ec3120ddc49df5af2a1d
+  data.tar.gz: 0f38085c800aa78f43e6df67cec9664115fed2cbce0cefc7fb89dbe2a0b3f624d7adfff1a71e542039af40a6b247744677e96a0115afe6f5f5ad65fb4c2a78df

data/README.md

@@ -30,7 +30,7 @@ end
 # counter_component.html.erb
 <%= component_controller do %>
     <p><%= @count %></p>
-    <button type="button" data-reflex="click->CounterComponentReflex#increment" data-key="<%= key %>">Click</button>
+    <%= reflex_tag :increment, :button, "Click" %>
 <% end %>
 ```
 
@@ -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,6 +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

@@ -43,7 +43,11 @@ module ViewComponentReflex
               component.instance_variable_set(k, v)
             end
             name.to_proc.call(component, *args)
-            refresh!
+            refresh! unless @prevent_refresh
+          end
+
+          def prevent_refresh!
+            @prevent_refresh = true
           end
 
           define_method :component_class do
@@ -62,7 +66,7 @@ module ViewComponentReflex
             return @component if @component
             @component = component_class.allocate
             reflex = self
-            exposed_methods = [:params, :request, :element, :refresh!, :refresh_all!, :stimulus_controller]
+            exposed_methods = [:params, :request, :element, :refresh!, :refresh_all!, :stimulus_controller, :session, :prevent_refresh!]
             exposed_methods.each do |meth|
               @component.define_singleton_method(meth) do |*a|
                 reflex.send(meth, *a)
@@ -98,15 +102,23 @@ module ViewComponentReflex
       helpers.controller.instance_variable_get(:@stimulus_reflex)
     end
 
-    def component_controller(opts = {}, &blk)
+    def component_controller(opts_or_tag = :div, opts = {}, &blk)
       self.class.init_stimulus_reflex
       init_key
-      opts[:data] = {
+
+      tag = :div
+      if opts_or_tag.is_a? Hash
+        options = opts_or_tag
+      else
+        tag = opts_or_tag
+        options = opts
+      end
+      options[:data] = {
         controller: self.class.stimulus_controller,
         key: key,
-        **(opts[:data] || {})
+        **(options[:data] || {})
       }
-      content_tag :div, capture(&blk), opts
+      content_tag tag, capture(&blk), options
     end
 
     # key is required if you're using state
@@ -121,6 +133,24 @@ module ViewComponentReflex
       @key = key
     end
 
+    def reflex_tag(reflex, name, content_or_options_with_block = {}, options = {}, escape = true, &block)
+      action, method = reflex.to_s.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
@@ -129,6 +159,10 @@ module ViewComponentReflex
       initial_param != new_param
     end
 
+    def omitted_from_state
+      []
+    end
+
     def key
       # initialize session state
       if !stimulus_reflex? || session[@key].nil?
@@ -141,7 +175,7 @@ module ViewComponentReflex
           :@helpers, :@controller, :@request, :@content
         ]
         instance_variables.reject { |k| blacklist.include?(k) }.each do |k|
-          new_state[k] = instance_variable_get(k)
+          new_state[k] = instance_variable_get(k) unless omitted_from_state.include?(k)
         end
         ViewComponentReflex::Engine.state_adapter.store_state(request, @key, new_state)
         ViewComponentReflex::Engine.state_adapter.store_state(request, "#{@key}_initial", new_state)
@@ -155,5 +189,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.2.0'
-end
+module ViewComponentReflex
+  VERSION = '1.6.1'
+end

metadata

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