Text.Blaze

BlazeMarkup is a markup combinator library. It provides a way to embed markup languages like HTML and SVG in Haskell in an efficient and convenient way, with a light-weight syntax.

To use the library, one needs to import a set of combinators. For example, you can use HTML 4 Strict from BlazeHtml package.

{-# LANGUAGE OverloadedStrings #-}
import Prelude hiding (head, id, div)
import Text.Blaze.Html4.Strict hiding (map)
import Text.Blaze.Html4.Strict.Attributes hiding (title)

To render the page later on, you need a so called Renderer. The recommended renderer is an UTF-8 renderer which produces a lazy bytestring.

import Text.Blaze.Renderer.Utf8 (renderMarkup)

Now, you can describe pages using the imported combinators.

page1 :: Markup
page1 = html $ do
    head $ do
        title "Introduction page."
        link ! rel "stylesheet" ! type_ "text/css" ! href "screen.css"
    body $ do
        div ! id "header" $ "Syntax"
        p "This is an example of BlazeMarkup syntax."
        ul $ mapM_ (li . toMarkup . show) [1, 2, 3]

The resulting HTML can now be extracted using:

renderMarkup page1

Important types.

type Markup = MarkupM ()

Simplification of the MarkupM datatype.

data Tag

Type for an HTML tag. This can be seen as an internal string type used by BlazeMarkup.

Instances

IsString Tag

data Attribute

Type for an attribute.

Instances

Monoid Attribute

data AttributeValue

The type for the value part of an attribute.

Instances

IsString AttributeValue

Monoid AttributeValue

ToValue AttributeValue

Creating attributes.

dataAttribute

Arguments

:: Tag

Name of the attribute.

-> AttributeValue

Value for the attribute.

-> Attribute

Resulting HTML attribute.

From HTML 5 onwards, the user is able to specify custom data attributes.

An example:

<p data-foo="bar">Hello.</p>

We support this in BlazeMarkup using this funcion. The above fragment could be described using BlazeMarkup with:

p ! dataAttribute "foo" "bar" $ "Hello."

customAttribute

Arguments

:: Tag

Name of the attribute

-> AttributeValue

Value for the attribute

-> Attribute

Resulting HTML attribtue

Create a custom attribute. This is not specified in the HTML spec, but some JavaScript libraries rely on it.

An example:

<select dojoType="select">foo</select>

Can be produced using:

select ! customAttribute "dojoType" "select" $ "foo"

Converting values to Markup.

class ToMarkup a where

Class allowing us to use a single function for Markup values

Minimal complete definition

toMarkup

Methods

toMarkup :: a -> Markup

Convert a value to Markup.

preEscapedToMarkup :: a -> Markup

Convert a value to Markup without escaping

Instances

ToMarkup Bool

ToMarkup Char

ToMarkup Double

ToMarkup Float

ToMarkup Int

ToMarkup Int32

ToMarkup Int64

ToMarkup Integer

ToMarkup Word

ToMarkup Word32

ToMarkup Word64

ToMarkup String

ToMarkup Text

ToMarkup Text

ToMarkup Markup

ToMarkup [Markup]

text

Arguments

:: Text

Text to render.

-> Markup

Resulting HTML fragment.

Render text. Functions like these can be used to supply content in HTML.

preEscapedText

Arguments

:: Text

Text to insert

-> Markup

Resulting HTML fragment

Render text without escaping.

lazyText

Arguments

:: Text

Text to insert

-> Markup

Resulting HTML fragment

A variant of text for lazy Text.

preEscapedLazyText

Arguments

:: Text

Text to insert

-> Markup

Resulting HTML fragment

A variant of preEscapedText for lazy Text

string

Arguments

:: String

String to insert.

-> Markup

Resulting HTML fragment.

Create an HTML snippet from a String.

preEscapedString

Arguments

:: String

String to insert.

-> Markup

Resulting HTML fragment.

Create an HTML snippet from a String without escaping

unsafeByteString

Arguments

:: ByteString

Value to insert.

-> Markup

Resulting HTML fragment.

Insert a ByteString. This is an unsafe operation:

• The ByteString could have the wrong encoding.
• The ByteString might contain illegal HTML characters (no escaping is done).

unsafeLazyByteString

Arguments

:: ByteString

Value to insert

-> Markup

Resulting HTML fragment

Insert a lazy ByteString. See unsafeByteString for reasons why this is an unsafe operation.

Comments

textComment :: Text -> Markup

Create a comment from a Text value. The text should not contain "--". This is not checked by the library.

lazyTextComment :: Text -> Markup

Create a comment from a Text value. The text should not contain "--". This is not checked by the library.

stringComment :: String -> Markup

Create a comment from a String value. The text should not contain "--". This is not checked by the library.

unsafeByteStringComment :: ByteString -> Markup

Create a comment from a ByteString value. The text should not contain "--". This is not checked by the library.

unsafeLazyByteStringComment :: ByteString -> Markup

Create a comment from a ByteString value. The text should not contain "--". This is not checked by the library.

Creating tags.

textTag

Arguments

:: Text

Text to create a tag from

-> Tag

Resulting tag

Create a Tag from some Text.

stringTag

Arguments

:: String

String to create a tag from

-> Tag

Resulting tag

Create a Tag from a String.

Converting values to attribute values.

class ToValue a where

Class allowing us to use a single function for attribute values

Minimal complete definition

toValue

Methods

toValue :: a -> AttributeValue

Convert a value to an attribute value

preEscapedToValue :: a -> AttributeValue

Convert a value to an attribute value without escaping

Instances

ToValue Bool

ToValue Char

ToValue Double

ToValue Float

ToValue Int

ToValue Int32

ToValue Int64

ToValue Integer

ToValue Word

ToValue Word32

ToValue Word64

ToValue String

ToValue Text

ToValue Text

ToValue AttributeValue

textValue

Arguments

:: Text

The actual value.

-> AttributeValue

Resulting attribute value.

Render an attribute value from Text.

preEscapedTextValue

Arguments

:: Text

The actual value

-> AttributeValue

Resulting attribute value

Render an attribute value from Text without escaping.

lazyTextValue

Arguments

:: Text

The actual value

-> AttributeValue

Resulting attribute value

A variant of textValue for lazy Text

preEscapedLazyTextValue

Arguments

:: Text

The actual value

-> AttributeValue

Resulting attribute value

A variant of preEscapedTextValue for lazy Text

stringValue :: String -> AttributeValue

Create an attribute value from a String.

preEscapedStringValue :: String -> AttributeValue

Create an attribute value from a String without escaping.

unsafeByteStringValue

Arguments

:: ByteString

ByteString value

-> AttributeValue

Resulting attribute value

Create an attribute value from a ByteString. See unsafeByteString for reasons why this might not be a good idea.

unsafeLazyByteStringValue

Arguments

:: ByteString

ByteString value

-> AttributeValue

Resulting attribute value

Create an attribute value from a lazy ByteString. See unsafeByteString for reasons why this might not be a good idea.

Setting attributes

(!) :: Attributable h => h -> Attribute -> h

Apply an attribute to an element.

Example:

img ! src "foo.png"

Result:

<img src="foo.png" />

This can be used on nested elements as well.

Example:

p ! style "float: right" $ "Hello!"

Result:

<p style="float: right">Hello!</p>

(!?) :: Attributable h => h -> (Bool, Attribute) -> h

Shorthand for setting an attribute depending on a conditional.

Example:

p !? (isBig, A.class "big") $ "Hello"

Gives the same result as:

(if isBig then p ! A.class "big" else p) "Hello"

Modifiying Markup trees

contents :: MarkupM a -> MarkupM b

Take only the text content of an HTML tree.

contents $ do
    p ! $ "Hello "
    p ! $ "Word!"

Result:

Hello World!