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!
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.
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.
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.
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!
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
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.
table : style -> List (Attribute variation msg) -> List (List (Element style variation msg)) -> Element style variation msg
A table is a special grid
{ rows : List Attributes.Length
, columns : List Attributes.Length
, cells : List (OnGrid (Element 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!
{ start : ( Basics.Int
, Basics.Int )
, width : Basics.Int
, height : Basics.Int
, content : Element style variation msg
}
Style.Internal.Model.NamedGridPosition
Internal.Model.OnGrid 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
.
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
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")
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.
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
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!
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.
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
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:
Window.resizes
from the Window
package.Element.classifyDevice
function which will convert Window.width
and Window.height
into a Device
record, which you should store in your model.Device
record in your view to specify how your page changes with window size.responsive
function to map one range to another.{ 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.
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.