@@ -6,30 +6,72 @@
66{-# LANGUAGE MultiParamTypeClasses #-}
77{-# LANGUAGE OverloadedStrings #-}
88{-# LANGUAGE TemplateHaskell #-}
9+
10+-- | A module for performing asynchronous HTTP calls from JavaScript
11+-- using the
12+-- <https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest XMLHttpRequest>
13+-- API (essentially AJAX). Despite the name, there is nothing whatsoever specific to XML.
14+--
15+-- The API has two components:
16+--
17+-- * convenient functions for common usecases like GET and POST
18+-- requests to APIs using JSON.
19+--
20+-- * a flexible set of functions for creating and executing arbitrary
21+-- requests and handling responses.
22+--
923module Reflex.Dom.Xhr
10− ( XMLHttpRequest
11− , XhrRequest (..)
12− , XhrRequestConfig (..)
13− , XhrResponse (..)
14− , XhrResponseBody (..)
15− , XhrResponseHeaders (..)
16− , XhrResponseType (..)
17− , XhrException (..)
18− , IsXhrPayload (..)
19− , _xhrResponse_body
20− , decodeText
21− , decodeXhrResponse
22− , getAndDecode
24+ ( -- * Common Patterns
25+
26+ -- | Functions that conveniently expose common uses like GET and
27+ -- POST to JSON APIs.
28+ getAndDecode
2329 , getMay
24− , newXMLHttpRequest
25− , newXMLHttpRequestWithError
26− , performMkRequestAsync
27− , performMkRequestsAsync
28− , performRequestAsync
29− , performRequestAsyncWithError
30− , performRequestsAsync
31− , performRequestsAsyncWithError
3230 , postJson
31+
32+ , decodeXhrResponse
33+ , decodeText
34+
35+ -- * General Request API
36+
37+ -- | This is the most general flow for sending XHR requests:
38+ --
39+ -- 1. Create an 'Event' stream of 'XhrRequest' records (ie
40+ -- @Event t (XhrRequest a)@). The records configure the request,
41+ -- and the 'Event' controls when the request or requests are
42+ -- actually sent.
43+ --
44+ -- 2. Plug the @Event t (XhrRequest a)@ into one of the functions
45+ -- for performing requests like 'performRequestAsync'.
46+ --
47+ -- 3. Consume the resulting stream of 'XhrResponse' events,
48+ -- parsing the body of the response however appropriate. A really
49+ -- common pattern is turning the 'Event' into a 'Dynamic' with
50+ -- 'holdDyn' or a related function.
51+ --
52+ -- Here is an example of calling a search API whenever the user
53+ -- types in a text input field and printing the result on the page:
54+ --
55+ -- @
56+ -- url query = "http:\/\/example.com\/search?query=" \<> query
57+ --
58+ -- search queries = do
59+ -- responses \<- performRequestAsync $ toRequest \<$> queries
60+ -- return $ view xhrResponse_responseText \<$> responses
61+ -- where toRequest query = XhrRequest \"GET" (url query) def
62+ --
63+ -- main = mainWidget $ do
64+ -- input \<- textInput def
65+ -- let queries = updated $ input ^. textInput_value
66+ -- results \<- search queries
67+ -- asText \<- holdDyn "No results." $ pack . show \<$> results
68+ -- dynText asText
69+ -- @
70+
71+ -- ** XHR Requests
72+ , XhrRequest (..)
73+ , XhrRequestConfig (..)
74+
3375 , xhrRequest
3476 , xhrRequestConfig_headers
3577 , xhrRequestConfig_password
@@ -41,12 +83,48 @@ module Reflex.Dom.Xhr
4183 , xhrRequest_config
4284 , xhrRequest_method
4385 , xhrRequest_url
44− , xhrResponse_body
86+
87+ -- ** Performing Requests
88+ , performMkRequestAsync
89+ , performMkRequestsAsync
90+ , performRequestAsync
91+ , performRequestAsyncWithError
92+ , performRequestsAsync
93+ , performRequestsAsyncWithError
94+
95+ -- ** XHR Responses
96+ , XhrResponse (..)
97+ , XhrResponseBody (..)
98+ , XhrResponseHeaders (..)
99+ , XhrResponseType (..)
100+
45101 , xhrResponse_response
46102 , xhrResponse_responseText
47103 , xhrResponse_status
48104 , xhrResponse_statusText
49105 , xhrResponse_headers
106+
107+ -- *** Deprecated
108+ , xhrResponse_body
109+ , _xhrResponse_body
110+
111+ -- ** Error Handling
112+ , XhrException (..)
113+ , IsXhrPayload (..)
114+
115+ -- * JavaScript XMLHttpRequest Objects
116+
117+ -- | 'XMLHttpRequest' is the type of JavaScript's underlying runtime
118+ -- objects that represent XHR requests.
119+ --
120+ -- Chances are you shouldn't need these in day-to-day code.
121+ , XMLHttpRequest
122+
123+ -- ** Constructors
124+ , newXMLHttpRequest
125+ , newXMLHttpRequestWithError
126+
127+ -- ** Fields
50128 , xmlHttpRequestGetReadyState
51129 , xmlHttpRequestGetResponseText
52130 , xmlHttpRequestGetStatus