mdgriffith / style-elements / Element

Capture Layout in your View

Think of Elements as Html with layout!

By building your view with Elements, you have a single place to go to adjust or add to your layout, which is great because that's usually what you're doing in your view!

Rendering

layout : StyleSheet style variation -> Element style variation msg -> Html msg

Embeds the stylesheet and renders the Element's into Html.

viewport : StyleSheet style variation -> Element style variation msg -> Html msg

Same as layout, but the height and width of the site is set to the height and width of the screen.

Basic Elements


type alias Element style variation msg =
Internal.Model.Element style variation msg

You can think of an Element as Html with built-in layout.

It has one style identifier, which you can think of as a CSS class.

It can also have style variations, which are covered in the Style module.


type alias Attribute variation msg =
Internal.Model.Attribute variation msg

empty : Element style variation msg

text : String -> Element style variation msg

el : style -> List (Attribute variation msg) -> Element style variation msg -> Element style variation msg

The most basic element.

You need to specify a style, a list of attributes, and a single child.

-- an element with the style `MyStyle`, that is aligned left, and has one child.
el MyStyle [ alignLeft ] (text "Hello World!")

el can only have one child because in order to have multiple children, we need to specify how the layout would work.

when : Basics.Bool -> Element style variation msg -> Element style variation msg

A helper function. This:

when (x == 5) (text "yay, it's 5")

is sugar for

if (x == 5) then
    text "yay, it's 5"
else
    empty

whenJust : Maybe a -> (a -> Element style variation msg) -> Element style variation msg

Another helper function that defaults to empty

whenJust (Just ("Hi!")) text

is sugar for

case maybe of
    Nothing ->
        empty
    Just x ->
        text x

html : Html msg -> Element style variation msg

For when you want to embed Html.

If you're using this library, I'd encourage you to try to solve your problem without using this escape hatch.

Usage of this function makes the most sense when you're dealing with Html from another module or package or if you need to craft something "manually" yourself.

map : (a -> msg) -> Element style variation a -> Element style variation msg

Change the msg that an Element is sending.

An analog of Html.map.

mapAll : (msgA -> msgB) -> (styleA -> styleB) -> (variationA -> variationB) -> Element styleA variationA msgA -> Element styleB variationB msgB

Map the msg, style, and variation that is used.

full : style -> List (Attribute variation msg) -> Element style variation msg -> Element style variation msg

A full element will ignore the spacing set for it by the parent, and also grow to cover the parent's padding.

This is mostly useful in text layouts.

Layout

A layout element will explicitly define how it's children are layed out.

Make sure to check out the Style Element specific attributes in Element.Attributes as they will help out when doing layout!

Linear Layouts

row : style -> List (Attribute variation msg) -> List (Element style variation msg) -> Element style variation msg

column : style -> List (Attribute variation msg) -> List (Element style variation msg) -> Element style variation msg

wrappedRow : style -> List (Attribute variation msg) -> List (Element style variation msg) -> Element style variation msg

wrappedColumn : style -> List (Attribute variation msg) -> List (Element style variation msg) -> Element style variation msg

Text Layout

textLayout : style -> List (Attribute variation msg) -> List (Element style variation msg) -> Element style variation msg

A text layout.

Children that are aligned left or right will be floated left or right. Everything else is arranged in the standard 'block' layout of css, meaning a column flowing down.

paragraph : style -> List (Attribute variation msg) -> List (Element style variation msg) -> Element style variation msg

Paragraph is actually a layout if you can believe it!

This is the same as a textLayout, except all of the children are set to display:inline.

Because all the children are inline, they will not respect a width or height set on them.

Grid Layout

table : style -> List (Attribute variation msg) -> List (List (Element style variation msg)) -> Element style variation msg

A table is a special grid


type alias Grid style variation msg =
{ rows : List Attributes.Length
, columns : List Attributes.Length
, cells : List (OnGrid (Element style variation msg)) 
}


type alias NamedGrid style variation msg =
{ rows : List ( Attributes.Length
, List Style.Internal.Model.NamedGridPosition )
, columns : List Attributes.Length
, cells : List (NamedOnGrid (Element style variation msg)) 
}

grid : style -> List (Attribute variation msg) -> Grid style variation msg -> Element style variation msg

An interface to css grid. Here's a basic example:

grid MyGridStyle []
    { columns = [ px 100, px 100, px 100, px 100 ]
    , rows =
        [ px 100
        , px 100
        , px 100
        , px 100
        ]
    , cells =
         [ cell
            { start = ( 0, 0 )
            , width = 1
            , height = 1
            , content =
                el Box [] (text "box")
            }
        , cell
            { start = ( 1, 1 )
            , width = 1
            , height = 2
            , content =
                el Box [] (text "box")
            }
        ]
    }

