@@ -6,30 +6,72 @@
6{-# LANGUAGE MultiParamTypeClasses #-}
6{-# LANGUAGE MultiParamTypeClasses #-}
7{-# LANGUAGE OverloadedStrings #-}
7{-# LANGUAGE OverloadedStrings #-}
8{-# LANGUAGE TemplateHaskell #-}
8{-# LANGUAGE TemplateHaskell #-}
10+-- | A module for performing asynchronous HTTP calls from JavaScript
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.
15+-- The API has two components:
17+-- * convenient functions for common usecases like GET and POST
18+-- requests to APIs using JSON.
20+-- * a flexible set of functions for creating and executing arbitrary
21+-- requests and handling responses.
9module Reflex.Dom.Xhr
23module Reflex.Dom.Xhr
10− ( XMLHttpRequest
24+ ( -- * Common Patterns
12− , XhrRequestConfig (..)
26+ -- | Functions that conveniently expose common uses like GET and
13− , XhrResponse (..)
27+ -- POST to JSON APIs.
14− , XhrResponseBody (..)
15− , XhrResponseHeaders (..)
16− , XhrResponseType (..)
22− , getAndDecode
28+ getAndDecode
25− , newXMLHttpRequestWithError
26− , performMkRequestAsync
27− , performMkRequestsAsync
28− , performRequestAsync
29− , performRequestAsyncWithError
30− , performRequestsAsync
31− , performRequestsAsyncWithError
32 , postJson
30 , postJson
35+ -- * General Request API
37+ -- | This is the most general flow for sending XHR requests:
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
44+ -- 2. Plug the @Event t (XhrRequest a)@ into one of the functions
45+ -- for performing requests like 'performRequestAsync'.
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.
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:
56+ -- url query = "http:\/\/example.com\/search?query=" \<> query
58+ -- search queries = do
59+ -- responses \<- performRequestAsync $ toRequest \<$> queries
60+ -- return $ view xhrResponse_responseText \<$> responses
61+ -- where toRequest query = XhrRequest \"GET" (url query) def
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
73+ , XhrRequestConfig (..)
33 , xhrRequest
75 , xhrRequest
34 , xhrRequestConfig_headers
76 , xhrRequestConfig_headers
35 , xhrRequestConfig_password
77 , xhrRequestConfig_password
@@ -41,12 +83,48 @@ module Reflex.Dom.Xhr
41 , xhrRequest_config
83 , xhrRequest_config
42 , xhrRequest_method
84 , xhrRequest_method
43 , xhrRequest_url
85 , xhrRequest_url
44− , xhrResponse_body
86+
87+ -- ** Performing Requests
88+ , performMkRequestAsync
89+ , performMkRequestsAsync
90+ , performRequestAsync
91+ , performRequestAsyncWithError
92+ , performRequestsAsync
93+ , performRequestsAsyncWithError
97+ , XhrResponseBody (..)
98+ , XhrResponseHeaders (..)
99+ , XhrResponseType (..)
45 , xhrResponse_response
101 , xhrResponse_response
46 , xhrResponse_responseText
102 , xhrResponse_responseText
47 , xhrResponse_status
103 , xhrResponse_status
48 , xhrResponse_statusText
104 , xhrResponse_statusText
49 , xhrResponse_headers
105 , xhrResponse_headers
111+ -- ** Error Handling
115+ -- * JavaScript XMLHttpRequest Objects
117+ -- | 'XMLHttpRequest' is the type of JavaScript's underlying runtime
118+ -- objects that represent XHR requests.
120+ -- Chances are you shouldn't need these in day-to-day code.
125+ , newXMLHttpRequestWithError
50 , xmlHttpRequestGetReadyState
128 , xmlHttpRequestGetReadyState
51 , xmlHttpRequestGetResponseText
129 , xmlHttpRequestGetResponseText
52 , xmlHttpRequestGetStatus
130 , xmlHttpRequestGetStatus