git.iko.soy/reflex-dom
on develop help sign in
Broke the documentation into sections and added a high-level description of the general request flow.
f6021eaTikhon Jelvis
src/Reflex/Dom/Xhr.hs+77−21
compare with develop
unifiedsplit
@@ -6,30 +6,51 @@
6{-# LANGUAGE MultiParamTypeClasses #-}
6{-# LANGUAGE MultiParamTypeClasses #-}
7{-# LANGUAGE OverloadedStrings #-}
7{-# LANGUAGE OverloadedStrings #-}
8{-# LANGUAGE TemplateHaskell #-}
8{-# 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+--
9module Reflex.Dom.Xhr
23module Reflex.Dom.Xhr
10− ( XMLHttpRequest
24+ ( -- * Common Patterns
11− , XhrRequest (..)
25+
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 (..)
17− , XhrException (..)
18− , IsXhrPayload (..)
19− , _xhrResponse_body
20− , decodeText
21− , decodeXhrResponse
22− , getAndDecode
28+ getAndDecode
23 , getMay
29 , getMay
24− , newXMLHttpRequest
25− , newXMLHttpRequestWithError
26− , performMkRequestAsync
27− , performMkRequestsAsync
28− , performRequestAsync
29− , performRequestAsyncWithError
30− , performRequestsAsync
31− , performRequestsAsyncWithError
32 , postJson
30 , 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+
33 , xhrRequest
54 , xhrRequest
34 , xhrRequestConfig_headers
55 , xhrRequestConfig_headers
35 , xhrRequestConfig_password
56 , xhrRequestConfig_password
@@ -41,12 +62,46 @@ module Reflex.Dom.Xhr
41 , xhrRequest_config
62 , xhrRequest_config
42 , xhrRequest_method
63 , xhrRequest_method
43 , xhrRequest_url
64 , 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+
44 , xhrResponse_body
80 , xhrResponse_body
45 , xhrResponse_response
81 , xhrResponse_response
46 , xhrResponse_responseText
82 , xhrResponse_responseText
47 , xhrResponse_status
83 , xhrResponse_status
48 , xhrResponse_statusText
84 , xhrResponse_statusText
49 , xhrResponse_headers
85 , 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
50 , xmlHttpRequestGetReadyState
105 , xmlHttpRequestGetReadyState
51 , xmlHttpRequestGetResponseText
106 , xmlHttpRequestGetResponseText
52 , xmlHttpRequestGetStatus
107 , xmlHttpRequestGetStatus
@@ -56,6 +111,7 @@ module Reflex.Dom.Xhr
56 , xmlHttpRequestOpen
111 , xmlHttpRequestOpen
57 , xmlHttpRequestSetRequestHeader
112 , xmlHttpRequestSetRequestHeader
58 , xmlHttpRequestSetResponseType
113 , xmlHttpRequestSetResponseType
114+
59 )
115 )
60where
116where
61
117