rails_redhot 0.0.2 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '059048dabb167e99b923d1021bf334dc4ed59f4fb0d2306aaa199ade9e1a1b67'
-  data.tar.gz: fcdf3b027a5d62b400ae824caeef344d1aaa91593d197d4e48a7b27c963cd4e3
+  metadata.gz: 5be8aff1e9314532378f476e76fe310b84bfe386abe0ba18c33ec60820696d24
+  data.tar.gz: f77470f8cec6b501c56fb0102e1b63242b0a11a4c453d4bbe3b3068b148b88fe
 SHA512:
-  metadata.gz: 91d1d21a37b5b6f2b7c9e96a5757e848b53ba92430ffbc794a0ed8313281b474dbfa42369492615822753a6b0667ae235e622a8e896000ab2fc369bef9faaf40
-  data.tar.gz: 17714334908de5714a7e18539ae264d4b937373f3e16888f5c07c91d0f3406485183c12d3bf328d65eb31ab086f8d50f48a6b6899b0f656c2c4da1c3ec9fcb8f
+  metadata.gz: adbb2a15f3bcffe7b910b05217d5e564125915bd39710347b527a863462fb7bef50951358d0b2d31829994410abca865f88f183abe09e09e0aef8be56956a5bf
+  data.tar.gz: 922d4eac6e294a8f25ac027eca82c457115884758fc785289c79867785618aa0f7a788975e5f66fcb4139bfd819cca39b4b263d6d7d8df989a6cdc03bec8f97d

data/README.md

@@ -9,13 +9,14 @@ Or when building a search page for a webshop. Whenever the user selects a catego
 or price range to filter on this can be an action for the redux store. If the user
 hits the back button the last action can be deleted and the current state
 regenerated by reducing all remaining actions. The user only sees the last filter
-being reverted to what it was before.  
+being reverted to what it was before.
+
 Sometimes the actions of the user in the frontend should be sent to a backend
 application. For instance when actions of multiple users should be kept in-sync.
 Often command-query-responsibility-separation (CQRS) is used for this purpose.
 These solutions can become very complex
