8585029 · reflex-dom · git.iko.soy

git.iko.soy/reflex-dom

Move longer function descriptions into Haddock.

commit85850299c9d067344ade753f0460994821acca1e authorDan Brown <dbbnrl@gmail.com> dateWed 5 Aug 2015, 15:21 (11 years ago) parentf98b5b7

4 files changed+64−45

compare with develop

unifiedsplit

Quickref.md+15−40 src/Reflex/Dom/Time.hs+1 src/Reflex/Dom/Widget/Basic.hs+43−5 src/Reflex/Dom/Xhr.hs+5

Quickref.md+15−40

@@ -70,19 +70,13 @@ In the Dynamic cases so far, the *content* of a widget is dynamic but the *defin

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

7171

7272```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.

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

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

7875

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

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

8178

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.

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

8680[W] listWithKey :: Ord k =>

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

8882

@@ -94,16 +88,11 @@ Note the "list" functions do not imply particular HTML tags (ul, li, etc), thoug

9488[W] simpleList ::

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

9690

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'.

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

10092[W] listViewWithKey :: Ord k =>

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

10294

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.

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

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

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

10998

@@ -131,25 +120,14 @@ Some of these widget builders take a configuration record and return a record co

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

132121 k -> Dynamic (Map k String) -> DropdownConfig k -> m (Dropdown k)

133122

134−-- Given class, list of columns with (column header, function from row key and Dynamic row

135−-- value to widget), Dynamic map from row key to row value, and function from row key to

136−-- Dynamic row attributes, produce a table widget that returns a Dynamic map from row keys

137−-- to (row El, list of row widget values).

138−[W] tableDynAttr :: (Show k, Ord k) =>

139− String -> [(String, k -> Dynamic r -> m v)] -> Dynamic (Map k r) ->

140− (k -> m (Dynamic (Map String String))) -> m (Dynamic (Map k (El, [v])))

141−

142−-- Construct a tabbed view that shows only one of its child widgets at a time. Takes a class

143−-- for the "ul" element, a class for the currently active "li" element, and a map from arbitrary

144−-- keys to (tab label, tab widget) pairs.

123+-- Table with static columns and dynamic rows.

124+[W] tableDynAttr :: ... -- See Reflex.Dom.Widget.Basic

125+

126+-- Tabbed view that shows only one of its child widgets at a time.

145127[W] tabDisplay :: (Show k, Ord k) => String -> String -> Map k (String, m ()) -> m ()

146128

147−-- Widget to efficiently display long scrolling lists. Dynamically control number of items in

148−-- list, current scroll position, attributes, and row content. Returns current scroll position

149−-- and current selection. Full documentation in Reflex/Dom/Widget/Lazy.hs

150−[W] virtualListWithSelection :: Ord k => Int -> Int -> Dynamic Int -> Int -> Event Int ->

151− String -> Dynamic (Map String String) -> String -> Dynamic (Map String String) ->

152− (k -> Dynamic v -> m ()) -> Dynamic (Map k v) -> m (Dynamic (Int, Int), Event k)

129+-- Widget to efficiently display long scrolling lists.

130+[W] virtualListWithSelection :: ... -- See Reflex.Dom.Widget.Lazy

153131```

154132

155133## Connecting to the real world (I/O)

@@ -157,8 +135,7 @@ Some of these widget builders take a configuration record and return a record co

157135### Connecting to DOM events

158136

159137```haskell

160−-- Extract the specified Event from an 'El'. The allowable event names, and their

161−-- corresponding data types, are listed in Reflex/Dom/Widget/Basic.hs

138+-- Extract the specified Event from an 'El'. See Reflex.Dom.Widget.Basic

162139[ ] domEvent :: EventName en -> El -> Event (EventResultType en)

163140```

164141

@@ -179,7 +156,7 @@ Some of these widget builders take a configuration record and return a record co

179156

180157### XMLHttpRequest

181158

182−Convenience functions for XMLHttpRequest. For configuration field details, see Reflex/Dom/Xhr.hs.

159+Convenience functions for XMLHttpRequest. see Reflex.Dom.Xhr

183160

