Safe Haskell	None
Language	Haskell98

Text.Blaze

Contents

Important types.
Creating attributes.
Converting values to Markup.
Comments
Creating tags.
Converting values to attribute values.
Setting attributes
Modifiying Markup trees

Description

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

Synopsis

type Markup = MarkupM ()
data Tag
data Attribute
data AttributeValue
dataAttribute :: Tag -> AttributeValue -> Attribute
customAttribute :: Tag -> AttributeValue -> Attribute
class ToMarkup a where
- toMarkup :: a -> Markup
- preEscapedToMarkup :: a -> Markup
text :: Text -> Markup
preEscapedText :: Text -> Markup
lazyText :: Text -> Markup
preEscapedLazyText :: Text -> Markup
string :: String -> Markup
preEscapedString :: String -> Markup
unsafeByteString :: ByteString -> Markup
unsafeLazyByteString :: ByteString -> Markup
textComment :: Text -> Markup
lazyTextComment :: Text -> Markup
stringComment :: String -> Markup
unsafeByteStringComment :: ByteString -> Markup
unsafeLazyByteStringComment :: ByteString -> Markup
textTag :: Text -> Tag
stringTag :: String -> Tag
class ToValue a where
- toValue :: a -> AttributeValue
- preEscapedToValue :: a -> AttributeValue
textValue :: Text -> AttributeValue
preEscapedTextValue :: Text -> AttributeValue
lazyTextValue :: Text -> AttributeValue
preEscapedLazyTextValue :: Text -> AttributeValue
stringValue :: String -> AttributeValue
preEscapedStringValue :: String -> AttributeValue
unsafeByteStringValue :: ByteString -> AttributeValue
unsafeLazyByteStringValue :: ByteString -> AttributeValue
(!) :: Attributable h => h -> Attribute -> h
(!?) :: Attributable h => h -> (Bool, Attribute) -> h
contents :: MarkupM a -> MarkupM a

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 #
Instance details Defined in Text.Blaze.Internal Methods fromString :: String -> Tag #

data Attribute #

Type for an attribute.

Instances

Semigroup Attribute #
Instance details Defined in Text.Blaze.Internal Methods (<>) :: Attribute -> Attribute -> Attribute # sconcat :: NonEmpty Attribute -> Attribute # stimes :: Integral b => b -> Attribute -> Attribute #
Monoid Attribute #
Instance details Defined in Text.Blaze.Internal Methods mempty :: Attribute # mappend :: Attribute -> Attribute -> Attribute # mconcat :: [Attribute] -> Attribute #

data AttributeValue #

The type for the value part of an attribute.

Instances

IsString AttributeValue #
Instance details Defined in Text.Blaze.Internal Methods fromString :: String -> AttributeValue #
Semigroup AttributeValue #
Instance details Defined in Text.Blaze.Internal Methods (<>) :: AttributeValue -> AttributeValue -> AttributeValue # sconcat :: NonEmpty AttributeValue -> AttributeValue # stimes :: Integral b => b -> AttributeValue -> AttributeValue #
Monoid AttributeValue #
Instance details Defined in Text.Blaze.Internal Methods mempty :: AttributeValue # mappend :: AttributeValue -> AttributeValue -> AttributeValue # mconcat :: [AttributeValue] -> AttributeValue #
ToValue AttributeValue #
Instance details Defined in Text.Blaze Methods toValue :: AttributeValue -> AttributeValue # preEscapedToValue :: AttributeValue -> 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 function. 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 #
Instance details Defined in Text.Blaze Methods toMarkup :: Bool -> Markup # preEscapedToMarkup :: Bool -> Markup #
ToMarkup Char #
Instance details Defined in Text.Blaze Methods toMarkup :: Char -> Markup # preEscapedToMarkup :: Char -> Markup #
ToMarkup Double #
Instance details Defined in Text.Blaze Methods toMarkup :: Double -> Markup # preEscapedToMarkup :: Double -> Markup #
ToMarkup Float #
Instance details Defined in Text.Blaze Methods toMarkup :: Float -> Markup # preEscapedToMarkup :: Float -> Markup #
ToMarkup Int #
Instance details Defined in Text.Blaze Methods toMarkup :: Int -> Markup # preEscapedToMarkup :: Int -> Markup #
ToMarkup Int32 #
Instance details Defined in Text.Blaze Methods toMarkup :: Int32 -> Markup # preEscapedToMarkup :: Int32 -> Markup #
ToMarkup Int64 #
Instance details Defined in Text.Blaze Methods toMarkup :: Int64 -> Markup # preEscapedToMarkup :: Int64 -> Markup #
ToMarkup Integer #
Instance details Defined in Text.Blaze Methods toMarkup :: Integer -> Markup # preEscapedToMarkup :: Integer -> Markup #
ToMarkup Natural #
Instance details Defined in Text.Blaze Methods toMarkup :: Natural -> Markup # preEscapedToMarkup :: Natural -> Markup #
ToMarkup Word #
Instance details Defined in Text.Blaze Methods toMarkup :: Word -> Markup # preEscapedToMarkup :: Word -> Markup #
ToMarkup Word32 #
Instance details Defined in Text.Blaze Methods toMarkup :: Word32 -> Markup # preEscapedToMarkup :: Word32 -> Markup #
ToMarkup Word64 #
Instance details Defined in Text.Blaze Methods toMarkup :: Word64 -> Markup # preEscapedToMarkup :: Word64 -> Markup #
ToMarkup String #
Instance details Defined in Text.Blaze Methods toMarkup :: String -> Markup # preEscapedToMarkup :: String -> Markup #
ToMarkup Text #
Instance details Defined in Text.Blaze Methods toMarkup :: Text -> Markup # preEscapedToMarkup :: Text -> Markup #
ToMarkup Text #
Instance details Defined in Text.Blaze Methods toMarkup :: Text -> Markup # preEscapedToMarkup :: Text -> Markup #
ToMarkup Builder #
Instance details Defined in Text.Blaze Methods toMarkup :: Builder -> Markup # preEscapedToMarkup :: Builder -> Markup #
ToMarkup Markup #
Instance details Defined in Text.Blaze Methods toMarkup :: Markup -> Markup # preEscapedToMarkup :: Markup -> Markup #
ToMarkup [Markup] #
Instance details Defined in Text.Blaze Methods toMarkup :: [Markup] -> Markup # preEscapedToMarkup :: [Markup] -> 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 ChoiceString.

