1# Reflex / Reflex-Dom Quick(ish) Reference
5Many Reflex functions operate in monadic context `X a`, where the monadic type X supports various additional typeclasses such as MonadWidget, MonadHold, or MonadSample in addition to Monad itself. For Reflex-Dom users, the type X will generally be `Widget Spider (Gui Spider (WithWebView SpiderHost) (HostFrame Spider))`, from the Reflex-Dom main entry point:
8mainWidget :: Widget Spider (Gui Spider (WithWebView SpiderHost) (HostFrame Spider)) () -> IO ()
11The function signatures here have been simplified by removing many typeclass constraints and adding simple annotations to each function. Also the ubiquitous 't' type parameter has been removed.
13Functions annotated with "[ ]" are *pure*: They operate on Events, Behaviors, or Dynamics uniformly without regard to the "current time".
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[H] -- Function runs in any monad supporting MonadHold
20[W] -- Function runs in any monad supporting MonadWidget
23Since 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].
27### Functions producing Event
33-- Extract Event from Dynamic
34[ ] updated :: Dynamic a -> Event a
36-- Transform Event to Event using function
37[ ] fmap :: (a -> b) -> Event a -> Event b
38[ ] fmapMaybe :: (a -> Maybe b) -> Event a -> Event b
39[ ] ffor :: Event a -> (a -> b) -> Event b
40[ ] fforMaybe :: Event a -> (a -> Maybe b) -> Event b
41[ ] ffilter :: (a -> Bool) -> Event a -> Event a
42[ ] splitE :: Event (a, b) -> (Event a, Event b)
44-- Event to identical Event with debug trace.
45[ ] traceEvent :: Show a => String -> Event a -> Event a
46[ ] traceEventWith :: (a -> String) -> Event a -> Event a
48-- Transform Event to Event by sampling Behavior or Dynamic
49[ ] tag :: Behavior b -> Event a -> Event b
50[ ] tagDyn :: Dynamic a -> Event b -> Event a
51[ ] gate :: Behavior Bool -> Event a -> Event a
52[ ] attach :: Behavior a -> Event b -> Event (a, b)
53[ ] attachDyn :: Dynamic a -> Event b -> Event (a, b)
54[ ] attachWith :: (a -> b -> c) -> Behavior a -> Event b -> Event c
55[ ] attachDynWith :: (a -> b -> c) -> Dynamic a -> Event b -> Event c
56[ ] attachWithMaybe :: (a -> b -> Maybe c) -> Behavior a -> Event b -> Event c
57[ ] attachDynWithMaybe :: (a -> b -> Maybe c) -> Dynamic a -> Event b -> Event c
59-- Combine multiple Events
60[ ] <> :: Monoid a => Event a -> Event a -> Event a
61[ ] mergeWith :: (a -> a -> a) -> [Event a] -> Event a
62[ ] leftmost :: [Event a] -> Event a
63[ ] mergeList :: [Event a] -> Event (NonEmpty a)
64[ ] merge :: GCompare k => DMap (WrapArg Event k) -> Event (DMap k)
65[ ] mergeMap :: Ord k => Map k (Event a) -> Event (Map k a)
67-- Efficient one-to-many fanout
68[ ] fan :: GCompare k => Event (DMap k) -> EventSelector k
69[ ] fanMap :: Ord k => Event (Map k a) -> EventSelector (Const2 k a)
70[ ] select :: EventSelector k -> k a -> Event a
72-- Event to Event via monadic function
73[ ] push :: (a -> m (Maybe b)) -> Event a -> Event b
74[ ] pushAlways :: (a -> m b) -> Event a -> Event b
75 -- Note supplied function operates in [H] context
77-- Event to monadic Event
78[H] headE :: Event a -> m (Event a)
79[H] tailE :: Event a -> m (Event a)
80[H] headTailE :: Event a -> m (Event a, Event a)
83### Event flattening functions
85These functions flatten Event-of-Event, Behavior-of-Event, or Dynamic-of-Event into Event, where the returned Event fires whenever the latest Event supplied by the wrapper fires. There are subtle differences in how they handle *coincidences* -- situations where the old or new Event fires at the same instant that we switch from old to new. In some cases, the output Event tracks the old Event at the instant of switchover, while in other cases it tracks the new Event.
88-- Flatten Event-of-Event to monadic Event. New Event is used immediately.
89[H] switchPromptly :: Event a -> Event (Event a) -> m (Event a)
91-- Flatten Behavior-of-Event to Event. Old Event is used during switchover.
92[ ] switch :: Behavior (Event a) -> Event a
94-- Flatten Dyanmic-of-Event to Event. New Event is used immediately.
95[ ] switchPromptlyDyn :: Dynamic (Event a) -> Event a
97-- Flatten Event-of-Event to Event that fires when both wrapper and new Event fire.
98[ ] coincidence :: Event (Event a) -> Event a
101### Functions producing Behavior
105[ ] constant :: a -> Behavior a
107-- Extract Behavior from Dynamic
108[ ] current :: Dynamic a -> Behavior a
110-- Transform Behavior to Behavior using function
111[ ] fmap :: (a -> b) -> Behavior a -> Behavior b
112[ ] ffor :: Behavior a -> (a -> b) -> Behavior b
113[ ] <*> :: Behavior (a -> b) -> Behavior a -> Behavior b
114[ ] >>= :: Behavior a -> (a -> Behavior b) -> Behavior b
115[ ] <> :: Monoid a => Behavior a -> Behavior a -> Behavior a
117-- Behavior to Behavior via monadic value
118[S] sample :: Behavior a -> m a
119[ ] pull :: m a -> Behavior a
120 -- Note supplied value is in [S] context
122-- Event to monadic Behavior
123[H] hold :: a -> Event a -> m (Behavior a)
125-- Flatten Event-of-Behavior to monadic Behavior
126[H] switcher :: Behavior a -> Event (Behavior a) -> m (Behavior a)
129### Functions producing Dynamic
133[ ] constDyn :: a -> Dynamic a
135-- Construct Dynamic from Event
136[H] holdDyn :: a -> Event a -> m (Dynamic a)
137[H] foldDyn :: (a -> b -> b) -> b -> Event a -> m (Dynamic b)
138[H] foldDynM :: (a -> b -> m' b) -> b -> Event a -> m (Dynamic b)
139 -- Note supplied function operates in [H] context
140[H] count :: Num b => Event a -> m (Dynamic b)
141[H] toggle :: Bool -> Event a -> m (Dynamic Bool)
143-- Transform Dynamic to Dynamic using function
144[H] mapDyn :: (a -> b) -> Dynamic a -> m (Dynamic b)
145[H] forDyn :: Dynamic a -> (a -> b) -> m (Dynamic b)
146[H] mapDynM :: (a -> m' b) -> Dynamic a -> m (Dynamic b)
147 -- Note supplied function runs in [S] context
148[H] splitDyn :: Dynamic (a, b) -> m (Dynamic a, Dynamic b)
150-- Combine multiple Dynamics
151[H] mconcatDyn :: Monoid a => [Dynamic a] -> m (Dynamic a)
152[H] distributeDMapOverDyn :: GCompare k => DMap (WrapArg Dynamic k) -> m (Dynamic (DMap k))
153[H] combineDyn :: (a -> b -> c) -> Dynamic a -> Dynamic b -> m (Dynamic c)
155-- Efficient one-to-many fanout
156[ ] demux :: Ord k => Dynamic k -> Demux k
157[H] getDemuxed :: Eq k => Demux k -> k -> m (Dynamic Bool)
159-- Dynamic to Dynamic, removing updates w/o value change
160[ ] nubDyn :: Eq a => Dynamic a -> Dynamic a
162-- Dynamic to identical Dynamic with debug trace.
163[ ] traceDyn :: Show a => String -> Dynamic a -> Dynamic a
164[ ] traceDynWith :: (a -> String) -> Dynamic a -> Dynamic a
166-- Flatten Dynamic-of-Dynamic to Dynamic. New Dynamic is used immediately.
167-- Output updated whenever inner or outer Dynamic updates.
168[ ] joinDyn :: Dynamic (Dynamic a) -> Dynamic a
169[ ] joinDynThroughMap :: Ord k => Dynamic (Map k (Dynamic a)) -> Dynamic (Map k a)
174### Creating widgets (DOM elements hooked into the FRP system)
178These 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.
180Widgets 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-- Simplest form. Create a widget of given type containing the given child.
184-- Return whatever the child returns.
185[W] el :: String -> m a -> m a
187-- This version returns the 'El' as well.
188[W] el' :: String -> m a -> m (El, a)
190-- These two additionaly apply attributes to the element, such as ("class" =: "blah")
191[W] elAttr :: String -> Map String String -> m a -> m a
192[W] elAttr' :: String -> Map String String -> m a -> m (El, a)
194-- As above, but now the attribute map is Dynamic
195[W] elDynAttr :: String -> Dynamic (Map String String) -> m a -> m a
196[W] elDynAttr' :: String -> Dynamic (Map String String) -> m a -> m (El, a)
198-- Shortcut for elAttr when you only want to set the "class" attribute.
199[W] elClass :: String -> String -> m a -> m a
201-- Even shorter-cut for above when element type is "div". Create a div of given class.
202[W] divClass :: String -> m a -> m a
204-- Create a widget of given type with arbitrary, Dymamic HTML inside.
205[W] elDynHtml' :: String -> Dynamic String -> m El
206[W] elDynHtmlAttr' :: String -> Map String String -> Dynamic String -> m El
208-- Shortcut for elDynHtml' where the type is "div" and you don't need the 'El'.
209[W] dynHtml :: Dynamic String -> m ()
211-- Create a static text element
212[W] text :: String -> m ()
214-- Create a dynamic text element
215[W] dynText :: Dynamic String -> m ()
216[W] display :: Show a => Dynamic a -> m ()
218-- Create a "button" element with given label, return onClick Event
219[W] button :: String -> m (Event ())
227In the Dynamic cases above, 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.
229Note 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-- Given a Dynamic of widget-creating actions, create a widget that is redefined whenever the Dynamic updates.
233-- The returned Event of widget results occurs when the Dynamic does. Note that if type 'a' is an Event, the
234-- return value is an Event-of-Events that would typically be flattened.
235[W] dyn :: Dynamic (m a) -> m (Event a)
237-- Same as dyn, but takes initial value and an update Event instead of a Dynamic.
238[W] widgetHold :: m a -> Event (m a) -> m (Dynamic a)
240-- Given a Dynamic key/value map and a function to create a widget for a given
241-- key & Dynamic value, create a bunch of widgets. Widgets will be created,
242-- destroyed, and updated appropriately as the map changes. Returns Dynamic map
243-- from keys to widget results.
244[W] listWithKey :: Ord k => Dynamic (Map k v) -> (k -> Dynamic v -> m a) -> m (Dynamic (Map k a))
246-- Same as above where the widget constructor doesn't care about the key.
247[W] list :: Ord k => Dynamic (Map k v) -> (Dynamic v -> m a) -> m (Dynamic (Map k a))
249-- Even simpler version where there are no keys and we just use a list.
250[W] simpleList :: Dynamic [v] -> (Dynamic v -> m a) -> m (Dynamic [a])
252-- Same as listWithKey, but takes initial values and an updates Event instead of a Dynamic.
253[W] listWithKey' :: Ord k => Map k v -> Event (Map k (Maybe v)) -> (k -> v -> Event v -> m a) -> m (Dynamic (Map k a))
255-- Like listWithKey specialized for widgets returning (Event a). listWithKey would return 'Dynamic (Map k (Event a))'
256-- in this scenario, but listViewWithKey flattens this to 'Event (Map k a)' via 'switch'.
257[W] listViewWithKey :: Ord k => Dynamic (Map k v) -> (k -> Dynamic v -> m (Event a)) -> m (Event (Map k a))
259-- As above, but there is a "current key", and the widget constructor gets a Dynamic Bool indicating if that widget
260-- is currently selected. The returned Event fires when any of the widgets' returned Events fire, and returns the key
261-- of an arbitrary firing widget.
262[W] selectViewListWithKey_ :: Ord k => Dynamic k -> Dynamic (Map k v) -> (k -> Dynamic v -> Dynamic Bool -> m (Event a)) -> m (Event k)
270### Connecting to the real world (I/O)
272#### Connecting to DOM events
275-- Extract the specified Event from an 'El'. The allowable event names, and their corresponding
276-- data types, are listed in Reflex/Dom/Widget/Basic.hs
277[ ] domEvent :: EventName en -> El -> Event (EventResultType en)
280#### Performing arbitrary I/O in response to Events
283-- Run side-effecting actions in Event when it occurs; returned Event contains results.
284-- Side effects run in (WidgetHost m) monad, which includes [S] and [H] and can also do I/O via liftIO
285[W] performEvent :: Event (WidgetHost m a) -> m (Event a)
287-- Just run side-effects; no return Event
288[W] performEvent_ :: Event (WidgetHost m ()) -> m ()
290-- Actions are run asynchronously; each action is given a callback to call when it completes
291[W] performEventAsync :: Event ((a -> IO ()) -> WidgetHost m ()) -> m (Event a)
297-- Reflex-Dom entry point. Takes a monadic widget-building action of lengthy type and turns it into an IO action.
298[I] mainWidget :: Widget Spider (Gui Spider (WithWebView SpiderHost) (HostFrame Spider)) () -> IO ()
299[I] mainWidgetWithHead :: Widget Spider (Gui Spider (WithWebView SpiderHost) (HostFrame Spider)) () -> Widget Spider (Gui Spider (WithWebView SpiderHost) (HostFrame Spider)) () -> IO ()
300[I] mainWidgetWithCss :: ByteString -> Widget Spider (Gui Spider (WithWebView SpiderHost) (HostFrame Spider)) () -> IO ()
302-- One-shot Event that is triggered once all initial widgets are built
303[W] getPostBuild :: m (Event ())
keysesc to close
- j k
- move down, up
- enter
- open
- esc
- back, or up a level
- 1 2 3 4
- readme, files, commits, refs
- /
- filter
- y
- copy the clone command
- c
- compare the chosen commit with another (or shift-click both)
- ?
- show or hide this list