WIP adding specs and docs for collection component, fixed toggle naming

Author: jonasjabari

app/concepts/matestack/ui/core/collection/filter/filter.js

@@ -14,17 +14,18 @@ const componentDef = {
   methods: {
     submitFilter: function(){
       var url;
+      var filter = this.filter
       for (var key in this.filter) {
-        url = this.updateQueryParams(this.componentConfig["id"] + "-filter-" + key, this.filter[key])
-        url = this.updateQueryParams(this.componentConfig["id"] + "-offset", 0, url)
+        url = this.updateQueryParams(this.componentConfig["id"] + "-filter-" + key, this.filter[key], url)
       }
+      url = this.updateQueryParams(this.componentConfig["id"] + "-offset", 0, url)
       window.history.pushState({matestackApp: true, url: url}, null, url);
       matestackEventHub.$emit(this.componentConfig["id"] + "-update")
     },
     resetFilter: function(){
       var url;
       for (var key in this.filter) {
-        url = this.updateQueryParams(this.componentConfig["id"] + "-filter-" + key, null)
+        url = this.updateQueryParams(this.componentConfig["id"] + "-filter-" + key, null, url)
         this.filter[key] = null;
         this.$forceUpdate();
       }

app/concepts/matestack/ui/core/collection/order/order.js

@@ -12,7 +12,7 @@ const componentDef = {
     }
   },
   methods: {
-    toggelOrder: function(key){
+    toggleOrder: function(key){
       if (this.ordering[key] == undefined) {
         this.ordering[key] = "asc"
       } else if (this.ordering[key] == "asc") {

app/concepts/matestack/ui/core/collection/order/toggel/toggel.haml

@@ -1,4 +1,4 @@
-module Matestack::Ui::Core::Collection::Order::Toggel::Indicator
+module Matestack::Ui::Core::Collection::Order::Toggle::Indicator
   class Indicator < Matestack::Ui::Core::Component::Static
 
     def response

app/concepts/matestack/ui/core/collection/order/toggel/toggel.rb

@@ -0,0 +1,3 @@
+%a{@tag_attributes, "@click": "toggleOrder(\"#{@component_config[:key]}\")"}
+  - if block_given?
+    = yield

app/concepts/matestack/ui/core/collection/order/toggel/indicator/indicator.rb renamed to app/concepts/matestack/ui/core/collection/order/toggle/indicator/indicator.rb

@@ -0,0 +1,6 @@
+module Matestack::Ui::Core::Collection::Order::Toggle
+  class Toggle < Matestack::Ui::Core::Component::Static
+
+
+  end
+end

app/concepts/matestack/ui/core/collection/order/toggle/toggle.haml

@@ -0,0 +1,300 @@
+# matestack core component: Collection
+
+Show [specs](../../spec/usage/components/collection_spec.rb)
+
+The `collection` component is designed:
+
+- to display instances from a model (Active Record or similar)
+- filter the displayed instances without full page reload
+- paginate the displayed instances without full page reload
+- order the displayed instances without full page reload
+
+The `collection` component should be as flexible as possible while still reducing the complexity of implementing all classic collection features by hand
+
+## Prerequisites
+
+We use a ActiveRecord Model in the following examples. This Model has two columns: `id` and `title`.
+
+## Examples
+
+### Filterable collection
+
+In this example, we want to display ALL instances of `DummyModel` and filter the collection by title using a text input.
+
+```ruby
+class Pages::MyApp::Collection < Matestack::Ui::Page
+
+  include Matestack::Ui::Core::Collection::Helper
+
+  def prepare
+    my_collection_id = "my-first-collection"
+
+    current_filter = get_collection_filter(my_collection_id)
+
+    my_base_query = DummyModel.all
+
+    my_filtered_query = my_base_query
+      .where("title LIKE ?", "%#{current_filter[:title]}%")
+
+    @my_collection = set_collection({
+      id: my_collection_id,
+      data: my_filtered_query
+    })
+  end
+
+  def response
+    components {
+      heading size: 2, text: "My Collection"
+
+      partial :filter
+      partial :content
+    }
+  end
+
+  def filter
+    partial {
+      collection_filter @my_collection.config do
+
+        collection_filter_input key: :title, type: :text, placeholder: "Filter by Title"
+        collection_filter_submit do
+          button text: "filter"
+        end
+        collection_filter_reset do
+          button text: "reset"
+        end
+
+      end
+    }
+  end
+
+  def content
+    partial {
+      collection_content @my_collection.config do
+        ul do
+          @my_collection.data.each do |dummy|
+            li do
+              plain dummy.title
+            end
+          end
+        end
+      end
+    }
+  end
+
+end
+```
+
+### Filtered & paginated collection
+
+In this example, we want to display only a limited (10) amount of  instances of `DummyModel` at once and filter the collection by title using a text input. We want to display the classic pagination buttons and information below the list of paginated instances.
+
+```ruby
+class Pages::MyApp::Collection < Matestack::Ui::Page
+
+  include Matestack::Ui::Core::Collection::Helper
+
+  def prepare
+    my_collection_id = "my-first-collection"
+
+    current_filter = get_collection_filter(my_collection_id)
+
+    my_base_query = DummyModel.all
+
+    my_filtered_query = my_base_query
+      .where("title LIKE ?", "%#{current_filter[:title]}%")
+
+    @my_collection = set_collection({
+      id: my_collection_id,
+      data: my_filtered_query,
+      init_limit: 10, #set a limit
+      filtered_count: my_filtered_query.count, #tell the component how to count the filtered result
+      base_count: my_base_query.count #tell the component how to count the total amount
+    })
+  end
+
+  def response
+    components {
+      heading size: 2, text: "My Collection"
+
+      partial :filter
+      partial :content
+    }
+  end
+
+  def filter
+    partial {
+      collection_filter @my_collection.config do
+
+        collection_filter_input key: :title, type: :text, placeholder: "Filter by Title"
+        collection_filter_submit do
+          button text: "filter"
+        end
+        collection_filter_reset do
+          button text: "reset"
+        end
+
+      end
+    }
+  end
+
+  def content
+    partial {
+      collection_content @my_collection.config do
+        ul do
+          # now we use paginated_data!
+          @my_collection.paginated_data.each do |dummy|
+            li do
+              plain dummy.title
+            end
+          end
+        end
+        partial :paginator #has to be placed within `collection_content`!
+      end
+    }
+  end
+
+  def paginator
+    partial {
+      plain "showing #{@my_collection.from}"
+      plain "to #{@my_collection.to}"
+      plain "of #{@my_collection.filtered_count}"
+      plain "from total #{@my_collection.base_count}"
+
+      collection_content_previous do
+        button text: "previous"
+      end
+
+      @my_collection.pages.each do |page|
+        collection_content_page_link page: page do
+          button text: page
+        end
+      end
+
+      collection_content_next do
+        button text: "next"
+      end
+    }
+  end
+
+
+end
+```
+
+### Filtered & paginated & ordered collection
+
+In this example, we want to display only a limited (10) amount of  instances of `DummyModel` at once and filter the collection by title using a text input. We want to display the classic pagination buttons and information below the list of paginated instances. Additionally, we want to order the collection by title ascending or descending.
+
+```ruby
+class Pages::MyApp::Collection < Matestack::Ui::Page
+
+  include Matestack::Ui::Core::Collection::Helper
+
+  def prepare
+    my_collection_id = "my-first-collection"
+
+    current_filter = get_collection_filter(my_collection_id)
+    current_order = get_collection_order(my_collection_id) #now we need the current order state from the url params
+
+    my_base_query = DummyModel.all
+
+    my_filtered_query = my_base_query
+      .where("title LIKE ?", "%#{current_filter[:title]}%")
+      .order(current_order) # and apply the state to the query
+
+    @my_collection = set_collection({
+      id: my_collection_id,
+      data: my_filtered_query,
+      init_limit: 10,
+      filtered_count: my_filtered_query.count,
+      base_count: my_base_query.count
+    })
+  end
+
+  def response
+    components {
+      heading size: 2, text: "My Collection"
+
+      partial :filter
+      partial :ordering
+      partial :content
+    }
+  end
+
+  def filter
+    partial {
+      collection_filter @my_collection.config do
+
+        collection_filter_input key: :title, type: :text, placeholder: "Filter by Title"
+        collection_filter_submit do
+          button text: "filter"
+        end
+        collection_filter_reset do
+          button text: "reset"
+        end
+
+      end
+    }
+  end
+
+  def ordering
+    partial {
+      collection_order @my_collection.config do
+
+        plain "sort by:"
+        collection_order_toggle key: :title do
+          button do
+            # we want to use an "arrow up (unicode: &#8593;)"
+            # and and an "arrow down (unicode: &#8595;)" in order to
+            # visualize the current order state
+            collection_order_toggle_indicator key: :title, asc: '&#8593;', desc: '&#8595;'
+            plain "title"
+          end
+        end
+
+      end
+    }
+  end
+
+  def content
+    partial {
+      collection_content @my_collection.config do
+        ul do
+          @my_collection.paginated_data.each do |dummy|
+            li do
+              plain dummy.title
+            end
+          end
+        end
+        partial :paginator
+      end
+    }
+  end
+
+  def paginator
+    partial {
+      plain "showing #{@my_collection.from}"
+      plain "to #{@my_collection.to}"
+      plain "of #{@my_collection.filtered_count}"
+      plain "from total #{@my_collection.base_count}"
+
+      collection_content_previous do
+        button text: "previous"
+      end
+
+      @my_collection.pages.each do |page|
+        collection_content_page_link page: page do
+          button text: page
+        end
+      end
+
+      collection_content_next do
+        button text: "next"
+      end
+    }
+  end
+
+
+end
+```
+
+### Action enriched collection

app/concepts/matestack/ui/core/collection/order/toggle/toggle.rb

@@ -37,6 +37,7 @@ def filter
       collection_filter @my_collection.config do
 
         collection_filter_input key: :title, type: :text, placeholder: "Filter by Title"
+        collection_filter_input id: "my-description-filter-input", key: :description, type: :text, placeholder: "Filter by description"
         collection_filter_submit do
           button text: "filter"
         end
@@ -52,9 +53,9 @@ def ordering
     partial {
       collection_order @my_collection.config do
         plain "sort by: "
-        collection_order_toggel key: :title do
+        collection_order_toggle key: :title do
           button do
-            collection_order_toggel_indicator key: :title, asc: '↑', desc: '↓'
+            collection_order_toggle_indicator key: :title, asc: '↑', desc: '↓'
             plain "title"
           end
         end