184161```haskell

185162-- Given method, URL, and config record (with default instance), construct a request.

@@ -191,7 +168,7 @@ Convenience functions for XMLHttpRequest. For configuration field details, see

191168-- Issue a collection of requests, wait for them ALL to complete, return collected results.

192169[W] performRequestsAsync :: Traversable f => Event (f XhrRequest) -> m (Event (f XhrResponse))

193170

194−-- Convenience function to decode JSON-encoded response.

171+-- Convenience function to decode JSON-encoded responses.

195172[ ] decodeXhrResponse :: FromJSON a => XhrResponse -> Maybe a

196173

197174-- Simplified interface to "GET" URLs and return decoded results.

@@ -201,12 +178,10 @@ Convenience functions for XMLHttpRequest. For configuration field details, see

201178### Time

202179

203180```haskell

204−-- Given a time interval in seconds and a basis time, create an Event that fires on the given

205−-- interval. The Event will report the number of time intervals elapsed since the basis time

206−-- (and other info, see Reflex/Dom/Time.hs). High load will cause ticks to be dropped.

181+-- Create Event at given interval with given basis time.

207182[W] tickLossy :: NominalDiffTime -> UTCTime -> m (Event t TickInfo)

208183

209−-- Delay an Event's occurences by a given amount in seconds.

184+-- Delay an Event's occurrences by a given amount in seconds.

210185[W] delay :: NominalDiffTime -> Event t a -> m (Event t a)

