A store contains application state, receives actions from the dispatcher, and notifies controller-views to re-render themselves. You can have multiple stores; it should be the case that all of the state required to render the page is contained in the stores. A store keeps a global reference to a value of type storeData, which must be an instance of StoreData.

Stores also work when compiled with GHC instead of GHCJS. When compiled with GHC, the store is just an MVar containing the store data and there are no controller views. alterStore can still be used, but it just transforms the store and does not notify any controller-views since there are none. Compiling with GHC instead of GHCJS can be helpful for unit testing, although GHCJS plus node can also be used for unit testing.

data Todo = Todo {
    todoText :: Text
  , todoComplete :: Bool
  , todoIsEditing :: Bool
} deriving (Show, Typeable)

newtype TodoState = TodoState {
    todoList :: [(Int, Todo)]
} deriving (Show, Typeable)

data TodoAction = TodoCreate Text
                | TodoDelete Int
                | TodoEdit Int
                | UpdateText Int Text
                | ToggleAllComplete
                | TodoSetComplete Int Bool
                | ClearCompletedTodos
  deriving (Show, Typeable, Generic, NFData)

instance StoreData TodoState where
    type StoreAction TodoState = TodoAction
    transform action (TodoState todos) = ...

todoStore :: ReactStore TodoState
todoStore = mkStore $ TodoState
    [ (0, Todo "Learn react" True False)
    , (1, Todo "Learn react-flux" False False)
    ]

The data in a store must be an instance of this typeclass.

Create a new store from the initial data.

Obtain the store data from a store. Note that the store data is stored in an MVar, so getStoreData can block since it uses readMVar. The MVar is empty exactly when the store is being transformed, so there is a possiblity of deadlock if two stores try and access each other's data during transformation.

First, transform the store data according to the given action. Next, if compiled with GHCJS, notify all registered controller-views to re-render themselves. (If compiled with GHC, the store data is just transformed since there are no controller-views.)

Only a single thread can be transforming the store at any one time, so this function will block on an MVar waiting for a previous transform to complete if one is in process.

An existential type for some store action. It is used as the output of the dispatcher. The NFData instance is important for performance, for details see below.

Call alterStore on the store and action.

A view is conceptually a rendering function from props and some internal state to a tree of elements. The function receives a value of type props from its parent in the virtual DOM. Additionally, the rendering function can depend on some internal state or store data. Based on the props and the internal state, the rendering function produces a virtual tree of elements which React then reconciles with the browser DOM.

This module supports 3 kinds of views. All of the views provided by this module are pure, in the sense that the rendering function and event handlers cannot perform any IO. All IO occurs inside the transform function of a store.

A controller view provides the glue between a ReactStore and the DOM. The controller-view registers with the given store, and whenever the store is transformed the controller-view re-renders itself. Each instance of a controller-view also accepts properties of type props from its parent. Whenever the parent re-renders itself, the new properties will be passed down to the controller-view causing it to re-render itself.

Events registered on controller-views are expected to produce lists of SomeStoreAction. Since lists of SomeStoreAction are the output of the dispatcher, each event handler should just be a call to a dispatcher function. Once the event fires, the actions are executed causing the store(s) to transform which leads to the controller-view(s) re-rendering. This one-way flow of data from actions to store to controller-views is central to the flux design.

It is recommended to have one controller-view for each significant section of the page. Controller-views deeper in the page tree can cause complexity because data is now flowing into the page in multiple possibly conflicting places. You must balance the gain of encapsulated components versus the complexity of multiple entry points for data into the page. Note that multiple controller views can register with the same store.

todoApp :: ReactView ()
todoApp = defineControllerView "todo app" todoStore $ \todoState () ->
    div_ $ do
        todoHeader_
        mainSection_ todoState
        todoFooter_ todoState

A view is a re-usable component of the page which accepts properties of type props from its parent and re-renders itself whenever the properties change.

One option to implement views is to just use a Haskell function taking the props as input and producing a ReactElementM. For small views, such a Haskell function is ideal. Using a ReactView provides more than just a Haskell function when used with a key property with viewWithSKey and viewWithIKey. The key property allows React to more easily reconcile the virtual DOM with the browser DOM.

The following is two example views: mainSection_ is just a Haskell function and todoItem is a React view. We use the convention that an underscore suffix signifies a combinator which can be used in the rendering function.