preEscapedString #

Arguments

:: String	String to insert.
-> Markup	Resulting HTML fragment.

Create an HTML snippet from a ChoiceString without escaping

unsafeByteString #

Arguments

:: ByteString	Value to insert.
-> Markup	Resulting HTML fragment.

Insert a ChoiceString. This is an unsafe operation:

The ChoiceString could have the wrong encoding.
The ChoiceString 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 ChoiceString 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 ChoiceString value. The text should not contain "--". This is not checked by the library.

unsafeByteStringComment :: ByteString -> Markup #

Create a comment from a ChoiceString 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 ChoiceString.

stringTag #

Arguments

:: String	String to create a tag from
-> Tag	Resulting tag

Create a Tag from a ChoiceString.

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 #
Instance details Defined in Text.Blaze Methods toValue :: Bool -> AttributeValue # preEscapedToValue :: Bool -> AttributeValue #
ToValue Char #
Instance details Defined in Text.Blaze Methods toValue :: Char -> AttributeValue # preEscapedToValue :: Char -> AttributeValue #
ToValue Double #
Instance details Defined in Text.Blaze Methods toValue :: Double -> AttributeValue # preEscapedToValue :: Double -> AttributeValue #
ToValue Float #
Instance details Defined in Text.Blaze Methods toValue :: Float -> AttributeValue # preEscapedToValue :: Float -> AttributeValue #
ToValue Int #
Instance details Defined in Text.Blaze Methods toValue :: Int -> AttributeValue # preEscapedToValue :: Int -> AttributeValue #
ToValue Int32 #
Instance details Defined in Text.Blaze Methods toValue :: Int32 -> AttributeValue # preEscapedToValue :: Int32 -> AttributeValue #
ToValue Int64 #
Instance details Defined in Text.Blaze Methods toValue :: Int64 -> AttributeValue # preEscapedToValue :: Int64 -> AttributeValue #
ToValue Integer #
Instance details Defined in Text.Blaze Methods toValue :: Integer -> AttributeValue # preEscapedToValue :: Integer -> AttributeValue #
ToValue Word #
Instance details Defined in Text.Blaze Methods toValue :: Word -> AttributeValue # preEscapedToValue :: Word -> AttributeValue #
ToValue Word32 #
Instance details Defined in Text.Blaze Methods toValue :: Word32 -> AttributeValue # preEscapedToValue :: Word32 -> AttributeValue #
ToValue Word64 #
Instance details Defined in Text.Blaze Methods toValue :: Word64 -> AttributeValue # preEscapedToValue :: Word64 -> AttributeValue #
ToValue String #
Instance details Defined in Text.Blaze Methods toValue :: String -> AttributeValue # preEscapedToValue :: String -> AttributeValue #
ToValue Text #
Instance details Defined in Text.Blaze Methods toValue :: Text -> AttributeValue # preEscapedToValue :: Text -> AttributeValue #
ToValue Text #
Instance details Defined in Text.Blaze Methods toValue :: Text -> AttributeValue # preEscapedToValue :: Text -> AttributeValue #
ToValue Builder #
Instance details Defined in Text.Blaze Methods toValue :: Builder -> AttributeValue # preEscapedToValue :: Builder -> AttributeValue #
ToValue AttributeValue #
Instance details Defined in Text.Blaze Methods toValue :: AttributeValue -> AttributeValue # preEscapedToValue :: AttributeValue -> AttributeValue #

textValue #

Arguments

:: Text	The actual value.
-> AttributeValue	Resulting attribute value.

Render an attribute value from ChoiceString.

preEscapedTextValue #

Arguments

:: Text	The actual value
-> AttributeValue	Resulting attribute value

Render an attribute value from ChoiceString 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 ChoiceString.

preEscapedStringValue :: String -> AttributeValue #

Create an attribute value from a ChoiceString without escaping.

unsafeByteStringValue #

Arguments

:: ByteString	ByteString value
-> AttributeValue	Resulting attribute value

Create an attribute value from a ChoiceString. 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 a #

Take only the text content of an HTML tree.

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

Result:

Hello World!