@@ -1,4 +1,4 @@
1−# Reflex / Reflex-Dom Quick(ish) Reference
1+# Reflex Quick(ish) Reference
22
33## Typeclasses
44
@@ -15,16 +15,14 @@ Functions annotated with "[ ]" are *pure*: They operate on Events, Behaviors, o
1515Other functions must operate in some monadic context, because they produce a result "as of now". The annotations are:
1616
1717```haskell
18+[ ] -- Pure function
1819[S] -- Function runs in any monad supporting MonadSample
1920[H] -- Function runs in any monad supporting MonadHold
20−[W] -- Function runs in any monad supporting MonadWidget
2121```
2222
23−Since MonadWidget depends on MonadHold and MonadHold depends on MonadSample, any [S] function also runs in [H] or [W] context, and any [H] function also runs in [W].
23+Since MonadHold depends on MonadSample, any [S] function also runs in [H] context.
2424
25−## Reflex
26−
27−### Functions producing Event
25+## Functions producing Event
2826
2927```haskell
3028-- Trivial Event
@@ -79,7 +77,7 @@ Since MonadWidget depends on MonadHold and MonadHold depends on MonadSample, any
7977[H] headTailE :: Event a -> m (Event a, Event a)
8078```
8179
82−### Functions producing Behavior
80+## Functions producing Behavior
8381
8482```haskell
8583-- Trivial Behavior
@@ -105,7 +103,7 @@ Since MonadWidget depends on MonadHold and MonadHold depends on MonadSample, any
105103 -- Note supplied value is in [S] context
106104```
107105
108−### Functions producing Dynamic
106+## Functions producing Dynamic
109107
110108```haskell
111109-- Trivial Dynamic
@@ -143,7 +141,7 @@ Since MonadWidget depends on MonadHold and MonadHold depends on MonadSample, any
143141[ ] traceDynWith :: (a -> String) -> Dynamic a -> Dynamic a
144142```
145143
146−### Flattening functions
144+## Flattening functions
147145
148146These functions flatten nested types such as Event-of-Event, Behavior-of-Event, Event-of-Behavior etc, removing the outer wrapper.
149147
@@ -170,213 +168,3 @@ For Events, the returned Event fires whenever the latest Event supplied by the w
170168-- Flatten Event-of-Behavior to monadic Behavior
171169[H] switcher :: Behavior a -> Event (Behavior a) -> m (Behavior a)
172170```
173−
174−## Reflex-Dom
175−
176−### Creating widgets (DOM elements hooked into the FRP system)
177−
178−#### Basic widgets
179−
180−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.
181−
182−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.
183−
184−```haskell
185−-- Simplest form. Create a widget of given type containing the given child.
186−-- Return whatever the child returns.
187−[W] el :: String -> m a -> m a
188−
189−-- This version returns the 'El' as well.
190−[W] el' :: String -> m a -> m (El, a)
191−
192−-- These two additionally apply attributes to the element, such as ("class" =: "blah")
193−[W] elAttr :: String -> Map String String -> m a -> m a
194−[W] elAttr' :: String -> Map String String -> m a -> m (El, a)
195−
196−-- As above, but now the attribute map is Dynamic
197−[W] elDynAttr :: String -> Dynamic (Map String String) -> m a -> m a
198−[W] elDynAttr' :: String -> Dynamic (Map String String) -> m a -> m (El, a)
199−
200−-- Shortcut for elAttr when you only want to set the "class" attribute.
201−[W] elClass :: String -> String -> m a -> m a
202−
203−-- Even shorter-cut for above when element type is "div". Create a div of given class.
204−[W] divClass :: String -> m a -> m a
205−
206−-- Create a widget of given type with arbitrary, Dymamic HTML inside.
207−[W] elDynHtml' :: String -> Dynamic String -> m El
208−[W] elDynHtmlAttr' :: String -> Map String String -> Dynamic String -> m El
209−
210−-- Shortcut for elDynHtml' where the type is "div" and you don't need the 'El'.
211−[W] dynHtml :: Dynamic String -> m ()
212−
213−-- Create a static text element
214−[W] text :: String -> m ()
215−
216−-- Create a dynamic text element
217−[W] dynText :: Dynamic String -> m ()
218−[W] display :: Show a => Dynamic a -> m ()
219−
220−-- Create a "button" element with given label, return onClick Event
221−[W] button :: String -> m (Event ())
222−
223−-- Empty widget
224−[W] blank :: m ()
225−```
226−
227−#### Dynamic widgets
228−
229−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.
230−
231−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.
232−
233−```haskell
234−-- Given a Dynamic of widget-creating actions, create a widget that is redefined
235−-- whenever the Dynamic updates. The returned Event of widget results occurs when
236−-- the Dynamic does. Note that if type 'a' is an Event, the return value is an
237−-- Event-of-Events that would typically be flattened.
238−[W] dyn :: Dynamic (m a) -> m (Event a)
239−
240−-- Same as dyn, but takes initial value and an update Event instead of a Dynamic.
241−[W] widgetHold :: m a -> Event (m a) -> m (Dynamic a)
242−
243−-- Given a Dynamic key/value map and a function to create a widget for a given
244−-- key & Dynamic value, create a bunch of widgets. Widgets will be created,
245−-- destroyed, and updated appropriately as the map changes. Returns Dynamic map
246−-- from keys to widget results.
247−[W] listWithKey :: Ord k =>
248− Dynamic (Map k v) -> (k -> Dynamic v -> m a ) -> m (Dynamic (Map k a))
249−
250−-- Same as above where the widget constructor doesn't care about the key.
251−[W] list :: Ord k =>
252− Dynamic (Map k v) -> ( Dynamic v -> m a ) -> m (Dynamic (Map k a))
253−
254−-- Even simpler version where there are no keys and we just use a list.
255−[W] simpleList ::
256− Dynamic [v] -> ( Dynamic v -> m a ) -> m (Dynamic [a])
257−
258−-- Like listWithKey specialized for widgets returning (Event a). listWithKey would
259−-- return 'Dynamic (Map k (Event a))' in this scenario, but listViewWithKey flattens
260−-- this to 'Event (Map k a)' via 'switch'.
261−[W] listViewWithKey :: Ord k =>
262− Dynamic (Map k v) -> (k -> Dynamic v -> m (Event a)) -> m (Event (Map k a))
263−
264−-- As above, but there is a "current key", and the widget constructor gets a
265−-- Dynamic Bool indicating if that widget is currently selected. The returned
266−-- Event fires when any of the widgets' returned Events fire, and returns the key
267−-- of an arbitrary firing widget.
268−[W] selectViewListWithKey_ :: Ord k => Dynamic k ->
269− Dynamic (Map k v) -> (k -> Dynamic v -> Dynamic Bool -> m (Event a)) -> m (Event k)
270−
271−-- Same as listWithKey, but takes initial values and an updates Event instead of a Dynamic.
272−[W] listWithKey' :: Ord k =>
273− Map k v -> Event (Map k (Maybe v)) -> (k -> v -> Event v -> m a) -> m (Dynamic (Map k a))
274−
275−-- tableDynAttr
276−-- tabDisplay
277−-- workflow
278−-- workflowView
279−```
280−
281−#### Utility widgets
282−
283−These are useful widgets that are implemented (or could be implemented) in terms of the low-level widgets above.
284−
285−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).
286−
287−```haskell
288−-- Text input.
289−[W] textInput :: TextInputConfig -> m TextInput
290−[ ] textInputGetEnter :: TextInput -> Event ()
291−[W] textArea :: TextAreaConfig -> m TextArea
292−
293−-- Checkbox. The Bool supplies the initial state.
294−[W] checkbox :: Bool -> CheckboxConfig -> m Checkbox
295−
296−-- Dropdown with Dynamic options. First argument is initial state.
297−[W] dropdown :: (Ord k, Show k, Read k) =>
298− k -> Dynamic (Map k String) -> DropdownConfig k -> m (Dropdown k)
299−
300−-- Widget to efficiently display long scrolling lists. Dynamically control number of items in
301−-- list, current scroll position, attributes, and row content. Returns current scroll position
302−-- and current selection. Full documentation in Reflex/Dom/Widget/Lazy.hs
303−[W] virtualListWithSelection :: Ord k => Int -> Int -> Dynamic Int -> Int -> Event Int ->
304− String -> Dynamic (Map String String) -> String -> Dynamic (Map String String) ->
305− (k -> Dynamic v -> m ()) -> Dynamic (Map k v) -> m (Dynamic (Int, Int), Event k)
306−```
307−
308−### Connecting to the real world (I/O)
309−
310−#### Connecting to DOM events
311−
312−```haskell
313−-- Extract the specified Event from an 'El'. The allowable event names, and their
314−-- corresponding data types, are listed in Reflex/Dom/Widget/Basic.hs
315−[ ] domEvent :: EventName en -> El -> Event (EventResultType en)
316−```
317−
318−#### Performing arbitrary I/O in response to Events
319−
320−```haskell
321−-- Run side-effecting actions in Event when it occurs; returned Event contains
322−-- results. Side effects run in (WidgetHost m) monad, which includes [S] and [H]
323−-- and can also do I/O via liftIO
324−[W] performEvent :: Event ( WidgetHost m a) -> m (Event a)
325−
326−-- Just run side-effects; no return Event
327−[W] performEvent_ :: Event ( WidgetHost m ()) -> m ()
328−
329−-- Actions run asynchronously; actions are given a callback to send return values
330−[W] performEventAsync :: Event ((a -> IO ()) -> WidgetHost m ()) -> m (Event a)
331−```
332−
333−#### XMLHttpRequest
334−
335−Convenience functions for XMLHttpRequest. For configuration field details, see Reflex/Dom/Xhr.hs.
336−
337−```haskell
338−-- Given method, URL, and config record (with default instance), construct a request.
339−[ ] xhrRequest :: String -> String -> XhrRequestConfig -> XhrRequest
340−
341−-- Given Event of requests, issue them and produce Event of responses.
342−[W] performRequestAsync :: Event XhrRequest -> m (Event XhrResponse)
343−
344−-- Issue a collection of requests, wait for them ALL to complete, return collected results.
345−[W] performRequestsAsync :: Traversable f => Event (f XhrRequest) -> m (Event (f XhrResponse))
346−
347−-- Convenience function to decode JSON-encoded response.
348−[ ] decodeXhrResponse :: FromJSON a => XhrResponse -> Maybe a
349−
350−-- Simplified interface to "GET" URLs and return decoded results.
351−[W] getAndDecode :: FromJSON a => Event String -> m (Event (Maybe a))
352−```
353−
354−#### Time
355−
356−```haskell
357−-- Given a time interval in seconds and a basis time, create an Event that fires on the given
358−-- interval. The Event will report the number of time intervals elapsed since the basis time
359−-- (and other info, see Reflex/Dom/Time.hs). High load will cause ticks to be dropped.
360−[W] tickLossy :: NominalDiffTime -> UTCTime -> m (Event t TickInfo)
361−
362−-- Delay an Event's occurences by a given amount in seconds.
363−[W] delay :: NominalDiffTime -> Event t a -> m (Event t a)
364−```
365−
366−### Startup
367−
368−```haskell
369−-- Reflex-Dom entry point. Takes a monadic widget-building action of lengthy
370−-- type and turns it into an IO action.
371−[I] mainWidget ::
372− Widget Spider (Gui Spider (WithWebView SpiderHost) (HostFrame Spider)) () -> IO ()
373−[I] mainWidgetWithHead ::
374− Widget Spider (Gui Spider (WithWebView SpiderHost) (HostFrame Spider)) () ->
375− Widget Spider (Gui Spider (WithWebView SpiderHost) (HostFrame Spider)) () -> IO ()
376−[I] mainWidgetWithCss ::
377− ByteString ->
378− Widget Spider (Gui Spider (WithWebView SpiderHost) (HostFrame Spider)) () -> IO ()
379−
380−-- One-shot Event that is triggered once all initial widgets are built
381−[W] getPostBuild :: m (Event ())
382−```