namedGrid : style -> List (Attribute variation msg) -> NamedGrid style variation msg -> Element style variation msg

With a named grid, you can name areas within the grid and use that name to place an element.

Here's an example:

namedGrid MyGridStyle []
    { columns = [ px 200, px 200, px 200, fill 1 ]
    , rows =
        [ px 200 => [ spanAll "header" ]
        , px 200 => [ span 3 "content", span 1 "sidebar" ]
        , px 200 => [ span 3 "content", span 1 "sidebar" ]
        , px 200 => [ spanAll "footer" ]
        ]
    , cells =
        [ named "header"
            (el Box [] (text "box"))
        , named "sidebar"
            (el Box [] (text "box"))
        ]
    }

note: this example uses rocket(=>) as a synonym for creating a tuple. For more, check out the rocket update package!


type alias GridPosition style variation msg =
{ start : ( Basics.Int
, Basics.Int )
, width : Basics.Int
, height : Basics.Int
, content : Element style variation msg 
}


type alias NamedGridPosition =
Style.Internal.Model.NamedGridPosition


type alias OnGrid thing =
Internal.Model.OnGrid thing


type alias NamedOnGrid thing =
Internal.Model.NamedOnGrid thing

cell : GridPosition style variation msg -> OnGrid (Element style variation msg)

A specific position on a grid.

named : String -> Element style variation msg -> NamedOnGrid (Element style variation msg)

Specify a named postion on a namedGrid.

span : Basics.Int -> String -> NamedGridPosition

Used to define named areas in a namedGrid.

spanAll : String -> NamedGridPosition

Used to define named areas in a namedGrid.

Positioning

It can be useful to position something near another element.

In CSS terms, this positions children using 'position:absolute'. So, to position three boxes below a container, we could do the following:

 el MyStyle [ width (px 200), height (px 200) ] empty
    |> below
        [ el Box [ width (px 40), height (px 40) ] empty
        -- below on the right
        , el Box [ alignRight, width (px 40), height (px 40) ] empty
        -- below and centered
        , el Box [ center, width (px 40), height (px 40) ] empty
        ]

below : List (Element style variation msg) -> Element style variation msg -> Element style variation msg

above : List (Element style variation msg) -> Element style variation msg -> Element style variation msg

onRight : List (Element style variation msg) -> Element style variation msg -> Element style variation msg

onLeft : List (Element style variation msg) -> Element style variation msg -> Element style variation msg

within : List (Element style variation msg) -> Element style variation msg -> Element style variation msg

screen : Element style variation msg -> Element style variation msg

Position an element relative to the window.

Essentially the same as display: fixed.

If you're trying to make a modal, check out Element.Location.modal

Linking

link : String -> Element style variation msg -> Element style variation msg

Turn an element into a link.

link "http://zombo.com"
    <| el MyStyle [] (text "Welcome to Zombocom")

Wraps an element in an <a> and sets the href. rel properties are set to noopener and noreferrer.

newTab : String -> Element style variation msg -> Element style variation msg

Make a link that opens in a new tab.

Depending on the browsers configiration, it may open in a new window.

newTab "http://zombo.com"
    <| el MyStyle (text "Welcome to Zombocom")

Same as target "_blank"

download : String -> Element style variation msg -> Element style variation msg

Make a link that will download a file

download "http://zombo.com/schedule.pdf"
    <| el MyStyle (text "Welcome to Zombocom")

downloadAs : { src : String, filename : String } -> Element style variation msg -> Element style variation msg

Make a link that will download a file and give it a specific filename.

downloadAs
    { src = "http://zombo.com/schedule.pdf"
    , filename = "zombocomSchedule.pdf"
    }
    <| el MyStyle (text "Welcome to Zombocom")

Markup

node : String -> Element style variation msg -> Element style variation msg

button : style -> List (Attribute variation msg) -> Element style variation msg -> Element style variation msg

Renders as a <button>

Also is able to receive keyboard focus.

hairline : style -> Element style variation msg

Creates a 1 px tall horizontal line.

If you want a horizontal rule that is something more specific, craft it with el!

article : style -> List (Attribute variation msg) -> Element style variation msg -> Element style variation msg

section : style -> List (Attribute variation msg) -> Element style variation msg -> Element style variation msg

aside : style -> List (Attribute variation msg) -> Element style variation msg -> Element style variation msg

spacer : Basics.Float -> Element style variation msg

An element for adding additional spacing. The Float is the multiple that should be used of the spacing that's being set by the parent.

So, if the parent element is a column that set spacing to 5, and this spacer was a 2. Then it would be a 10 pixel spacer.

