Text.Blaze.Internal

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.

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)

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).

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.

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>

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.