Quickref.md · reflex-dom

git.iko.soy/reflex-dom

on cale-quitfixes help sign in

reflex-dom/Quickref.md

204 lines 8.8 kB history raw

1# Reflex-Dom Quick(ish) Reference

3## Typeclasses

5Function 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:

7```haskell

8[ ] -- Pure function

9[W] -- Function runs in any monad supporting MonadWidget

10[I] -- Function runs in IO

11```

13Functions from Reflex that run in MonadSample or MonadHold context ([S] or [H]) will also run in [W].

15## Creating widgets (DOM elements hooked into the FRP system)

17### Basic widgets

19These 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.

21Widgets 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.

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

28-- This version returns the 'El' as well.

29[W] el' :: String -> m a -> m (El, a)

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)

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)

39-- Shortcut for elAttr when you only want to set the "class" attribute.

40[W] elClass :: String -> String -> m a -> m a

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

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

49-- Shortcut for elDynHtml' where the type is "div" and you don't need the 'El'.

50[W] dynHtml :: Dynamic String -> m ()

52-- Create a static text element

53[W] text :: String -> m ()

55-- Create a dynamic text element

56[W] dynText :: Dynamic String -> m ()

57[W] display :: Show a => Dynamic a -> m ()

59-- Create a "button" element with given label, return onClick Event

60[W] button :: String -> m (Event ())

62-- Empty widget

63[W] blank :: m ()

64```

66### Dynamic widgets

68In 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.

70Note 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.

72```haskell

73-- Create a dynamically-redefined widget from a Dynamic of widget actions.

74[W] dyn :: Dynamic (m a) -> m (Event a)

76-- Same as dyn, but takes initial value and an update Event instead of a Dynamic.

77[W] widgetHold :: m a -> Event (m a) -> m (Dynamic a)

79-- Turn a Dynamic key/value map into a set of dynamically-changing widgets.

80[W] listWithKey :: Ord k =>

81 Dynamic (Map k v) -> (k -> Dynamic v -> m a ) -> m (Dynamic (Map k a))

83-- Same as above where the widget constructor doesn't care about the key.

84[W] list :: Ord k =>

85 Dynamic (Map k v) -> ( Dynamic v -> m a ) -> m (Dynamic (Map k a))

87-- Even simpler version where there are no keys and we just use a list.

88[W] simpleList ::

89 Dynamic [v] -> ( Dynamic v -> m a ) -> m (Dynamic [a])

91-- Like listWithKey specialized for widgets returning (Event a).

92[W] listViewWithKey :: Ord k =>

93 Dynamic (Map k v) -> (k -> Dynamic v -> m (Event a)) -> m (Event (Map k a))

95-- Create a dynamically-changing set of widgets, one of which is selected at any time.

96[W] selectViewListWithKey_ :: Ord k => Dynamic k ->

97 Dynamic (Map k v) -> (k -> Dynamic v -> Dynamic Bool -> m (Event a)) -> m (Event k)

99-- Same as listWithKey, but takes initial values and an updates Event instead of a Dynamic.

100[W] listWithKey' :: Ord k =>

101 Map k v -> Event (Map k (Maybe v)) -> (k -> v -> Event v -> m a) -> m (Dynamic (Map k a))

102```

103

104### Utility widgets

105

106These are useful widgets that are implemented (or could be implemented) in terms of the low-level widgets above.

107

108Some 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).

109

110```haskell

111-- Text input.

112[W] textInput :: TextInputConfig -> m TextInput

113[ ] textInputGetEnter :: TextInput -> Event ()

114[W] textArea :: TextAreaConfig -> m TextArea

115

116-- Checkbox. The Bool supplies the initial state.

117[W] checkbox :: Bool -> CheckboxConfig -> m Checkbox

118

119-- Dropdown with Dynamic options. First argument is initial state.

120[W] dropdown :: (Ord k, Show k, Read k) =>