circle : Basics.Float -> style -> List (Attribute variation msg) -> Element style variation msg -> Element style variation msg

A simple circle. Provide the radius it should have.

Automatically sets the propery width, height, and corner rounded.

Significant Locations

navigation : style -> List (Attribute variation msg) -> { options : List (Element style variation msg), name : String } -> Element style variation msg

The main navigation of the site, rendered as a row.

The required name is used by accessibility software to describe to non-sighted users what this navigation element pertains to.

Don't leave name blank, even if you just put "Main Navigation" in it.

 navigation NavMenuStyle
    []
    { name = "Main Navigation"
    , options =
        [ link "/profile" (el NavLink [] (text "profile"))
        , link "/logout" (el NavLink [] (text "logout"))
        ]
    }

navigationColumn : style -> List (Attribute variation msg) -> { options : List (Element style variation msg), name : String } -> Element style variation msg

header : style -> List (Attribute variation msg) -> Element style variation msg -> Element style variation msg

This is the main page header area.

mainContent : style -> List (Attribute variation msg) -> Element style variation msg -> Element style variation msg

The main content of your page.

footer : style -> List (Attribute variation msg) -> Element style variation msg -> Element style variation msg

This is the main page footer where your copyright and other infomation should live.

sidebar : style -> List (Attribute variation msg) -> List (Element style variation msg) -> Element style variation msg

This is a sidebar which contains complementary information to your main content.

It's rendered as a column.

search : style -> List (Attribute variation msg) -> Element style variation msg -> Element style variation msg

An area that houses the controls for running a search.

While Element.Input.search will create a literal search input, this element is meant to group all the controls that are involved with searching, such as filters and the search button.

modal : style -> List (Attribute variation msg) -> Element style variation msg -> Element style variation msg

This is a modal

Headings

h1 : style -> List (Attribute variation msg) -> Element style variation msg -> Element style variation msg

h2 : style -> List (Attribute variation msg) -> Element style variation msg -> Element style variation msg

h3 : style -> List (Attribute variation msg) -> Element style variation msg -> Element style variation msg

h4 : style -> List (Attribute variation msg) -> Element style variation msg -> Element style variation msg

h5 : style -> List (Attribute variation msg) -> Element style variation msg -> Element style variation msg

h6 : style -> List (Attribute variation msg) -> Element style variation msg -> Element style variation msg

subheading : style -> List (Attribute variation msg) -> String -> Element style variation msg

Don't use a heading like h2 if you want a subheading/subtitle, instead use this element!

Images

image : style -> List (Attribute variation msg) -> { src : String, caption : String } -> Element style variation msg

For images, both a source and a caption are required. The caption will serve as the alt-text.

decorativeImage : style -> List (Attribute variation msg) -> { src : String } -> Element style variation msg

If an image is purely decorative, you can skip the caption.

Text Markup

These elements are useful for quick text markup.

bold : String -> Element style variation msg

italic : String -> Element style variation msg

strike : String -> Element style variation msg

underline : String -> Element style variation msg

sub : String -> Element style variation msg

super : String -> Element style variation msg

Responsive

Since this library moves all layout and positioning logic to the view instead of the stylesheet, it doesn't make a ton of sense to support media queries in the stylesheet.

Instead, responsiveness is controlled directly in the view.

Here's how it's done:

  1. Set up a subscription to Window.resizes from the Window package.
  2. Use the Element.classifyDevice function which will convert Window.width and Window.height into a Device record, which you should store in your model.
  3. Use the Device record in your view to specify how your page changes with window size.
  4. If things get crazy, use the responsive function to map one range to another.


type alias Device =
{ width : Basics.Int
, height : Basics.Int
, phone : Basics.Bool
, tablet : Basics.Bool
, desktop : Basics.Bool
, bigDesktop : Basics.Bool
, portrait : Basics.Bool 
}

classifyDevice : { window | width : Basics.Int, height : Basics.Int } -> Device

Takes in a Window.Size and returns a device profile which can be used for responsiveness.

responsive : Basics.Float -> ( Basics.Float, Basics.Float ) -> ( Basics.Float, Basics.Float ) -> Basics.Float

Define two ranges that should linearly match up with each other.

Provide a value for the first and receive the calculated value for the second.

fontsize =
    responsive device.width ( 600, 1200 ) ( 16, 20 )

When the device width is between 600 and 1200, set the font-size between 16 and 20 using a linear scale.

Advanced Rendering

toHtml : StyleSheet style variation -> Element style variation msg -> Html msg

Renders Element's into Html, but does not embed a stylesheet.

embedStylesheet : StyleSheet style variation -> Html msg

Embed a stylesheet.