@@ -6,30 +6,51 @@
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.
49+
50+ -- ** XHR Requests
51+ , XhrRequest (..)
52+ , XhrRequestConfig (..)
53+
3354 , xhrRequest
3455 , xhrRequestConfig_headers
3556 , xhrRequestConfig_password
@@ -41,12 +62,46 @@ module Reflex.Dom.Xhr
4162 , xhrRequest_config
4263 , xhrRequest_method
4364 , xhrRequest_url
65+
66+ -- ** Performing Requests
67+ , performMkRequestAsync
68+ , performMkRequestsAsync
69+ , performRequestAsync
70+ , performRequestAsyncWithError
71+ , performRequestsAsync
72+ , performRequestsAsyncWithError
73+
74+ -- ** XHR Responses
75+ , XhrResponse (..)
76+ , XhrResponseBody (..)
77+ , XhrResponseHeaders (..)
78+ , XhrResponseType (..)
79+
4480 , xhrResponse_body
4581 , xhrResponse_response
4682 , xhrResponse_responseText
4783 , xhrResponse_status
4884 , xhrResponse_statusText
4985 , xhrResponse_headers
86+
87+ -- ** Error Handling
88+ , XhrException (..)
89+ , IsXhrPayload (..)
90+ , _xhrResponse_body
91+
92+ -- * JavaScript XMLHttpRequest Objects
93+
94+ -- | 'XMLHttpRequest' is the type of JavaScript's underlying runtime
95+ -- objects that represent XHR requests.
96+ --
97+ -- Chances are you shouldn't need these in day-to-day code.
98+ , XMLHttpRequest
99+
100+ -- ** Constructors
101+ , newXMLHttpRequest
102+ , newXMLHttpRequestWithError
103+
104+ -- ** Fields
50105 , xmlHttpRequestGetReadyState
51106 , xmlHttpRequestGetResponseText
52107 , xmlHttpRequestGetStatus
@@ -56,6 +111,7 @@ module Reflex.Dom.Xhr
56111 , xmlHttpRequestOpen
57112 , xmlHttpRequestSetRequestHeader
58113 , xmlHttpRequestSetResponseType
114+
59115 )
60116where
61117