Filter facets #18

cavis · 2019-08-26T22:11:58Z

Adds filter facet attributes into the paged collection. It's up to the client to know how to interpret them, and change the ?filter param.

Also adds a vary link to paged collections, which gives you a templated link to this collection.

{
  "count": 25,
  "total": 71,
  "facets": {
    "type": [
      {"id": "the_normal_type", "label": "The Normal Type", "count": 10},
      {"id": "a_different_type", "label": "A Different Type", "count": 7}
    ],
    "status": [
      {"id": "active", "label": "Active", "count": 9},
      {"id": "inactive", "label": "Inactive", "count": 15}
    ],
    "some_custom_filter": [
      {"id": "", "label": "", "count": 12}
    ]
  },
  "_embedded": {
    "prx:items": []
  },
  "_links": {
    "self": {
      "href": "/api/v1/campaigns?filters=text%3Dwhatever",
      "profile": "http://meta.prx.org/model/collection/application-record/campaign"
    },
    "vary": {
      "href": "/api/v1/campaigns{?page,per,zoom,filters,sorts}",
      "templated": true
    }
  }
}

The idea with facets is that they change as you apply filters, and represent what counts would return if you applied that filter+value in addition to any filters you currently have applied. There is nothing in the JSON to tell you what filters are currently applied (unless you parse it out of the self link). So the client had better be tracking its own filter state.

The vary link only appears if there are query params to vary (set by the vary_params method). By default here, base HalApi::Representers do not have a vary link (though you could argue we should allow varying by ?zoom). And paged representers do have a vary link, including ?page,per,zoom,filters,sorts which are all part of the HalApi::Controller by default.

cavis · 2019-08-27T18:53:03Z

lib/hal_api/controller/filtering.rb

@@ -53,6 +53,28 @@ def filters
    @filters ||= parse_filters_param
  end

+  def filter_facets


By default, the facets attribute won't render at all. You have to provide this method in your controller.

makes sense to me - how does the API indicate which fields can be used as facets?
e.g. type, status, etc.?

The specifics of this were implemented in Augury (i.e. left up to the specific app). Ended up being a hash of "facet name" (which is the ?filters= key name) to a list of options for the facet.

cavis · 2019-08-27T18:54:16Z

lib/hal_api/controller/resources.rb

@@ -75,6 +75,10 @@ def resources_base
    self.class.resource_class.where(nil)
  end

+  def resources_query


Convenience method for controllers implementing filter_facets. For instance, in the Augury campaigns controller I found myself doing:

def filter_facets { type: resources_query.group(:type).count, status: resources_query.group(:status).count, } end

cavis · 2019-08-27T18:54:59Z

lib/hal_api/representer/collection_paging.rb

@@ -36,6 +37,14 @@ def self_url(represented)
    href_url_helper(represented.params)
  end

+  def vary_url(represented)
+    href_url_helper(represented.params.except(*vary_params))


It was necessary to remove any of the "varied query params" before getting the url.

cavis · 2019-08-27T18:55:26Z

lib/hal_api/representer/collection_paging.rb

@@ -46,6 +55,7 @@ def profile_url(represented)
  # if it is a lambda, execute in the context against the represented.parent (if there is one) or represented
  def href_url_helper(options={})
    if represented_url.nil?
+      options = options.except(:format)


This was an existing bug/annoyance where paged collections always had a self link with .json in it.

oh yuck, good fix!

kookster

I have questions.

kookster · 2019-09-05T13:39:50Z

lib/hal_api/controller/filtering.rb

@@ -53,6 +53,28 @@ def filters
    @filters ||= parse_filters_param
  end

+  def filter_facets


makes sense to me - how does the API indicate which fields can be used as facets?
e.g. type, status, etc.?

kookster · 2019-09-05T13:45:33Z

lib/hal_api/controller/filtering.rb

+  end
+
+  def index_collection
+    collection = defined?(super) ? super : HalApi::PagedCollection.new([])


I kinda thought some of this might end up in or extending paged collection, but I can see the separation of the controller knowing about the facets and setting them, like with other model data. I wonder if the controller or the paged collection should be more aware of the structure of it though...probably not, probably overkill to have mutator and other methods on the collection...maybe a method to add/set a facet?

I guess I am unsure where to put all the filtering functionality. I think your move here to keep it in a concern/mixin may actually be better, as it keeps most of the logic in the same place.

I could see doing an optimization like that. But to start, I wanted to leave that up to the implementing app (augury.prx.org in this case) and see where that takes us. Rather than locking them into a more controlled data structure.

kookster · 2019-09-05T13:47:10Z

lib/hal_api/controller/filtering.rb

+    collection = defined?(super) ? super : HalApi::PagedCollection.new([])
+
+    # add facets if defined, removing filters/facets with counts of 0
+    non_zero_facets = (filter_facets || {}).with_indifferent_access.tap do |hash|


Should the filter_key have more than just an id? Should there be a human readable label for it?
e.g. some_custom_filter would not be the best for display.

I have talked myself out of this, withdrawn!

I'd lump this in with "describing all available filters", which is sort of out-of-scope for this PR now. Opened #19.

kookster · 2019-09-05T13:48:52Z

lib/hal_api/representer/collection_paging.rb

@@ -46,6 +55,7 @@ def profile_url(represented)
  # if it is a lambda, execute in the context against the represented.parent (if there is one) or represented
  def href_url_helper(options={})
    if represented_url.nil?
+      options = options.except(:format)


oh yuck, good fix!

kookster

questions answered - lgtm

cavis added 3 commits August 26, 2019 15:37

Set accessors for allowed sorts/filters

3045a52

Add sorts/filters to paged representer

7270703

Bump version

ba3c801

cavis self-assigned this Aug 26, 2019

cavis added 3 commits August 27, 2019 10:38

Remove sorting hints

3d2fc0e

Rename filters -> facets; remove 0s automagically

ba8c539

Init vary link

0fdfa15

cavis changed the title ~~Filter/sort facets~~ Filter facets Aug 27, 2019

cavis commented Aug 27, 2019

View reviewed changes

Remove empty test

4035e56

cavis requested a review from kookster August 27, 2019 18:57

cavis added 2 commits August 28, 2019 09:11

Switch to facets as arrays of objects

6d430bc

Safety 3rd

94d7034

kookster reviewed Sep 5, 2019

View reviewed changes

kookster approved these changes Sep 6, 2019

View reviewed changes

cavis merged commit 8f3eaee into master Sep 9, 2019

cavis deleted the feat/filter_sort_facets branch September 9, 2019 14:07

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Filter facets #18

Filter facets #18

cavis commented Aug 26, 2019 •

edited

Loading

cavis Aug 27, 2019

kookster Sep 5, 2019

cavis Sep 5, 2019

cavis Aug 27, 2019

cavis Aug 27, 2019

cavis Aug 27, 2019

kookster Sep 5, 2019

kookster left a comment

kookster Sep 5, 2019

kookster Sep 5, 2019

cavis Sep 5, 2019 •

edited

Loading

kookster Sep 5, 2019

kookster Sep 5, 2019

cavis Sep 5, 2019

kookster Sep 5, 2019

kookster left a comment

Filter facets #18

Filter facets #18

Conversation

cavis commented Aug 26, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kookster left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cavis Sep 5, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kookster left a comment

Choose a reason for hiding this comment

cavis commented Aug 26, 2019 •

edited

Loading

cavis Sep 5, 2019 •

edited

Loading