211186```

212187

src/Reflex/Dom/Time.hs+1

@@ -45,6 +45,7 @@ tickLossyFrom dt t0 e = performEventAsync $ fmap callAtNextInterval e

4545 threadDelay $ ceiling $ (dt - alreadyElapsed) * 1000000

4646 cb $ TickInfo t n alreadyElapsed

4747

48+-- | Delay an Event's occurrences by a given amount in seconds.

4849delay :: MonadWidget t m => NominalDiffTime -> Event t a -> m (Event t a)

4950delay dt e = performEventAsync $ ffor e $ \a cb -> liftIO $ void $ forkIO $ do

5051 threadDelay $ ceiling $ dt * 1000000

src/Reflex/Dom/Widget/Basic.hs+43−5

@@ -106,6 +106,9 @@ display :: (MonadWidget t m, Show a) => Dynamic t a -> m ()

106106display a = dynText =<< mapDyn show a

107107

108108--TODO: Should this be renamed to 'widgetView' for consistency with 'widgetHold'?

109+-- | Given a Dynamic of widget-creating actions, create a widget that is recreated whenever the Dynamic updates.

110+-- The returned Event of widget results occurs when the Dynamic does.

111+-- Note: Often, the type 'a' is an Event, in which case the return value is an Event-of-Events that would typically be flattened.

109112dyn :: MonadWidget t m => Dynamic t (m a) -> m (Event t a)

110113dyn child = do

111114 startPlaceholder <- text' ""

@@ -133,6 +136,9 @@ dyn child = do

133136 build newChild

134137 return $ fmap fst newChildBuilt

135138

139+-- | Given an initial widget and an Event of widget-creating actions, create a widget that is recreated whenever the Event fires.

140+-- The returned Dynamic of widget results occurs when the Event does.

141+-- Note: Often, the type 'a' is an Event, in which case the return value is a Dynamic-of-Events that would typically be flattened.

136142widgetHold :: MonadWidget t m => m a -> Event t (m a) -> m (Dynamic t a)

137143widgetHold child0 newChild = do

138144 startPlaceholder <- text' ""

@@ -162,7 +168,11 @@ widgetHold child0 newChild = do

162168 holdDyn result0 $ fmap fst newChildBuilt

163169

164170--TODO: Something better than Dynamic t (Map k v) - we want something where the Events carry diffs, not the whole value

165−listWithKey :: (Ord k, MonadWidget t m) => Dynamic t (Map k v) -> (k -> Dynamic t v -> m a) -> m (Dynamic t (Map k a))

171+-- | Create a dynamically-changing set of widgets from a Dynamic key/value map.

172+listWithKey :: (Ord k, MonadWidget t m)

173+ => Dynamic t (Map k v) -- ^ Dynamic key/value map

174+ -> (k -> Dynamic t v -> m a) -- ^ Function to create a widget for a given key from Dynamic value

175+ -> m (Dynamic t (Map k a)) -- ^ Dynamic map from keys to widget results

166176listWithKey vals mkChild = do

167177 doc <- askDocument

168178 endPlaceholder <- text' ""

@@ -211,7 +221,12 @@ listWithKey vals mkChild = do

211221 postBuild

212222 holdDyn Map.empty $ fmap (fmap (fst . fst)) newChildren

213223

214−listWithKey' :: forall t m k v a. (Ord k, MonadWidget t m) => Map k v -> Event t (Map k (Maybe v)) -> (k -> v -> Event t v -> m a) -> m (Dynamic t (Map k a))

224+-- | Create a dynamically-changing set of widgets from a key/value map with update Events.

225+listWithKey' :: forall t m k v a. (Ord k, MonadWidget t m)

226+ => Map k v -- ^ Initial key/value map

227+ -> Event t (Map k (Maybe v)) -- ^ Event of map updates

228+ -> (k -> v -> Event t v -> m a) -- ^ Function to create a widget for a given key from initial value and update Event

229+ -> m (Dynamic t (Map k a)) -- ^ Dynamic map from keys to widget results

215230listWithKey' initialVals valsChanged mkChild = do

216231 doc <- askDocument

217232 endPlaceholder <- text' ""

@@ -267,6 +282,8 @@ listWithKey' initialVals valsChanged mkChild = do

267282 mapDyn (fmap (fst . fst)) children

268283

269284--TODO: Something better than Dynamic t (Map k v) - we want something where the Events carry diffs, not the whole value

285+-- | Create a dynamically-changing set of Event-valued widgets.

286+-- This is like listWithKey, specialized for widgets returning (Event t a). listWithKey would return 'Dynamic t (Map k (Event t a))' in this scenario, but listViewWithKey flattens this to 'Event t (Map k a)' via 'switch'.

270287listViewWithKey :: (Ord k, MonadWidget t m) => Dynamic t (Map k v) -> (k -> Dynamic t v -> m (Event t a)) -> m (Event t (Map k a))

271288listViewWithKey vals mkChild = liftM (switch . fmap mergeMap) $ listViewWithKey' vals mkChild

272289

@@ -321,7 +338,12 @@ listViewWithKey' vals mkChild = do

321338

322339--TODO: Deduplicate the various list*WithKey* implementations

323340

324−selectViewListWithKey_ :: forall t m k v a. (MonadWidget t m, Ord k) => Dynamic t k -> Dynamic t (Map k v) -> (k -> Dynamic t v -> Dynamic t Bool -> m (Event t a)) -> m (Event t k)

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

342+selectViewListWithKey_ :: forall t m k v a. (MonadWidget t m, Ord k)

343+ => Dynamic t k -- ^ Current selection key

344+ -> Dynamic t (Map k v) -- ^ Dynamic key/value map

345+ -> (k -> Dynamic t v -> Dynamic t Bool -> m (Event t a)) -- ^ Function to create a widget for a given key from Dynamic value and Dynamic Bool indicating if this widget is currently selected

346+ -> m (Event t k) -- ^ Event that fires when any child's return Event fires. Contains key of an arbitrary firing widget.

325347selectViewListWithKey_ selection vals mkChild = do

326348 let selectionDemux = demux selection -- For good performance, this value must be shared across all children

327349 selectChild <- listWithKey vals $ \k v -> do

@@ -676,9 +698,12 @@ elClass elementTag c child = elAttr elementTag ("class" =: c) child

676698-- Copied and pasted from Reflex.Widget.Class

677699--------------------------------------------------------------------------------

678700

701+-- | Create a dynamically-changing set of widgets from a Dynamic key/value map.

702+-- Unlike the 'withKey' variants, the child widgets are insensitive to which key they're associated with.

679703list :: (MonadWidget t m, Ord k) => Dynamic t (Map k v) -> (Dynamic t v -> m a) -> m (Dynamic t (Map k a))

680704list dm mkChild = listWithKey dm (\_ dv -> mkChild dv)

681705

706+-- | Create a dynamically-changing set of widgets from a Dynamic list.

682707simpleList :: MonadWidget t m => Dynamic t [v] -> (Dynamic t v -> m a) -> m (Dynamic t [a])

683708simpleList xs mkChild = mapDyn (map snd . Map.toList) =<< flip list mkChild =<< mapDyn (Map.fromList . zip [(1::Int)..]) xs

684709

@@ -759,7 +784,13 @@ dtdd h w = do

759784blank :: forall t m. MonadWidget t m => m ()

760785blank = return ()

761786

762−tableDynAttr :: forall t m r k v. (MonadWidget t m, Show k, Ord k) => String -> [(String, k -> Dynamic t r -> m v)] -> Dynamic t (Map k r) -> (k -> m (Dynamic t (Map String String))) -> m (Dynamic t (Map k (El t, [v])))

787+-- | A widget to display a table with static columns and dynamic rows.

788+tableDynAttr :: forall t m r k v. (MonadWidget t m, Show k, Ord k)

789+ => String -- ^ Class applied to <table> element

790+ -> [(String, k -> Dynamic t r -> m v)] -- ^ Columns of (header, row key -> row value -> child widget)

791+ -> Dynamic t (Map k r) -- ^ Map from row key to row value

792+ -> (k -> m (Dynamic t (Map String String))) -- ^ Function to compute <tr> element attributes from row key

793+ -> m (Dynamic t (Map k (El t, [v]))) -- ^ Map from row key to (El, list of widget return values)

763794tableDynAttr klass cols dRows rowAttrs = elAttr "div" (Map.singleton "style" "zoom: 1; overflow: auto; background: white;") $ do

764795 elAttr "table" (Map.singleton "class" klass) $ do

765796 el "thead" $ el "tr" $ do

@@ -770,7 +801,14 @@ tableDynAttr klass cols dRows rowAttrs = elAttr "div" (Map.singleton "style" "zo

770801 elDynAttr' "tr" dAttrs $ mapM (\x -> el "td" $ snd x k r) cols)

771802

772803--TODO preselect a tab on open

773−tabDisplay :: forall t m k. (MonadFix m, MonadWidget t m, Show k, Ord k) => String -> String -> Map k (String, m ()) -> m ()

804+-- | A widget to construct a tabbed view that shows only one of its child widgets at a time.

805+-- Creates a header bar containing a <ul> with one <li> per child; clicking a <li> displays

806+-- the corresponding child and hides all others.

807+tabDisplay :: forall t m k. (MonadFix m, MonadWidget t m, Show k, Ord k)

808+ => String -- ^ Class applied to <ul> element

809+ -> String -- ^ Class applied to currently active <li> element

810+ -> Map k (String, m ()) -- ^ Map from (arbitrary) key to (tab label, child widget)

811+ -> m ()

774812tabDisplay ulClass activeClass tabItems = do

775813 rec dCurrentTab <- holdDyn Nothing (updated dTabClicks)

776814 dTabClicks :: Dynamic t (Maybe k) <- elAttr "ul" (Map.singleton "class" ulClass) $ do

src/Reflex/Dom/Xhr.hs+5

@@ -62,6 +62,7 @@ instance Default XhrRequestConfig where

6262 , _xhrRequestConfig_sendData = Nothing

6363 }

6464

65+-- | Construct a request object from method, URL, and config record.

6566xhrRequest :: String -> String -> XhrRequestConfig -> XhrRequest

6667xhrRequest = XhrRequest

6768

@@ -92,11 +93,13 @@ newXMLHttpRequest req cb = do

9293 _ <- xmlHttpRequestSend xhr (_xhrRequestConfig_sendData c)

9394 return xhr

9495

96+-- | Given Event of requests, issue them when the Event fires. Returns Event of corresponding responses.

9597performRequestAsync :: (MonadWidget t m) => Event t XhrRequest -> m (Event t XhrResponse)

9698performRequestAsync req = performEventAsync $ ffor req $ \r cb -> do

9799 _ <- newXMLHttpRequest r $ liftIO . cb

98100 return ()

99101

102+-- | Issues a collection of requests when the supplied Event fires. When ALL requests from a given firing complete, the results are collected and returned via the return Event.

100103performRequestsAsync :: (Traversable f, MonadWidget t m) => Event t (f XhrRequest) -> m (Event t (f XhrResponse))

101104performRequestsAsync req = performEventAsync $ ffor req $ \rs cb -> do

102105 resps <- forM rs $ \r -> do

@@ -106,6 +109,7 @@ performRequestsAsync req = performEventAsync $ ffor req $ \rs cb -> do

106109 _ <- liftIO $ forkIO $ cb =<< forM resps takeMVar

107110 return ()

108111

112+-- | Simplified interface to "GET" URLs and return decoded results.

109113getAndDecode :: (FromJSON a, MonadWidget t m) => Event t String -> m (Event t (Maybe a))

110114getAndDecode url = do

111115 r <- performRequestAsync $ fmap (\x -> XhrRequest "GET" x def) url

@@ -119,6 +123,7 @@ getMay f e = do

119123decodeText :: FromJSON a => Text -> Maybe a

120124decodeText = decode . BL.fromStrict . encodeUtf8

121125

126+-- | Convenience function to decode JSON-encoded responses.

122127decodeXhrResponse :: FromJSON a => XhrResponse -> Maybe a

123128decodeXhrResponse = join . fmap decodeText . _xhrResponse_body

124129