mainSection_ :: TodoState -> ReactElementM ViewEventHandler ()
mainSection_ st = section_ ["id" $= "main"] $ do
    input_ [ "id" $= "toggle-all"
           , "type" $= "checkbox"
           , "checked" $= if all (todoComplete . snd) $ todoList st then "checked" else ""
           , onChange $ \_ -> dispatchTodo ToggleAllComplete
           ]

    label_ [ "htmlFor" $= "toggle-all"] "Mark all as complete"
    ul_ [ "id" $= "todo-list" ] $ mapM_ todoItem_ $ todoList st

todoItem :: ReactView (Int, Todo)
todoItem = defineView "todo item" $ \(todoIdx, todo) ->
    li_ [ classNames [("completed", todoComplete todo), ("editing", todoIsEditing todo)]
        , "key" @= todoIdx
        ] $ do
        
        div_ [ "className" $= "view"] $ do
            input_ [ "className" $= "toggle"
                   , "type" $= "checkbox"
                   , "checked" @= todoComplete todo
                   , onChange $ \_ -> dispatchTodo $ TodoSetComplete todoIdx $ not $ todoComplete todo
                   ]

            label_ [ onDoubleClick $ \_ _ -> dispatchTodo $ TodoEdit todoIdx] $
                elemText $ todoText todo

            button_ [ "className" $= "destroy"
                    , onClick $ \_ _ -> dispatchTodo $ TodoDelete todoIdx
                    ] mempty

        when (todoIsEditing todo) $
            todoTextInput_ TextInputArgs
                { tiaId = Nothing
                , tiaClass = "edit"
                , tiaPlaceholder = ""
                , tiaOnSave = dispatchTodo . UpdateText todoIdx
                , tiaValue = Just $ todoText todo
                }

todoItem_ :: (Int, Todo) -> ReactElementM eventHandler ()
todoItem_ !todo = viewWithIKey todoItem (fst todo) todo mempty

A stateful view is a re-usable component of the page which keeps track of internal state. Try to keep as many views as possible stateless. The React documentation on interactivity and dynamic UIs has some discussion of what should and should not go into the state.

The rendering function is a pure function of the state and the properties from the parent. The view will be re-rendered whenever the state or properties change. The only way to transform the internal state of the view is via an event handler, which can optionally produce new state. Any more complicated state should be moved out into a (possibly new) store.

data TextInputArgs = TextInputArgs {
      tiaId :: Maybe JSString
    , tiaClass :: JSString
    , tiaPlaceholder :: JSString
    , tiaOnSave :: Text -> [SomeStoreAction]
    , tiaValue :: Maybe Text
} deriving (Typeable)

todoTextInput :: ReactView TextInputArgs
todoTextInput = defineStatefulView "todo text input" "" $ \curText args ->
    input_ $
        maybe [] (\i -> ["id" &= i]) (tiaId args)
        ++
        [ "className" &= tiaClass args
        , "placeholder" &= tiaPlaceholder args
        , "value" &= curText
        , "autoFocus" &= True
        , onChange $ \evt _ -> ([], Just $ target evt "value")
        , onBlur $ \_ _ curState ->
             if not (Text.null curState)
                 then (tiaOnSave args curState, Just "")
                 else ([], Nothing)
        , onKeyDown $ \_ evt curState ->
             if keyCode evt == 13 && not (Text.null curState) -- 13 is enter
                 then (tiaOnSave args curState, Just "")
                 else ([], Nothing)
        ]

todoTextInput_ :: TextInputArgs -> ReactElementM eventHandler ()
todoTextInput_ !args = view todoTextInput args mempty

Event handlers in a controller-view and a view transform events into actions, but are not allowed to perform any IO.

A stateful-view event handler produces a list of store actions and potentially a new state. If the new state is nothing, no change is made to the state (which allows an optimization in that we do not need to re-render the view).

Changing the state causes a re-render which will cause a new event handler to be created. If the handler closes over the state passed into the rendering function, there is a race if multiple events occur before React causes a re-render. Therefore, the handler takes the current state as input. Your handlers therefore should ignore the state passed into the render function and instead use the state passed directly to the handler.

A React element is a node or list of nodes in a virtual tree. Elements are the output of the rendering functions of classes. React takes the output of the rendering function (which is a tree of elements) and then reconciles it with the actual DOM elements in the browser. The ReactElement is a monoid, so dispite its name can represent more than one element. Multiple elements are rendered into the browser DOM as siblings.

