Graphics.UI.Threepenny.Core

Synopsis

Core functionality of the Threepenny GUI library.

Server

To display the user interface, you have to start a server using startGUI. Then, visit the URL http://localhost:8023/ in your browser (assuming that you use the default server configuration defaultConfig, or have set the port number to jsPort=8023.)

The server is multithreaded. FFI calls can be made concurrently, but events are handled sequentially.

data Config

Configuration of a Foreign.JavaScript server.

Constructors

Config

Fields

jsPort :: Maybe Int

Port number. Nothing means that the port number is read from the environment variable PORT. Alternatively, port 8023 is used if this variable is not set.

jsAddr :: Maybe ByteString

Bind address. Nothing means that the bind address is read from the environment variable ADDR. Alternatively, address 127.0.0.1 is used if this variable is not set.

jsCustomHTML :: Maybe FilePath

Custom HTML file to replace the default one.

jsStatic :: Maybe FilePath

Directory that is served under /static.

jsLog :: ByteString -> IO ()

Print a single log message.

defaultConfig :: Config

Default configuration.

Port from environment variable or 8023, listening on localhost, no custom HTML, no static directory, logging to stderr.

startGUI

Arguments

:: Config

Server configuration.

-> (Window -> UI ())

Action to run whenever a client browser connects.

-> IO ()

Start server for GUI sessions.

UI monad

data UI a

User interface elements are created and manipulated in the UI monad.

This monad is essentially just a thin wrapper around the familiar IO monad. Use the liftIO function to access IO operations like reading and writing from files.

There are several subtle reasons why Threepenny uses a custom UI monad instead of the standard IO monad:

• More convenience when calling JavaScript. The monad keeps track of a browser Window context in which JavaScript function calls are executed.
• Recursion for functional reactive programming.

Instances

Monad UI

Functor UI

MonadFix UI

Applicative UI

MonadIO UI

Typeable (* -> *) UI

runUI :: Window -> UI a -> IO a

Execute an UI action in a particular browser window. Also runs all scheduled IO actions.

askWindow :: UI Window

Retrieve current Window context in the UI monad.

liftIOLater :: IO () -> UI ()

Schedule an IO action to be run later.

module Control.Monad.IO.Class

module Control.Monad.Fix

Browser Window

data Window

The type Window represents a browser window.

title :: WriteAttr Window String

Title of the client window.

DOM elements

Create and manipulate DOM elements.

data Element

Instances

ToJS Element

Widget Element

Typeable * Element

getWindow :: Element -> IO Window

mkElement :: String -> UI Element

Make a new DOM element with a given tag name.

mkElementNamespace :: Maybe String -> String -> UI Element

Make a new DOM element with a namespace and a given tag name.

A namespace Nothing corresponds to the default HTML namespace.

delete :: Element -> UI ()

Delete the given element.

string :: String -> UI Element

Make a span element with a given text content.

getHead :: Window -> UI Element

Get the head of the page.

getBody :: Window -> UI Element

Get the body of the page.

