A handle to a running Page. Create this using runPage, and wait for its eventual result using waitPage. In between, you can interact with it using the rest of the functions in this module, such as modifyPage, stopPage, etc.

Run an interactive page, returning a handle Page through which it can be interacted further, via the functions in this module (e.g. waitPage, modifyPage, etc.).

This function takes as input a PageLocation, an initial model, and a pure function from the current state of the page's model to a rendered HTML view of the page in its entirety, and the new set of Handlers for page events. A handler can modify the model of the page, and perform arbitrary IO actions, including evaluating JavaScript in the page using eval. After each all pertinent handlers for an event are dispatched, the page is re-rendered to the browser.

This function itself is non-blocking: it immediately kicks off threads to start running the page. It will not throw exceptions by itself. All exceptions thrown by page threads (such as issues with connecting to the server) are deferred until a call to waitPage.

Important: Because the GHC runtime does not wait for all threads to finish when ending the main thread, you probably need to use waitPage to make sure your program stays alive to keep processing events.

Typical use of this function embeds a Reactive page by using the reactive function to adapt it as the last argument (but this is not the only way to use it, see Using Page without Reactive):

runPage location (pure initialModel) (reactive component)

Wait for a Page to finish executing and return its resultant model, or re-throw any exception the page encountered.

This function may throw HttpException if it cannot connect to a running instance of the server. Additionally, it will also re-throw any exception that was raised by user code running within an event handler or model-modifying action.

Politely request a Page to shut down. This is non-blocking: to get the final model of the Page, follow stopPage with a call to waitPage.

Before the page is stopped, all events and modifications which were pending at the time of this command will be processed.

The options for connecting to the Myxine server. This is an opaque Monoid: set options by combining pagePort and/or pagePath using their Semigroup instance.

Set the path to something other than the default of /.

Set the port to a non-default port. This is only necessary when Myxine is running on a non-default port also.

The Reactive type interleaves the description of page markup with the specification of event handlers for the page.

It is a Monoid and its underlying type ReactiveM is a Monad, which means that just like the Blaze templating library, it can be (and is designed to be!) used in do-notation. Importantly, it is also a MonadReader model, where the current model is returned by ask.

The underlying builder monad for the Reactive type.

This is almost always used with a return type of (), hence you will usually see it aliased as Reactive model.

Evaluate a reactive component to produce a pair of PageContent and Handlers. This is the bridge between the runPage abstraction and the Reactive abstraction: use this to run a reactive component in a Page.

Set the title for the page. If this function is called multiple times in one update, the most recent call is used.

Write an atomic piece of HTML (or anything that can be converted to it) to the page in this location. Event listeners for its enclosing scope can be added by sequential use of on. If you need sub-pieces of this HTML to have their own scoped event listeners, use @@ to build a composite component.

>>> markup h === const (toMarkup h) @@ pure ()

Listen to a particular event and react to it by modifying the model for the page. This function's returned Propagation value specifies whether or not to propagate the event outwards to other enclosing contexts. The event target is scoped to the enclosing @@, or the whole page if at the top level.

When the specified EventType occurs, the event handler will be called with that event type's corresponding property record, e.g. a Click event's handler will receive a MouseEvent record. A handler can modify the page's model via Stateful actions and perform arbitrary IO using liftIO. In the context of a running page, a handler also has access to the eval and evalBlock functions to evaluate JavaScript in that page.

Exception behavior: This function catches PatternMatchFail exceptions thrown by the passed function. That is, if there is a partial pattern match in the pure function from event properties to stateful update, the stateful update will be silently skipped. This is useful as a shorthand to select only events of a certain sort, for instance:

on' Click \MouseEvent{shiftKey = True} ->
  do putStrLn "Shift + Click!"
     pure Bubble

Listen to a particular event and react to it by modifying the model for the page. This is a special case of on' where the event is always allowed to bubble out to listeners in enclosing contexts.

See the documentation for on'.

Indicator for whether an event should continue to be triggered on parent elements in the path. An event handler can signal that it wishes the event to stop propagating by returning Stop.

Wrap an inner reactive component in some enclosing HTML. Any listeners created via on in the wrapped component will be scoped to only events that occur within this chunk of HTML.

