@@ -25,6 +25,22 @@
25{-# LANGUAGE ForeignFunctionInterface #-}
25{-# LANGUAGE ForeignFunctionInterface #-}
26{-# LANGUAGE JavaScriptFFI #-}
26{-# LANGUAGE JavaScriptFFI #-}
28+-- | This is a builder to be used on the client side. It can be run in two modes:
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
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.
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.
28module Reflex.Dom.Builder.Hydration
44module Reflex.Dom.Builder.Hydration
29 ( EventTriggerRef (..)
45 ( EventTriggerRef (..)
30 , HydrationDomBuilderEnv (..)
46 , HydrationDomBuilderEnv (..)
@@ -151,8 +167,8 @@ data HydrationDomBuilderEnv t = HydrationDomBuilderEnv
151 , _hydrationDomBuilderEnv_switchover :: !(Event t ())
167 , _hydrationDomBuilderEnv_switchover :: !(Event t ())
154−-- | The monad which performs the delayed actions to reuse prerendered nodes and set up events
170+-- | 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.
171+-- State contains reference to the previous node sibling, if any, and the reader contains reference to the parent node.
156newtype HydrationRunnerT t m a = HydrationRunnerT { unHydrationRunnerT :: StateT (Maybe Node) (ReaderT Node (DomRenderHookT t m)) a }
172newtype HydrationRunnerT t m a = HydrationRunnerT { unHydrationRunnerT :: StateT (Maybe Node) (ReaderT Node (DomRenderHookT t m)) a }
157 deriving (Functor, Applicative, Monad, MonadFix, MonadIO, MonadException
173 deriving (Functor, Applicative, Monad, MonadFix, MonadIO, MonadException
158#if MIN_VERSION_base(4,9,1)
174#if MIN_VERSION_base(4,9,1)