@@ -1,4 +1,4 @@
1−# Reflex / Reflex-Dom Quick(ish) Reference
1+# Reflex Quick(ish) Reference
3## Typeclasses
3## Typeclasses
@@ -15,16 +15,14 @@ Functions annotated with "[ ]" are *pure*: They operate on Events, Behaviors, o
15Other functions must operate in some monadic context, because they produce a result "as of now". The annotations are:
15Other functions must operate in some monadic context, because they produce a result "as of now". The annotations are:
18[S] -- Function runs in any monad supporting MonadSample
19[S] -- Function runs in any monad supporting MonadSample
19[H] -- Function runs in any monad supporting MonadHold
20[H] -- Function runs in any monad supporting MonadHold
20−[W] -- Function runs in any monad supporting MonadWidget
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.
27−### Functions producing Event
25+## Functions producing Event
30-- Trivial Event
28-- Trivial Event
@@ -79,7 +77,7 @@ Since MonadWidget depends on MonadHold and MonadHold depends on MonadSample, any
79[H] headTailE :: Event a -> m (Event a, Event a)
77[H] headTailE :: Event a -> m (Event a, Event a)
82−### Functions producing Behavior
80+## Functions producing Behavior
85-- Trivial Behavior
83-- Trivial Behavior
@@ -105,7 +103,7 @@ Since MonadWidget depends on MonadHold and MonadHold depends on MonadSample, any
105 -- Note supplied value is in [S] context
103 -- Note supplied value is in [S] context
108−### Functions producing Dynamic
106+## Functions producing Dynamic
110```haskell
108```haskell
111-- Trivial Dynamic
109-- Trivial Dynamic
@@ -143,7 +141,7 @@ Since MonadWidget depends on MonadHold and MonadHold depends on MonadSample, any
143[ ] traceDynWith :: (a -> String) -> Dynamic a -> Dynamic a
141[ ] traceDynWith :: (a -> String) -> Dynamic a -> Dynamic a
146−### Flattening functions
144+## Flattening functions
148These functions flatten nested types such as Event-of-Event, Behavior-of-Event, Event-of-Behavior etc, removing the outer wrapper.
146These functions flatten nested types such as Event-of-Event, Behavior-of-Event, Event-of-Behavior etc, removing the outer wrapper.
@@ -170,213 +168,3 @@ For Events, the returned Event fires whenever the latest Event supplied by the w
170-- Flatten Event-of-Behavior to monadic Behavior
168-- Flatten Event-of-Behavior to monadic Behavior
171[H] switcher :: Behavior a -> Event (Behavior a) -> m (Behavior a)
169[H] switcher :: Behavior a -> Event (Behavior a) -> m (Behavior a)
176−### Creating widgets (DOM elements hooked into the FRP system)
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.
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.
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
189−-- This version returns the 'El' as well.
190−[W] el' :: String -> m a -> m (El, a)
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)
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)
200−-- Shortcut for elAttr when you only want to set the "class" attribute.
201−[W] elClass :: String -> String -> m a -> m a
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
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
210−-- Shortcut for elDynHtml' where the type is "div" and you don't need the 'El'.
211−[W] dynHtml :: Dynamic String -> m ()
213−-- Create a static text element
214−[W] text :: String -> m ()
216−-- Create a dynamic text element
217−[W] dynText :: Dynamic String -> m ()
218−[W] display :: Show a => Dynamic a -> m ()
220−-- Create a "button" element with given label, return onClick Event
221−[W] button :: String -> m (Event ())
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.
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.
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)
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)
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))
250−-- Same as above where the widget constructor doesn't care about the key.
252− Dynamic (Map k v) -> ( Dynamic v -> m a ) -> m (Dynamic (Map k a))
254−-- Even simpler version where there are no keys and we just use a list.
256− Dynamic [v] -> ( Dynamic v -> m a ) -> m (Dynamic [a])
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))
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)
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))
283−These are useful widgets that are implemented (or could be implemented) in terms of the low-level widgets above.
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).
289−[W] textInput :: TextInputConfig -> m TextInput
290−[ ] textInputGetEnter :: TextInput -> Event ()
291−[W] textArea :: TextAreaConfig -> m TextArea
293−-- Checkbox. The Bool supplies the initial state.
294−[W] checkbox :: Bool -> CheckboxConfig -> m Checkbox
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)
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)
308−### Connecting to the real world (I/O)
310−#### Connecting to DOM events
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)
318−#### Performing arbitrary I/O in response to Events
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)
326−-- Just run side-effects; no return Event
327−[W] performEvent_ :: Event ( WidgetHost m ()) -> m ()
329−-- Actions run asynchronously; actions are given a callback to send return values
330−[W] performEventAsync :: Event ((a -> IO ()) -> WidgetHost m ()) -> m (Event a)
335−Convenience functions for XMLHttpRequest. For configuration field details, see Reflex/Dom/Xhr.hs.
338−-- Given method, URL, and config record (with default instance), construct a request.
339−[ ] xhrRequest :: String -> String -> XhrRequestConfig -> XhrRequest
341−-- Given Event of requests, issue them and produce Event of responses.
342−[W] performRequestAsync :: Event XhrRequest -> m (Event XhrResponse)
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))
347−-- Convenience function to decode JSON-encoded response.
348−[ ] decodeXhrResponse :: FromJSON a => XhrResponse -> Maybe a
350−-- Simplified interface to "GET" URLs and return decoded results.
351−[W] getAndDecode :: FromJSON a => Event String -> m (Event (Maybe a))
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)
362−-- Delay an Event's occurences by a given amount in seconds.
363−[W] delay :: NominalDiffTime -> Event t a -> m (Event t a)
369−-- Reflex-Dom entry point. Takes a monadic widget-building action of lengthy
370−-- type and turns it into an IO action.
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 ::
378− Widget Spider (Gui Spider (WithWebView SpiderHost) (HostFrame Spider)) () -> IO ()
380−-- One-shot Event that is triggered once all initial widgets are built
381−[W] getPostBuild :: m (Event ())