Liking cljdoc? Tell your friends :D

ajax.url

At first blush, it's pretty bizarre that an entire file is devoted to one
function, namely params-to-str, which just takes a map and converts it to a querystring. However, it turns out that people sometimes want to encode fairly complex maps and the behaviour in the presence of vectors/arrays is controversial.

The basic question is: what {:a [1 2]} be encoded as? The correct answer as far as ring is concerned is a=1&a=2. This is also true of most Java implementations, ASP.NET, Angular, Haskell and even old-school ASP. This is called vec-strategy :java in the code. Rails and PHP, however, prefer a[]=1&a[]=2, which has an obvious implementation in a dynamic language. This is called vec-strategy :rails. Finally, there's what cljs-ajax (mistakenly) did between versions 0.4.0 and 0.6.x: a[0]=1&a[2]=1, which is called vec-strategy :indexed. This is retained mostly for people who need to keep compatibility with the previous behaviour.

None of these are the "correct answer": the HTTP standards are silent on the subject, so you're left with what your server accepts, and different servers have different conventions. Worse, if you send the wrong convention it gets misinterpreted. Send strategy :rails to a :java server and you get { "a[]" [1 2]}. Worse, send strategy :java to a :rails server and you get { "a" 2 }. So it's important to know what your server's convention is.

The situation for maps is simpler, pretty much everyone encodes {:a {:b 1}} as "a[b]=1". That is, assuming they process it at all. The HTTP spec is similarly silent on this and your server may get your language's equivalent of { "a[b]" 1 }. In cases like this, you have two choices 1) write your own server-side decoder or 2) don't ever send nested maps.

If you ever wanted to consider exactly how bad the effect of supporting a wide range of use cases, consider that this was the original code:

(defn params-to-str [params] (if params (-> params
clj->js structs/Map. query-data/createFromMap .toString)))

This code remains completely correct for at least 90% of actual users of cljs-ajax. Now we have ~50 SLOCs achieving much the same result.

At first blush, it's pretty bizarre that an entire file is devoted to one  
function, namely params-to-str, which just takes a map and converts it to
a querystring. However, it turns out that people sometimes want to encode
fairly complex maps and the behaviour in the presence of vectors/arrays
is controversial.

The basic question is: what {:a [1 2]} be encoded as? The correct answer
as far as ring is concerned is a=1&a=2. This is also true of most Java
implementations, ASP.NET, Angular, Haskell and even old-school ASP. This 
is called vec-strategy :java in the code. Rails and PHP, however, 
prefer a[]=1&a[]=2, which has an obvious implementation in a dynamic 
language. This is called vec-strategy :rails. Finally, there's what 
cljs-ajax (mistakenly) did between versions 0.4.0 and 0.6.x: 
a[0]=1&a[2]=1, which is called vec-strategy :indexed. This is retained 
mostly for people who need to keep compatibility with the previous behaviour.

None of these are the "correct answer": the HTTP standards are
silent on the subject, so you're left with what your server accepts, and
different servers have different conventions. Worse, if you send the
wrong convention it gets misinterpreted. Send strategy :rails to a :java
server and you get { "a[]" [1 2]}. Worse, send strategy :java to a :rails
server and you get { "a" 2 }. So it's important to know what your server's
convention is.

The situation for maps is simpler, pretty much everyone encodes
{:a {:b 1}} as "a[b]=1". That is, assuming they process it at all.
The HTTP spec is similarly silent on this and your server may get your
language's equivalent of { "a[b]" 1 }. In cases like this, you have two
choices 1) write your own server-side decoder or 2) don't ever send
nested maps.

If you ever wanted to consider exactly how bad the effect of supporting
a wide range of use cases, consider that this was the original code:

(defn params-to-str [params]
   (if params
       (-> params      
           clj->js
           structs/Map.
           query-data/createFromMap
           .toString)))

This code remains completely correct for at least 90% of actual users
of cljs-ajax. Now we have ~50 SLOCs achieving much the same result.
raw docstring

params-to-strcljs

(params-to-str vec-strategy)
(params-to-str vec-strategy params)
source

url-request-formatcljs

(url-request-format)
(url-request-format {:keys [vec-strategy]})

The request format for simple POST and GET.

The request format for simple POST and GET.
sourceraw docstring

cljdoc is a website building & hosting documentation for Clojure/Script libraries

× close