In the following example, we install a Click handler for the whole page, then build a div with another Click handler inside that page, which returns Stop from on' to stop the Click event from bubbling out to the outer handler when the inner div is clicked.

do on Click $ \_ ->
     liftIO $ putStrLn "Clicked outside!"
   div ! style "background: lightblue;" @@ do
     "Click here, or elsewhere..."
     on' Click $ \_ -> do
       liftIO $ putStrLn "Clicked inside!"
       pure Stop

Focus a reactive page fragment to manipulate a piece of a larger model, using a Traversal' to specify what part(s) of the larger model to manipulate.

This is especially useful when creating generic components which can be re-used in the context of many different models. For instance, we can define a toggle button and specify separately which part of a model it toggles:

toggle :: Reactive Bool
toggle =
  button @@ do
    active <- ask
    if active then "ON" else "OFF"
    on Click \_ -> modify not

twoToggles :: Reactive (Bool, Bool)
twoToggles = do
  _1 ## toggle
  _2 ## toggle

This function takes a Traversal', which is strictly more general than a Lens'. This means you can use traversals with zero or more than one target, and this many replicas of the given Reactive fragment will be generated, each separately controlling its corresponding portion of the model. This means the above example could also be phrased:

twoToggles :: Reactive (Bool, Bool)
twoToggles = each ## toggle

Create a scope for event listeners without wrapping any enclosing HTML. Any listeners created via on will apply only to HTML that is written inside this block, rather than to the enclosing broader scope.

>>> target === (id @@)

Return a piece of JavaScript code which looks up the object corresponding to the current scope's location in the page. This is suitable to be used in eval, for instance, to retrieve properties of a particular element.

If there is no enclosing @@, then this is the window object; otherwise, it is the outermost HTML element object created by the first argument to the enclosing @@. If there are multiple elements at the root of the enclosing @@, then the first of these is selected.

For example, here's an input which reports its own contents:

textbox :: Reactive Text
textbox = input @@ do
  e <- this
  on Input _ -> do
    value eval $ this < ".value"
    put value

The WithinPage constraint, when it is present, enables the use of the eval and evalBlock functions. Only in the body of a call to runPage or modifyPageIO is there a canonical current page, and it's a type error to use these functions anywhere else.

Evaluate a JavaScript expression in the context of the current page. The given text is automatically wrapped in a return statement before being evaluated in the browser.

If you try to call eval outside of a call to runPage or modifyPageIO, you'll get a type error like the following:

• No instance for WithinPage arising from a use of ‘eval’
• In a stmt of a 'do' block: x <- eval @Int "1 + 1"

This means that you called it in some non-Page context, like in the main function of your program.

Evaluate a JavaScript block in the context of the current page. Unlike eval, the given text is not automatically wrapped in a return statement, which means that you can evaluate multi-line statements, but you must provide your own return.

If you try to call evalBlock outside of a call to runPage or modifyPageIO, you'll get a type error like the following:

• No instance for WithinPage arising from a use of ‘evalBlock’
• In a stmt of a 'do' block: x <- evalBlock @Int "return 1;"

This means that you called it in some non-Page context, like in the main function of your program.

Modify the model of the page with a pure function, and update the view in the browser to reflect the new model.

This function is non-blocking; the page view may not yet have been updated by the time it returns.

Modify the model of the page, potentially doing arbitrary other effects in the IO monad, then re-draw the page to the browser. The functions eval and evalBlock are available for evaluating JavaScript within the context of the current page.

This function is non-blocking; the page view may not yet have been updated by the time it returns.

Set the model of the page to a particular value, and update the view in the browser to reflect the new model.

This function is non-blocking; the page view may not yet have been updated by the time it returns.

Get the current model of the page, blocking until it is retrieved.

Note: it is not guaranteed that the model returned by this function is "fresh" by the time you act upon it. That is:

getPage page >>= setPage page

is not the same as

modifyPage id

This is because some other thread (notably, an event handler thread) could have changed the page in between the call to getPage and setPage. As a result, you probably don't want to use this function, except perhaps as a way to extract intermediate reports on the value of the page.