Copyright(c) digitally induced GmbH 2020
Safe HaskellNone

IHP.Controller.Context

Description

 
Synopsis

Documentation

data ControllerContext Source #

A container storing useful data along the request lifecycle, such as the request, the current user, set current view layout, flash messages, ...

The controller context is usually accessed via the ?context variable. It's availble inside the action and the view. Think of it as a key-value-map where the key is the type of the value.

You can store information inside the context using putContext:

>>> newtype CurrentLayout = CurrentLayout Html
>>> 
>>> ?context <- newControllerContext
>>> putContext (CurrentLayout layout)

Inside an action you can access the values using fromContext:

>>> (CurrentLayout layout) <- fromContext

You can freeze the context and then access values without being inside an IO context (like inside views which are pure):

Call freeze inside an IO part:

>>> ?context <- freeze ?context

(freeze is automatically called by IHP before rendering a view, so usually you don't need to call it manually)

Then use the frozen context from your pure code like this:

>>> let (CurrentLayout layout) = fromFrozenContext in ...

The context is initially created before a action is going to be executed. It's life cycle looks like this:

  • newControllerContext: The new controller context is created
  • The runActionWithNewContext fills in a few default values: The current ?application and also the Flash Messages to be rendered in the to-be-generated response.
  • initContext: The initContext function of the InitControllerContext WebApplication (inside your FrontController.hs) is called. There application-specific context can be provided. Usually this is the current user and the default layout.
  • beforeAction: Here the context could also be modified. E.g. the layout could be overriden here for the whole controller.
  • action ..: The action itself.
  • Freezing: Before rendering the response, the container is frozen. Frozen means that all previously mutable fields become immutable.
  • View Rendering: The frozen container is now used inside the view and layout to display information such as the current user or flash messages

freeze :: ControllerContext -> IO ControllerContext Source #

After freezing a container you can access it's values from pure non-IO code by using fromFronzenContext

Calls to putContext will throw an exception after it's frozen.

fromContext :: forall value. (?context :: ControllerContext, Typeable value) => IO value Source #

Returns a value from the current controller context

Throws an exception if the there is no value with the type inside the context

Example: Read the current user from the context

>>> user <- fromContext @User

fromFrozenContext :: forall value. (?context :: ControllerContext, Typeable value) => value Source #

Returns a value from the current controller context. Requires the context to be frozen.

Example: Read the current user from the context

>>> let user = fromFrozenContext @User

maybeFromContext :: forall value. (?context :: ControllerContext, Typeable value) => IO (Maybe value) Source #

maybeFromFrozenContext :: forall value. (?context :: ControllerContext, Typeable value) => Maybe value Source #

putContext :: forall value. (?context :: ControllerContext, Typeable value) => value -> IO () Source #

Puts a value into the context

Throws an exception if the context is already frozen.

newtype ActionType Source #

Constructors

ActionType TypeRep