blaze-html-0.4.3.1: A blazingly fast HTML combinator library for Haskell

Text.Blaze.Internal

Contents

- Important types.
- Creating custom tags and attributes.
- Converting values to HTML.
- Converting values to tags.
- Converting values to attribute values.
- Setting attributes
- Modifying HTML elements

Description

The BlazeHtml core, consisting of functions that offer the power to generate custom HTML elements. It also offers user-centric functions, which are exposed through `Text.Blaze`.

While this module is exported, usage of it is not recommended, unless you know what you are doing. This module might undergo changes at any time.

Synopsis

- data ChoiceString
  - = Static !StaticString
  - | String String
  - | Text Text
  - | ByteString ByteString
  - | PreEscaped ChoiceString
  - | External ChoiceString
  - | AppendChoiceString ChoiceString ChoiceString
  - | EmptyChoiceString
- data StaticString = StaticString {
  - getString :: String -> String
  - getUtf8ByteString :: ByteString
  - getText :: Text
  }
- data HtmlM a
  - = forall b . Parent StaticString StaticString StaticString (HtmlM b)
  - | Leaf StaticString StaticString StaticString
  - | Content ChoiceString
  - | forall b c . Append (HtmlM b) (HtmlM c)
  - | AddAttribute StaticString StaticString ChoiceString (HtmlM a)
  - | AddCustomAttribute ChoiceString ChoiceString ChoiceString (HtmlM a)
  - | Empty
- type Html = HtmlM ()
- data Tag
- data Attribute
- data AttributeValue
- attribute :: Tag -> Tag -> AttributeValue -> Attribute
- dataAttribute :: Tag -> AttributeValue -> Attribute
- customAttribute :: Tag -> AttributeValue -> Attribute
- text :: Text -> Html
- preEscapedText :: Text -> Html
- lazyText :: Text -> Html
- preEscapedLazyText :: Text -> Html
- string :: String -> Html
- preEscapedString :: String -> Html
- unsafeByteString :: ByteString -> Html
- unsafeLazyByteString :: ByteString -> Html
- textTag :: Text -> Tag
- stringTag :: String -> Tag
- textValue :: Text -> AttributeValue
- preEscapedTextValue :: Text -> AttributeValue
- lazyTextValue :: Text -> AttributeValue
- preEscapedLazyTextValue :: Text -> AttributeValue
- stringValue :: String -> AttributeValue
- preEscapedStringValue :: String -> AttributeValue
- unsafeByteStringValue :: ByteString -> AttributeValue
- unsafeLazyByteStringValue :: ByteString -> AttributeValue
- class Attributable h where
  - (!) :: h -> Attribute -> h
- external :: HtmlM a -> HtmlM a

# Important types.

data ChoiceString

A string denoting input from different string representations.

Constructors

Static !StaticString | Static data
String String | A Haskell String
Text Text | A Text value
ByteString ByteString | An encoded bytestring
PreEscaped ChoiceString | A pre-escaped string
External ChoiceString | External data in style/script tags, should be checked for validity
AppendChoiceString ChoiceString ChoiceString | Concatenation
EmptyChoiceString | Empty string

Instances

IsString ChoiceString |
Monoid ChoiceString |

data StaticString

A static string that supports efficient output to all possible backends.

Constructors

StaticString |

Fields

getString :: String -> String

  Appending haskell string

getUtf8ByteString :: ByteString

  UTF-8 encoded bytestring

getText :: Text

  Text value

Instances

IsString StaticString |

data HtmlM a

The core HTML datatype.

Constructors

forall b . Parent StaticString StaticString StaticString (HtmlM b) | Tag, open tag, end tag, content
Leaf StaticString StaticString StaticString | Tag, open tag, end tag
Content ChoiceString | HTML content
forall b c . Append (HtmlM b) (HtmlM c) | Concatenation of two HTML pieces
AddAttribute StaticString StaticString ChoiceString (HtmlM a) | Add an attribute to the inner HTML. Raw key, key, value, HTML to receive the attribute.
AddCustomAttribute ChoiceString ChoiceString ChoiceString (HtmlM a) | Add a custom attribute to the inner HTML.
Empty | Empty HTML.

Instances

Monad HtmlM |
Typeable1 HtmlM |
ToHtml Html |
IsString (HtmlM a) |
Monoid a => Monoid (HtmlM a) |
Attributable (HtmlM a) |
ToHtml [Html] |
Attributable (HtmlM a -> HtmlM b) |

type Html = HtmlM ()

Simplification of the `HtmlM` datatype.

data Tag

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

Instances

IsString Tag |

data Attribute

Type for an attribute.

data AttributeValue

The type for the value part of an attribute.

Instances

IsString AttributeValue |
Monoid AttributeValue |
ToValue AttributeValue |

# Creating custom tags and attributes.

attribute

Arguments

:: Tag | Raw key
-> Tag | Shared key string for the HTML attribute.
-> AttributeValue | Value for the HTML attribute.
-> Attribute | Resulting HTML attribute.

Create an HTML attribute that can be applied to an HTML element later using the `!` operator.

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 BlazeHtml using this funcion. The above fragment could be described using BlazeHtml 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 HTML.

text

Arguments

:: Text | Text to render.
-> Html | Resulting HTML fragment.

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

preEscapedText

Arguments

:: Text | Text to insert
-> Html | Resulting HTML fragment

Render text without escaping.

lazyText

Arguments

:: Text | Text to insert
-> Html | Resulting HTML fragment

A variant of `text` for lazy `Text`.

preEscapedLazyText

Arguments

:: Text | Text to insert
-> Html | Resulting HTML fragment

A variant of `preEscapedText` for lazy `Text`

string

Arguments

:: String | String to insert.
-> Html | Resulting HTML fragment.

Create an HTML snippet from a `String`.

preEscapedString

Arguments

:: String | String to insert.
-> Html | Resulting HTML fragment.

Create an HTML snippet from a `String` without escaping

unsafeByteString

Arguments

:: ByteString | Value to insert.
-> Html | 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
-> Html | Resulting HTML fragment

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

# Converting values to 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.

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

class Attributable h where

Used for applying attributes. You should not define your own instances of this class.

Methods

(!) :: 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>

Instances

Attributable (HtmlM a) |
Attributable (HtmlM a -> HtmlM b) |

# Modifying HTML elements

external :: HtmlM a -> HtmlM a

Mark HTML as external data. External data can be:

- CSS data in a `style` tag;
- Script data in a `script` tag.

This function is applied automatically when using the `style` or `script` combinators.