Interlude: HTTP GET parameter priority

Now, in an index page you will probably have three things all of which will want to put parameters to your urls to be activated:

• Query filtering; this will put a filter query parameter to filter your query. Notice that because of how phoenix works (it allows maps in the query parameters) the filter can be a single query parameter but contain multiple filters (i.e the filter will be something like %{"key1" => "value1", "key2" => "value2"}
• Order by: This will put an order_by query parameter to denote the field that the query will be sorted
• Pagination: This will put an page query parameter to denote the current page

I like to give them a priority in the order I’ve listed them; when one of them is changed, it will clear the ones following it. So if the query filters are changed both the pagination and the order by fields will be cleared, if the order by field is changed then only the pagination field will be cleared but if the pagination field is changed both the query filters and the order by fields will be kept there.

I think that’s the best way to do it from an UX point of view; try to think about it and you’ll probably agree.

create_order_url

This function receives three parameters: The current @conn, the name of a field to sort by and an optional list of query parameters that need to be kept while creating the order by links. I’ve put this function in a ViewHelpers module that I am including to all my views (by adding an import PhxcrdWeb.ViewHelpers line to the PhxcrdWeb module).

Let’s take a look at the code:

def create_order_url(conn, field_name, allowed_keys \\ ["filter"]) do
  Phoenix.Controller.current_url(conn, get_order_params(conn.params, allowed_keys, field_name))
end

This doesn’t do much, it just uses the phoenix’s current_url that generates a new url to the current page, passing it a dictionary of http get parameters that should be appended to the url that are created through get_order_params. Notice that there’s an allowed_keys parameter that contains the query parameters that we need to keep after the sorting (see the previous interlude). By default I pass the filter query parameter so if theres a filter (check my previous article) it will keep it when sorting (but any pagination will be cleared; if I sort by a new field I want to go to the first page there’s no reason for me to keep seeing the page I was on before changing the order by).

The get_order_params receives the query parameters of the current connection (as a map), the allowed keys I mentioned before and the actual name of the field to sort on. This method is a little more complex:

defp get_order_params(params, allowed_keys, order_key) do
  params
  |> Map.take(allowed_keys ++ ["order_by"])
  |> Enum.map(fn {k, v} -> {String.to_atom(k), v} end)
  |> Map.new()
  |> Map.update(
    :order_by,
    order_key,
    &case &1 do
      "-" <> ^order_key -> order_key
      ^order_key -> "-" <> order_key
      _ -> "-" <> order_key
    end
  )
end

It only keeps the parameters in the allowed_keys list and the current order_by parameter (if there’s one) discarding everything else. It will then convert the keys of the map to atoms and put them in a new map. Finally, it will update the order_by field (if exists) either by switching the - in front of the field to declare asc/desc sorting or adding it for the field that was clicked. Actually the logic of that Map.update is the following:

• If there’s no :order_by key then add it and assign the passed order_key
• If the current value of :order_by is equal to order_key with or without a - then toggle the - (this happens when you click on a field that is already used for sorting)
• If the current value of :order_by is anything else (i.e not the same as the order_key) then just change :order_by to -orderKey (this happens when there’s sorting but you click on a different field, not the one used for the sorting)

Notice that this juggling between map, list of keywords and then map again (using Enum.map and then Map.new etc) is needed because the query parameters are in a map with strings as keys form (%{"key" => "value"}) while the current_url function needs the query params in a map with atoms as keys form (%{key: "value"}).

sort_by_params

The sort_by_params method gets three parameters: The query that will be sorted, the existing http parameters map (so as to retrieve the order_by value) and the declared list of allowed sorting fields. Let’s take a look at it:

def sort_by_params(qs, %{"order_by" => "-" <> val}, allowed),
  do: do_sort_by_params(qs, val, :asc, allowed)

def sort_by_params(qs, %{"order_by" => val}, allowed),
  do: do_sort_by_params(qs, val, :desc, allowed)

def sort_by_params(qs, _, _), do: qs

This multi-legged function will only do something if there’s an order_by parameter in the http parameters (else it will just return the query as is) and will call do_sort_by_params passing it the received query, either :asc or :desc (depending if there’s a - in front of the value) and the received allowed fields list.

The do_sort_by_params makes sure that the passed parameter is in the allowed list and if yes it creates the atoms of the binding and field name (using String.to_atom) and does the actual sorting to the passed query:

defp do_sort_by_params(qs, val, ord, allowed) do
  if val in allowed do
    [binding, name] = val |> String.split("__") |> Enum.map(&String.to_atom/1)
    qs |> order_by([{^binding, t}], [{^ord, field(t, ^name)}])
  else
    qs
  end
end

The line qs |> order_by([{^binding, t}], [{^ord, field(t, ^name)}]) may seem a little complex but it has been thoroughly explained in the previous article.