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