elm-lang/core/1.1.1

NOTE: this package moved to elm/core

NOTE: this package is not compatible with Elm 0.19.1

Text

A library for styling and displaying text. While the String library focuses on representing and manipulating strings of character strings, the Text library focuses on how those strings should look on screen. It lets you make text bold or italic, set the typeface, set the text size, etc.

Creating Text

fromString : String -> Text

Convert a string into text which can be styled and displayed. To show the string "Hello World!" on screen in italics, you could say:

main = leftAligned (italic (fromString "Hello World!"))
empty : Text

Text with nothing in it.

empty = fromString ""
append : Text -> Text -> Text

Put two chunks of text together.

append (fromString "hello ") (fromString "world") == fromString "hello world"
concat : List Text -> Text

Put many chunks of text together.

concat
  [ fromString "type "
  , bold (fromString "Maybe")
  , fromString " = Just a | Nothing"
  ]
join : Text -> List Text -> Text

Put many chunks of text together with a separator.

chunks : List Text
chunks = List.map fromString ["lions","tigers","bears"]


join (fromString ", ") chunks == fromString "lions, tigers, bears"

Creating Elements

Each of the following functions places Text into a box. The function you use determines the alignment of the text.

leftAligned : Text -> Element

Align text along the left side of the text block. This is sometimes known as ragged right.

rightAligned : Text -> Element

Align text along the right side of the text block. This is sometimes known as ragged left.

centered : Text -> Element

Center text in the text block. There is equal spacing on either side of a line of text.

justified : Text -> Element

Align text along the left and right sides of the text block. Word spacing is adjusted to make this possible.

Links and Style

type alias Style =
{ typeface : List String
, height : Maybe Float
, color : Color
, bold : Bool
, italic : Bool
, line : Maybe Line
}

Represents all the ways you can style Text. If the typeface list is empty or the height is Nothing, the users will fall back on their browser's default settings. The following Style is black, 16 pixel tall, underlined, and Times New Roman (assuming that typeface is available on the user's computer):

{ typeface = [ "Times New Roman", "serif" ]
, height   = Just 16
, color    = black
, bold     = False
, italic   = False
, line     = Just Under
}
style : Style -> Text -> Text

Set the style of some text. For example, if you design a Style called footerStyle that is specifically for the bottom of your page, you could apply it to text like this:

style footerStyle (fromString "the old prince / 2007")
defaultStyle : Style

Plain black text. It uses the browsers default typeface and text height. No decorations are used.

{ typeface = []
, height = Nothing
, color = black
, bold = False
, italic = False
, line = Nothing
}
type Line
= Under
| Over
| Through

Styles for lines on text. This allows you to add an underline, an overline, or a strike out text:

line Under   (fromString "underline")
line Over    (fromString "overline")
line Through (fromString "strike out")

Convenience Functions

There are two convenience functions for creating an Element which can be useful when debugging or prototyping:

plainText : String -> Element

Display a string with no styling.

plainText string = leftAligned (fromString string)
asText : a -> Element

Convert anything to its textual representation and make it displayable in the browser. Excellent for debugging.

asText value = leftAligned (monospace (fromString (toString value)))

There are also a bunch of functions to set parts of a Style individually:

typeface : List String -> Text -> Text

Provide a list of preferred typefaces for some text.

["helvetica","arial","sans-serif"]

Not every browser has access to the same typefaces, so rendering will use the first typeface in the list that is found on the user's computer. If there are no matches, it will use their default typeface. This works the same as the CSS font-family property.

monospace : Text -> Text

Switch to a monospace typeface. Good for code snippets.

monospace (fromString "foldl (+) 0 [1,2,3]")
height : Float -> Text -> Text

Set the height of some text.

height 40 (fromString "Title")
color : Color -> Text -> Text

Set the color of some text.

color red (fromString "Red")
bold : Text -> Text

Make text bold.

fromString "sometimes you want " ++ bold (fromString "emphasis")
italic : Text -> Text

Make text italic.

fromString "make it " ++ italic (fromString "important")
line : Line -> Text -> Text

Put lines on text.

line Under   (fromString "underlined")
line Over    (fromString "overlined")
line Through (fromString "strike out")