A writer monad for ReactElements which is used in the rendering function of all views.

do notation or the Monoid instance is used to sequence sibling elements. Child elements are specified via function application; the combinator creating an element takes the child element as a parameter. The OverloadedStrings extension is used to create plain text.

ul_ $ do li_ (b_ "Hello")
         li_ "World"
         li_ $
             ul_ (li_ "Nested" <> li_ "List")

would build something like

<ul>
  <li><b>Hello</b><li>
  <li>World</li>
  <li><ul>
    <li>Nested</li>
    <li>List</li>
  </ul></li>
</ul>

The React.Flux.DOM module contains a large number of combinators for creating HTML elements.

Create a text element from a string. The text content is escaped to be HTML safe. If you need to insert HTML, instead use the dangerouslySetInnerHTML property. This is an alias for fromString.

Create a text element from a text value. The text content is escaped to be HTML safe.

Create a text element from a JSString. This is more efficient for hard-coded strings than converting from text to a JavaScript string. The string is escaped to be HTML safe.

Create an element containing text which is the result of showing the argument. Note that the resulting string is then escaped to be HTML safe.

Create an element from a view. I suggest you make a combinator for each of your views, similar to the examples above such as todoItem_.

Create an element from a view, and also pass in a string key property for the instance. Key properties speed up the reconciliation of the virtual DOM with the DOM. The key does not need to be globally unqiue, it only needs to be unique within the siblings of an element.

Similar to viewWithSKey, but with an integer key instead of a string key.

Transclude the children passed into view or viewWithKey into the current rendering. Use this where you would use this.props.children in a javascript React class.

Create a ReactElement for a class defined in javascript. See foreign_ for a convenient wrapper and some examples.

Render your React application into the DOM. Use this from your main function, and only in the browser.

Render your React application to a string using either ReactDOMServer.renderToString if the first argument is false or ReactDOMServer.renderToStaticMarkup if the first argument is true. Use this only on the server when running with node.

Export a Haskell view to a JavaScript function. This allows you to embed a Haskell react-flux application into a larger existing JavaScript React application. If you want to use JavaScript classes in your Haskell application, you should instead use foreign_ and foreignClass.

The way this works is as follows:

1. You create a Haskell function which translates the javascript arguments of into a Haskell value of type ReturnProps props. This is a variable-argument function using the ArgumentsToProps class. For example,

    data MyProps = MyProps { theInt :: Int, theString :: String }
    myArgsToProps :: Int -> String -> ReturnProps MyProps
    myArgsToProps i s = ReturnProps $ MyProps i s
    

2. You create a view which receives these properties and renders itself. This view will not receive any children.

    myView :: ReactView MyProps
    myView = defineView "my view" $ \myProps -> ...
    

3. You can then use exportViewToJavaScript to create a JavaScript function. When this JavaScript function is executed, the JavaScript arguments are converted to the props, the view is rendered using the props, and the resulting React element is returned from the JavaScript function.

    foreign import javascript unsafe
        "window['myHaskellView'] = $1;"
        js_setMyView :: JSVal -> IO ()
   
    exportMyView :: IO ()
    exportMyView = exportViewToJavaScript myView myArgsToProps >>= js_setMyView
    

   exportMyView should be called from your main function. After executing exportMyView, the window.myHaskellView property will be a javascript function.

4. Call the javascript function with two arguments to return a React element which can be used in a JavaScript React class rendering function.

      var myJsView = React.createClass({
          render: function() {
              return <div>{window.myHaskellView(5, "Hello World")}</div>;
          }
      };
      

A class which is used to implement variable argument functions. These variable argument functions are used to convert from a JavaScript arguments array to a Haskell value of type props.

Any function where each argument implements FromJSVal and the result is ReturnProps is an instance of this class. Entries from the JavaScript arguments array are matched one-by-one to the arguments before ReturnProps value. If the Haskell function has more parameters than the javascript arguments object, a javascript null is used for the conversion. Since the Maybe instance of FromJSVal converts null references to Nothing, you can exploit this to handle arguments not given to the JavaScript function.

A type needed to make GHC happy when solving for instances of ArgumentsToProps.

A deprecated way to create a view with a key which has problems when OverloadedStrings is active. Use viewWithSKey or viewWithIKey instead.

Keys in React can either be strings or integers