@@ -0,0 +1,221 @@
1+# Reflex-Dom Quick(ish) Reference
2+
3+## Typeclasses
4+
5+Function signatures have been simplified. The 't' type parameter and many typeclass constraints are removed, and annotations are added regarding the monad of the result type (See the Reflex Quickstart for more discussion). Annotations:
6+
7+```haskell
8+[ ] -- Pure function
9+[W] -- Function runs in any monad supporting MonadWidget
10+[I] -- Function runs in IO
11+```
12+
13+Functions from Reflex that run in MonadSample or MonadHold context ([S] or [H]) will also run in [W].
14+
15+## Creating widgets (DOM elements hooked into the FRP system)
16+
17+### Basic widgets
18+
19+These functions generally take an element tag (such as "div", "h1", etc) and a child widget, and produce a widget of the given type containing the child. Some of these functions return data of type `El`, which is a handle to the created DOM element along with a set of potential Events that might occur on that element.
20+
21+Widgets may return any type (this is 'a' in many of the functions below). Often this will be an Event carrying user interactions with the widget.
22+
23+```haskell
24+-- Simplest form. Create a widget of given type containing the given child.
25+-- Return whatever the child returns.
26+[W] el :: String -> m a -> m a
27+
28+-- This version returns the 'El' as well.
29+[W] el' :: String -> m a -> m (El, a)
30+
31+-- These two additionally apply attributes to the element, such as ("class" =: "blah")
32+[W] elAttr :: String -> Map String String -> m a -> m a
33+[W] elAttr' :: String -> Map String String -> m a -> m (El, a)
34+
35+-- As above, but now the attribute map is Dynamic
36+[W] elDynAttr :: String -> Dynamic (Map String String) -> m a -> m a
37+[W] elDynAttr' :: String -> Dynamic (Map String String) -> m a -> m (El, a)
38+
39+-- Shortcut for elAttr when you only want to set the "class" attribute.
40+[W] elClass :: String -> String -> m a -> m a
41+
42+-- Even shorter-cut for above when element type is "div". Create a div of given class.
43+[W] divClass :: String -> m a -> m a
44+
45+-- Create a widget of given type with arbitrary, Dymamic HTML inside.
46+[W] elDynHtml' :: String -> Dynamic String -> m El
47+[W] elDynHtmlAttr' :: String -> Map String String -> Dynamic String -> m El
48+
49+-- Shortcut for elDynHtml' where the type is "div" and you don't need the 'El'.
50+[W] dynHtml :: Dynamic String -> m ()
51+
52+-- Create a static text element
53+[W] text :: String -> m ()
54+
55+-- Create a dynamic text element
56+[W] dynText :: Dynamic String -> m ()
57+[W] display :: Show a => Dynamic a -> m ()
58+
59+-- Create a "button" element with given label, return onClick Event
60+[W] button :: String -> m (Event ())
61+
62+-- Empty widget
63+[W] blank :: m ()
64+```
65+
66+### Dynamic widgets
67+
68+In the Dynamic cases so far, the *content* of a widget is dynamic but the *definition* of the widget is static. The functions below enable the definition and/or structure of the widget itself to change over time.
69+
70+Note the "list" functions do not imply particular HTML tags (ul, li, etc), though the widgets they create can have those tags if you construct them appropriately.
71+
72+```haskell
73+-- Given a Dynamic of widget-creating actions, create a widget that is redefined
74+-- whenever the Dynamic updates. The returned Event of widget results occurs when
75+-- the Dynamic does. Note that if type 'a' is an Event, the return value is an
76+-- Event-of-Events that would typically be flattened.
77+[W] dyn :: Dynamic (m a) -> m (Event a)
78+
79+-- Same as dyn, but takes initial value and an update Event instead of a Dynamic.
80+[W] widgetHold :: m a -> Event (m a) -> m (Dynamic a)
81+
82+-- Given a Dynamic key/value map and a function to create a widget for a given
83+-- key & Dynamic value, create a bunch of widgets. Widgets will be created,
84+-- destroyed, and updated appropriately as the map changes. Returns Dynamic map
85+-- from keys to widget results.
86+[W] listWithKey :: Ord k =>
87+ Dynamic (Map k v) -> (k -> Dynamic v -> m a ) -> m (Dynamic (Map k a))
88+
89+-- Same as above where the widget constructor doesn't care about the key.
90+[W] list :: Ord k =>
91+ Dynamic (Map k v) -> ( Dynamic v -> m a ) -> m (Dynamic (Map k a))
92+
93+-- Even simpler version where there are no keys and we just use a list.
94+[W] simpleList ::
95+ Dynamic [v] -> ( Dynamic v -> m a ) -> m (Dynamic [a])
96+
97+-- Like listWithKey specialized for widgets returning (Event a). listWithKey would
98+-- return 'Dynamic (Map k (Event a))' in this scenario, but listViewWithKey flattens
99+-- this to 'Event (Map k a)' via 'switch'.
100+[W] listViewWithKey :: Ord k =>
101+ Dynamic (Map k v) -> (k -> Dynamic v -> m (Event a)) -> m (Event (Map k a))
102+
103+-- As above, but there is a "current key", and the widget constructor gets a
104+-- Dynamic Bool indicating if that widget is currently selected. The returned
105+-- Event fires when any of the widgets' returned Events fire, and returns the key
106+-- of an arbitrary firing widget.
107+[W] selectViewListWithKey_ :: Ord k => Dynamic k ->
108+ Dynamic (Map k v) -> (k -> Dynamic v -> Dynamic Bool -> m (Event a)) -> m (Event k)
109+
110+-- Same as listWithKey, but takes initial values and an updates Event instead of a Dynamic.
111+[W] listWithKey' :: Ord k =>
112+ Map k v -> Event (Map k (Maybe v)) -> (k -> v -> Event v -> m a) -> m (Dynamic (Map k a))
113+
114+-- tableDynAttr
115+-- tabDisplay
116+-- workflow
117+-- workflowView
118+```
119+
120+### Utility widgets
121+
122+These are useful widgets that are implemented (or could be implemented) in terms of the low-level widgets above.
123+
124+Some of these widget builders take a configuration record and return a record containing Events or other useful data associated with the created widget (similar to 'El'). The configuration records have default values, so you can just supply 'def'. See Reflex/Dom/Widget/Input.hs for record fields (Lenses are provided).
125+
126+```haskell
127+-- Text input.
128+[W] textInput :: TextInputConfig -> m TextInput
129+[ ] textInputGetEnter :: TextInput -> Event ()
130+[W] textArea :: TextAreaConfig -> m TextArea
131+
132+-- Checkbox. The Bool supplies the initial state.
133+[W] checkbox :: Bool -> CheckboxConfig -> m Checkbox
134+
135+-- Dropdown with Dynamic options. First argument is initial state.
136+[W] dropdown :: (Ord k, Show k, Read k) =>
137+ k -> Dynamic (Map k String) -> DropdownConfig k -> m (Dropdown k)
138+
139+-- Widget to efficiently display long scrolling lists. Dynamically control number of items in
140+-- list, current scroll position, attributes, and row content. Returns current scroll position
141+-- and current selection. Full documentation in Reflex/Dom/Widget/Lazy.hs
142+[W] virtualListWithSelection :: Ord k => Int -> Int -> Dynamic Int -> Int -> Event Int ->
143+ String -> Dynamic (Map String String) -> String -> Dynamic (Map String String) ->
144+ (k -> Dynamic v -> m ()) -> Dynamic (Map k v) -> m (Dynamic (Int, Int), Event k)
145+```
146+
147+## Connecting to the real world (I/O)
148+
149+### Connecting to DOM events
150+
151+```haskell
152+-- Extract the specified Event from an 'El'. The allowable event names, and their
153+-- corresponding data types, are listed in Reflex/Dom/Widget/Basic.hs
154+[ ] domEvent :: EventName en -> El -> Event (EventResultType en)
155+```
156+
157+### Performing arbitrary I/O in response to Events
158+
159+```haskell
160+-- Run side-effecting actions in Event when it occurs; returned Event contains
161+-- results. Side effects run in (WidgetHost m) monad, which includes [S] and [H]
162+-- and can also do I/O via liftIO
163+[W] performEvent :: Event ( WidgetHost m a) -> m (Event a)
164+
165+-- Just run side-effects; no return Event
166+[W] performEvent_ :: Event ( WidgetHost m ()) -> m ()
167+
168+-- Actions run asynchronously; actions are given a callback to send return values
169+[W] performEventAsync :: Event ((a -> IO ()) -> WidgetHost m ()) -> m (Event a)
170+```
171+
172+### XMLHttpRequest
173+
174+Convenience functions for XMLHttpRequest. For configuration field details, see Reflex/Dom/Xhr.hs.
175+
176+```haskell
177+-- Given method, URL, and config record (with default instance), construct a request.
178+[ ] xhrRequest :: String -> String -> XhrRequestConfig -> XhrRequest
179+
180+-- Given Event of requests, issue them and produce Event of responses.
181+[W] performRequestAsync :: Event XhrRequest -> m (Event XhrResponse)
182+
183+-- Issue a collection of requests, wait for them ALL to complete, return collected results.
184+[W] performRequestsAsync :: Traversable f => Event (f XhrRequest) -> m (Event (f XhrResponse))
185+
186+-- Convenience function to decode JSON-encoded response.
187+[ ] decodeXhrResponse :: FromJSON a => XhrResponse -> Maybe a
188+
189+-- Simplified interface to "GET" URLs and return decoded results.
190+[W] getAndDecode :: FromJSON a => Event String -> m (Event (Maybe a))
191+```
192+
193+### Time
194+
195+```haskell
196+-- Given a time interval in seconds and a basis time, create an Event that fires on the given
197+-- interval. The Event will report the number of time intervals elapsed since the basis time
198+-- (and other info, see Reflex/Dom/Time.hs). High load will cause ticks to be dropped.
199+[W] tickLossy :: NominalDiffTime -> UTCTime -> m (Event t TickInfo)
200+
201+-- Delay an Event's occurences by a given amount in seconds.
202+[W] delay :: NominalDiffTime -> Event t a -> m (Event t a)
203+```
204+
205+## Startup
206+
207+```haskell
208+-- Reflex-Dom entry point. Takes a monadic widget-building action of lengthy
209+-- type and turns it into an IO action.
210+[I] mainWidget ::
211+ Widget Spider (Gui Spider (WithWebView SpiderHost) (HostFrame Spider)) () -> IO ()
212+[I] mainWidgetWithHead ::
213+ Widget Spider (Gui Spider (WithWebView SpiderHost) (HostFrame Spider)) () ->
214+ Widget Spider (Gui Spider (WithWebView SpiderHost) (HostFrame Spider)) () -> IO ()
215+[I] mainWidgetWithCss ::
216+ ByteString ->
217+ Widget Spider (Gui Spider (WithWebView SpiderHost) (HostFrame Spider)) () -> IO ()
218+
219+-- One-shot Event that is triggered once all initial widgets are built
220+[W] getPostBuild :: m (Event ())
221+```