@@ -25,6 +25,22 @@
2525{-# LANGUAGE ForeignFunctionInterface #-}
2626{-# LANGUAGE JavaScriptFFI #-}
2727#endif
28+-- | This is a builder to be used on the client side. It can be run in two modes:
29+--
30+-- 1. in "hydration mode", reusing DOM nodes already in the page (as produced
31+-- by 'Reflex.Dom.Builder.Static.renderStatic')
32+-- 2. in "immediate mode", creating and appending DOM nodes as required
33+--
34+-- In "hydration mode", the preexisting DOM __must contain__ what the builder
35+-- will expect at switchover time (the time at which parity with the static
36+-- renderer is reached, and the time after which the page is "live").
37+-- There can be extra nodes, but no missing or incorrect nodes.
38+--
39+-- For example, displaying the current time as text should be done inside
40+-- 'Reflex.Dom.Prerender.prerender' to ensure that we don't attempt to hydrate the incorrect text.
41+-- The server will prerender a text node with time A, and the client will expect
42+-- a text node with time B. Barring a miracle, time A and time B will not match,
43+-- and hydration will fail.
2844module Reflex.Dom.Builder.Hydration
2945 ( EventTriggerRef (..)
3046 , HydrationDomBuilderEnv (..)
@@ -151,8 +167,8 @@ data HydrationDomBuilderEnv t = HydrationDomBuilderEnv
151167 , _hydrationDomBuilderEnv_switchover :: !(Event t ())
152168 }
153169
154−-- | The monad which performs the delayed actions to reuse prerendered nodes and set up events
155−-- State contains reference to the previous node sibling, if any.
170+-- | The monad which performs the delayed actions to reuse prerendered nodes and set up events.
171+-- State contains reference to the previous node sibling, if any, and the reader contains reference to the parent node.
156172newtype HydrationRunnerT t m a = HydrationRunnerT { unHydrationRunnerT :: StateT (Maybe Node) (ReaderT Node (DomRenderHookT t m)) a }
157173 deriving (Functor, Applicative, Monad, MonadFix, MonadIO, MonadException
158174#if MIN_VERSION_base(4,9,1)