(#+) :: UI Element -> [UI Element] -> UI Element infixl 8

Append DOM elements as children to a given element.

children :: WriteAttr Element [Element]

Child elements of a given element.

text :: WriteAttr Element String

Text content of an element.

html :: WriteAttr Element String

Child elements of a given element as a HTML string.

attr :: String -> WriteAttr Element String

HTML attributes of an element.

style :: WriteAttr Element [(String, String)]

Set CSS style of an Element

value :: Attr Element String

Value attribute of an element. Particularly relevant for control widgets like input.

getElementsByTagName

Arguments

:: Window

Browser window

-> String

The tag name.

-> UI [Element]

All elements with that tag name.

Get all elements of the given tag name.

getElementById

Arguments

:: Window

Browser window

-> String

The ID string.

-> UI (Maybe Element)

Element (if any) with given ID.

Get an element by a particular ID.

FIXME: Misleading type, throws a JavaScript exception when element not found.

getElementsByClassName

Arguments

:: Window

Browser window

-> String

The class string.

-> UI [Element]

Elements with given class.

Get a list of elements by particular class.

Layout

Combinators for quickly creating layouts. They can be adjusted with CSS later on.

grid :: [[UI Element]] -> UI Element

Align given elements in a rectangular grid.

Layout is achieved by using the CSS display:table property. The following element tree will be generated

 <div class="table">
   <div class="table-row">
     <div class="table-cell"> ... </div>
     <div class="table-cell"> ... </div>
   </div>
   <div class="table-row">
     ...
   </div>
  ...
  </div>

You can customatize the actual layout by assigning an id to the element and changing the .table, .table-row and table-column classes in a custom CSS file.

row :: [UI Element] -> UI Element

Align given elements in a row. Special case of grid.

column :: [UI Element] -> UI Element

Align given elements in a column. Special case of grid.

Events

For a list of predefined events, see Graphics.UI.Threepenny.Events.

type EventData = Value

Events may carry data. At the moment, they may return a single JSON value, as defined in the Data.Aeson module.

domEvent

Arguments

:: String

Event name. A full list can be found at http://www.w3schools.com/jsref/dom_obj_event.asp. Note that the on-prefix is not included, the name is click and so on.

-> Element

Element where the event is to occur.

-> Event EventData

Obtain DOM event for a given element.

unsafeFromJSON :: FromJSON a => EventData -> a

Convert event data to a Haskell value. Throws an exception when the data cannot be converted.

disconnect :: Window -> Event ()

Event that occurs whenever the client has disconnected, be it by closing the browser window or by exception.

Note: DOM Elements in a browser window that has been closed can no longer be manipulated.

on :: (element -> Event a) -> element -> (a -> UI void) -> UI ()

Convenience function to register Events for Elements.

Example usage.

on click element $ \_ -> ...

onEvent :: Event a -> (a -> UI void) -> UI ()

Register an UI action to be executed whenever the Event happens.

FIXME: Should be unified with on?

onChanges :: Behavior a -> (a -> UI void) -> UI ()

Execute a UI action whenever a Behavior changes. Use sparingly, it is recommended that you use sink instead.

module Reactive.Threepenny

Attributes

For a list of predefined attributes, see Graphics.UI.Threepenny.Attributes.

(#) :: a -> (a -> b) -> b infixl 8

Reverse function application. Allows convenient notation for setting properties.

Example usage.

mkElement "div"
    # set style     [("color","#CCAABB")]
    # set draggable True
    # set children  otherElements

(#.) :: UI Element -> String -> UI Element infixl 8

Convenient combinator for setting the CSS class on element creation.

type Attr x a = ReadWriteAttr x a a

Attributes can be set and get.

type WriteAttr x i = ReadWriteAttr x i ()

Attribute that only supports the set operation.

type ReadAttr x o = ReadWriteAttr x () o

Attribute that only supports the get operation.

data ReadWriteAttr x i o

Generalized attribute with different types for getting and setting.

Constructors

ReadWriteAttr

Fields

get' :: x -> UI o

set' :: i -> x -> UI ()

Instances

Functor (ReadWriteAttr x i)

set :: ReadWriteAttr x i o -> i -> UI x -> UI x

Set value of an attribute in the UI monad. Best used in conjunction with '#'.

sink :: ReadWriteAttr x i o -> Behavior i -> UI x -> UI x

Set the value of an attribute to a Behavior, that is a time-varying value.

Note: For reasons of efficiency, the attribute is only updated when the value changes.

get :: ReadWriteAttr x i o -> x -> UI o

Get attribute value.

mkReadWriteAttr

Arguments

:: (x -> UI o)

Getter.

-> (i -> x -> UI ())

Setter.

-> ReadWriteAttr x i o

Build an attribute from a getter and a setter.

mkWriteAttr :: (i -> x -> UI ()) -> WriteAttr x i

Build attribute from a setter.

mkReadAttr :: (x -> UI o) -> ReadAttr x o

Build attribute from a getter.

bimapAttr :: (i' -> i) -> (o -> o') -> ReadWriteAttr x i o -> ReadWriteAttr x i' o'

Map input and output type of an attribute.

fromObjectProperty :: (FromJS a, ToJS a, FFI (JSFunction a)) => String -> Attr Element a

Turn a JavaScript object property .prop = ... into an attribute.

Widgets

class Widget w where

Widgets are data types that have a visual representation.

Methods

getElement :: w -> Element

Instances

Widget Element

Widget TextEntry

Widget (ListBox a)

element :: MonadIO m => Widget w => w -> m Element

Convience synonym for return to make elements work well with set. Also works on Widgets.

Example usage.

e <- mkElement "button"
element e # set text "Ok"

widget :: Widget w => w -> UI w

Convience synonym for return to make widgets work well with set.

JavaScript FFI

Direct interface to JavaScript in the browser window.

debug :: String -> UI ()

Print a message on the client console if the client has debugging enabled.

class ToJS a

Helper class for rendering Haskell values as JavaScript expressions.

Minimal complete definition

render

Instances

ToJS Bool

ToJS Char

ToJS Double

ToJS Float

ToJS Int

ToJS Text

ToJS Value

ToJS JSObject

ToJS Element

ToJS a => ToJS [a]

class FFI a

Helper class for making ffi a variable argument function.

Minimal complete definition

fancy

Instances

FromJS b => FFI (JSFunction b)

(ToJS a, FFI b) => FFI (a -> b)

data JSFunction a

A JavaScript function with a given output type a.

Instances

Functor JSFunction

Change the output type of a JSFunction.

FromJS b => FFI (JSFunction b)

ffi :: FFI a => String -> a

Simple JavaScript FFI with string substitution.

Inspired by the Fay language. http://fay-lang.org/

example :: String -> Int -> JSFunction String
example = ffi "$(%1).prop('checked',%2)"

The ffi function takes a string argument representing the JavaScript code to be executed on the client. Occurrences of the substrings %1 to %9 will be replaced by subequent arguments.

Note: Always specify a type signature! The types automate how values are marshalled between Haskell and JavaScript. The class instances for the FFI class show which conversions are supported.

runFunction :: JSFunction () -> UI ()

Run the given JavaScript function and carry on. Doesn't block.

The client window uses JavaScript's eval() function to run the code.

callFunction :: JSFunction a -> UI a

Run the given JavaScript function and wait for results. Blocks.

The client window uses JavaScript's eval() function to run the code.

ffiExport :: IsHandler a => a -> UI JSObject

Export the given Haskell function so that it can be called from JavaScript code.

FIXME: At the moment, the function is not garbage collected.

Internal and oddball functions

fromJQueryProp :: String -> (Value -> a) -> (a -> Value) -> Attr Element a

Turn a jQuery property .prop() into an attribute.