-([example](https://medium.com/resolvejs/resolve-redux-backend-ebcfc79bbbea)
-scroll down a bit).
+([example](https://medium.com/resolvejs/resolve-redux-backend-ebcfc79bbbea),
+scroll down a bit for a full example).
 
 The Hotwire (Html Over The Wire) approach does an excellent job of removing the need
 to build single page apps. Hotwire will be the
@@ -28,20 +29,22 @@ is still very useful for this purpose.
 
 This gem aims to combine html-over-the-wire approach with the redux pattern to
 radically reduce complexity of the overall application.
-(At least when compared to for instance react+cqrs.)
+(At least when compared to for instance react+cqrs application stacks.)
 Only four components are required:
 
 1. Views, normal rails views rendering the current state and delivered as turbo frames
-2. Actions, just (submit) buttons that send a request to the backend
+2. Actions, just submit buttons that send a request to the backend handled by a controller
 3. Store, keeping the list of actions and current state, managed by this gem and stored
    in an activerecord model
-4. Reducers, a set of functions (provided by you) that translate actions to changes in state
+4. Reducers, a set of functions (provided by you) that translate actions to changes in
+   state. The state can be used again in step 1
 
 Common actions (undo, redo, flatten actions to initial state) are provided by this gem.
 Combined with turbo frames for rendering partial page updates this makes it easy to
 create a very smooth user experience.
 
 ## Usage
+### Model
 Create a migration to add a 'text' type attribute to a model that should have a redux store.
 In the model add an `acts_as_redux` line, specifying the name of the text attribute.
 Add a private method holding all your reducer functions.
@@ -49,40 +52,102 @@ See [this example](test/dummy/app/models/foobar.rb).
 Note that all reducer functions must return the state object (a Hash).
 
 ```ruby
-include RailsRedhot::ActsAsRedux
-
-acts_as_redux :my_redux
-
-private
-
-def my_redux_reducers
-->(state, action) {
-  case action[:type]
-  when :add
-    state[:total] += 1
-  when :remove
-    state[:total] -= 1
+class Foobar < ApplicationRecord
+  include RailsRedhot::ActsAsRedux
+
+  acts_as_redux :my_redux
+
+  private
+
+  def my_redux_reducers
+  ->(state, action) {
+    case action[:type]
+    when :add
+      state[:total] += 1
+    when :remove
+      state[:total] -= 1
+    end
+    state
+  },
   end
-  state
-},
 end
 ```
 
 Or specify your own reducer method:
 
 ```ruby
-acts_as_redux :my_redux, reducers: :list_of_reducers
+acts_as_redux :my_redux, reducers: :my_list_of_reducers
 
-def list_of_reducers
+def my_list_of_reducers
 # ...
 ```
 
-In your views add some submit buttons for adding and undoing actions.
-See [this example](test/dummy/app/views/foobars/_editor.html.erb).
-And let your controller ([example](test/dummy/app/controllers/foobars_controller.rb))
-process these actions.  
-See section [Demo application](https://github.com/easydatawarehousing/rails_redhot#demo-application)
-for a working example.
+### Undo/redo
+Every instance of the model now has access to several methods.
+For undoing actions there are: `undo?`, `undo_action` and `undo!`,
+which you might use in a view like this:
+
+```ruby
+<%- if foobar.undo? %>
+  <%= form_with(model: foobar, url: update_action_foobar_path(foobar), method: :put) do |form| %>
+    <%= form.hidden_field :action, value: :undo %>
+    <%= form.submit "Undo: #{foobar.undo_action['type']}" %>
+  <% end %>
+<% end %>
+```
+In the controller action use the `undo!` method to perform the action.
+For redoing actions the similar methods `redo?`, `redo_action` and `redo!` are available.
+
+### Flatten
+You can 'save' the current state. Essentially this flattens the list of actions to the initial state.
+Methods `flatten?` and `flatten!` can be used in a view and controller:
+
+```ruby
+<%- if foobar.flatten? %>
+  <%= form_with(model: foobar, url: update_action_foobar_path(foobar), method: :put) do |form| %>
+    <%= form.hidden_field :action, value: :flatten %>
+    <%= form.submit "Save changes" %>
+  <% end %>
+<% end %>
+```
+
+### Sequence ID
+As a convenience a sequence ID id available which should always return a unique id
+(within the context of the model instance). To get the next sequence id use `next_seq_id`,
+to get the current sequence value use `seq_id`.
+You could use a sequence in a reducer function to make sure every added item is assigned a unique id.
+
+### Dispatch actions and view state
+To add an action to the store you can use the `dispatch!` method, passing a hash with the details of the action.
+What the content of that hash should be is up to you.
+As long as your reducer fuctions can handle the action anything is possible.
+
+Finally to get the current state the `view_state` method is available.
+In a view it can be used like so:
+
+```ruby
+<p>
+  There are <%= foobar.view_state['total'] %> items
+</p>
+
+<%- foobar.view_state['items'].each do |item| %>
+  <p>
+    <%= CGI.unescape(item['value']) %>
+  </p>
+<% end %>
+```
+
+The `view_state` method returns a Hash. What the content of this hash looks like depends
+on the reducer functions you have implemented.
+
+For a full working example see the demo applications [view](test/dummy/app/views/foobars/_editor.html.erb)
+and [controller](test/dummy/app/controllers/foobars_controller.rb).
+
+## Security
+Care must be taken to not introduce any vulnerabilities.
+When passing values from the request to the reducer functions treat any string or complex
+values as potential candidates for SQL injection. Either sanitize the value or `CGI.escape`
+a string before adding it to the redux store.
 
 ## Installation
 Add this line to your application's Gemfile:
@@ -113,14 +178,14 @@ rails db:setup
 rails server
 ```
 
-Open the [application](http://localhost:3000/foobars).
+Then open the [application](http://localhost:3000/foobars).
 Click on 'New foobar', 'Add a new foobar' and 'Edit this foobar'.
 
 ## Test
 Run:
 
 ```bash
-rails test/dummy/test
+rails test test/dummy/test
 ```
 
 ## License
@@ -134,6 +199,9 @@ The gem is available as open source under the terms of the [MIT License](https:/
   If the list of actions to process is large this would become slow.
   One would need add 'savepoints' that regularly save the state and rebuild
   the current state from that point forward
+- Stricly speaking, hotwire is not needed for this gem to work. Just using
+  plain old rails views and controllers is fine. Hotwire certainly makes
+  an application using this gem a lot faster
 - No checking on the size of the text attribute used for the store is done
 - Currently only one redux store can be added to a model
 - Redux store code inspired by:

data/lib/rails_redhot/version.rb

@@ -1,4 +1,4 @@
 module RailsRedhot
   # Gem version
-  VERSION = "0.0.2"
+  VERSION = "0.1.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails_redhot
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.1.0
 platform: ruby
 authors:
 - Ivo Herweijer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-12-10 00:00:00.000000000 Z
+date: 2021-12-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 7.0.0.rc1
+        version: 7.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 7.0.0.rc1
+        version: 7.0.0
 description: REDux pattern for HOTwire == Redhot
 email:
 - info@edwhs.nl