Graphics.UI.Threepenny.Core

Guide

Threepenny runs a small web server that displays the user interface as a web page to any browser that connects to it. To start the web server, use the startGUI function.

Creating of DOM elements is easy, the '(#+)' combinator allows a style similar to HTML combinator libraries.

Existing DOM elements can be accessed much in the same way they are accessed from JavaScript; they can be searched, updated, moved and inspected. Events can be bound to DOM elements and handled.

Applications written in Threepenny are multithreaded. Each client (user) has a separate thread which runs with no awareness of the asynchronous protocol below. Each session should only be accessed from one thread. There is not yet any clever architecture for accessing the (single threaded) web browser from multi-threaded Haskell. That's my recommendation. You can choose to ignore it, but don't blame me when you run an element search and you get a click event as a result.

This project was originally called Ji.

Server

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

data Config

Record for configuring the Threepenny GUI server.

Constructors

Config

Fields

tpPort :: Int

Port number.

tpCustomHTML :: Maybe FilePath

Custom HTML file to replace the default one.

tpStatic :: FilePath

Directory that is served under /static.

startGUI

Arguments

:: Config

Server configuration.

-> (Window -> IO ())

Action to run whenever a client browser connects.

-> IO ()

Start server for GUI sessions.

loadFile

Arguments

:: Window

Browser window

-> String

MIME type

-> FilePath

Local path to the file

-> IO String

Generated URI

Make a local file available as a relative URI.

loadDirectory :: Window -> FilePath -> IO String

Make a local directory available as a relative URI.

Browser Window

type Window = Session

The client browser window.

title :: WriteAttr Window String

Title of the client window.

cookies :: ReadAttr Window [(String, String)]

Cookies on the client.

getRequestLocation :: Window -> IO URI

Get the request location.

DOM elements

Create and manipulate DOM elements.

data Element

Reference to an element in the DOM of the client window.

mkElement

Arguments

:: String

Tag name

-> IO Element

Make a new DOM element.

getWindow :: Element -> IO (Maybe Window)

Retreive the browser Window in which the element resides.

Note that elements do not reside in any browser window when they are first created. To move the element to a particular browser window, you have to append it to a parent, for instance with the `(#+)` operator.

WARNING: The ability to move elements from one browser window to another is currently not implemented yet.

delete :: Element -> IO ()

Delete the given element.

(#+) :: IO Element -> [IO Element] -> IO Element

Append DOM elements as children to a given element.

string :: String -> IO Element

Make a span element with a given text content.

getHead :: Window -> IO Element

Get the head of the page.

getBody :: Window -> IO Element

Get the body of the page.

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.

getValuesList

Arguments

:: [Element]

A list of elements to get the values of.

-> IO [String]

The list of plain text values.

Get values from inputs. Blocks. This is faster than many getValue invocations.

getElementsByTagName

Arguments

:: Window

Browser window

-> String

The tag name.

-> IO [Element]

All elements with that tag name.

Get all elements of the given tag name. Blocks.

getElementByTagName

Arguments

:: Window

Browser window

-> String

The tag name.

-> IO (Maybe Element)

An element (if any) with that tag name.

Get an element by its tag name. Blocks.

getElementsById

Arguments

:: Window

Browser window

-> [String]

The ID string.

-> IO [Element]

Elements with given ID.

Get a list of elements by particular IDs. Blocks.

getElementById

Arguments

:: Window

Browser window

-> String

The ID string.

-> IO (Maybe Element)

Element (if any) with given ID.

Get an element by a particular ID. Blocks.

Layout

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

grid :: [[IO Element]] -> IO 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 :: [IO Element] -> IO Element

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

column :: [IO Element] -> IO Element

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

Events

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

data EventData

Data from an event. At the moment it is empty.

Constructors

EventData [Maybe String]

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.

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

Convenience function to register Events for Elements.

Example usage.

 on click element $ \_ -> ...

module Control.Event

Attributes

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

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

Reverse function application. Allows convenient notation for setting properties.

Example usage.

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

(#.) :: IO Element -> String -> IO Element

Convenient combinator for setting the CSS class on element creation.

element :: Element -> IO Element

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

Example usage.

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

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 -> IO o

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

set :: MonadIO m => ReadWriteAttr x i o -> i -> m x -> m x

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

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

Get attribute value.

mkReadWriteAttr

Arguments

:: (x -> IO o)

Getter.

-> (i -> x -> IO ())

Setter.

-> ReadWriteAttr x i o

Build an attribute from a getter and a setter.

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

Build attribute from a setter.

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

Build attribute from a getter.

JavaScript FFI

Direct interface to JavaScript in the browser window.

debug

Arguments

:: Window

Client window

-> String

Some plain text to send to the client.

-> IO ()

Send a debug message to the client. The behaviour of the client is unspecified.

clear :: Window -> IO ()

Clear the client's DOM.

class ToJS a

Class for rendering Haskell types as JavaScript code.

Instances

ToJS Bool

ToJS Int

ToJS String

ToJS JSValue

class FFI a

Helper class for making a simple JavaScript FFI

Instances

FFI (JSFunction String)

FFI (JSFunction ())

FFI (JSFunction JSValue)

(ToJS a, FFI b) => FFI (a -> 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.

data JSFunction a

Representation of a JavaScript expression with a girven output type.

Instances

Functor JSFunction

FFI (JSFunction String)

FFI (JSFunction ())

FFI (JSFunction JSValue)

runFunction :: Window -> JSFunction () -> IO ()

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

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

callFunction :: Window -> JSFunction a -> IO a

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

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

callDeferredFunction

Arguments

:: Window

Browser window

-> String

The function name.

-> [String]

Parameters.

-> ([Maybe String] -> IO ())

The continuation to call if/when the function completes.

-> IO ()

Call the given function with the given continuation. Doesn't block.

atomic :: Window -> IO a -> IO a

Atomically execute the given computation in the context of a browser window

Internal and oddball functions

updateElement :: (Element -> IO ()) -> Element -> IO ()

manifestElement :: Window -> Element -> IO Element

audioPlay :: Element -> IO ()

fromProp :: String -> (JSValue -> a) -> (a -> JSValue) -> Attr Element a