UI.ListView

UI.ListView is a styled searchable row list. The main variation (select-lists) has the capability of having one of its rows selected.

The developer is responsible for coding the row's view. While this component then applies the borders and the click event. Also, it can optionally filter when having a search bar, and add an action bar.

view : RenderConfig -> Model -> Element Msg
view renderConfig model =
    ListView.selectList Msg.SelectElement
        elementToKey
        elementView
        |> ListView.withItems model.myListElements
        |> ListView.withSearchField
            { label = "Search for elements matching name.."
            , searchMsg = Msg.FilterSet
            , currentFilter =
                Maybe.map
                    (\str -> ( str, elementHasString ))
                    model.currentFilter
            }
        |> ListView.withActionBar
            { label = "Create new element"
            , icon = Icon.add
            , action =
                DialogMsg.OpenElementCreation
                    |> Msg.ForDialog
                    |> Action.DispatchMsg
            }
        |> ListView.withSelected
            (\{ id } ->
                Maybe.map (.id >> (==) id) model.selectedElement
                    |> Maybe.withDefault False
            )
        |> ListView.withWidth Element.fill
        |> ListView.renderElement renderConfig


elementHasString : String -> Element -> Bool
elementHasString str { name } =
    String.contains str name

Building

type ListView object msg

The ListView object msg type is used for describing the component for later rendering.

selectList :

(object -> msg)

-> (object -> String)

-> (Bool -> object -> Element msg)

-> ListView object msg

The main variation of UI.ListView. Click an element, and it will be selected.

ListView.selectList Msg.SelectElement
    (\{ name } ->
        Element.el [ Element.padding 8 ]
            (Element.text name)
    )

simpleList :

(object -> String)

-> (Bool -> object -> Element msg)

-> ListView object msg

A UI.ListView without built-in selection support.

ListView.simpleList
    (\{ name } ->
        Element.el [ Element.padding 8 ]
            (Element.text name)
    )

Toggleable variation

type alias ToggleableConfig object msg =

Config object msg

Configuration required to render a toggleable-list.

{ detailsShowLabel = "Show details" -- For accessibility only
, detailsCollapseLabel = "Hide details" -- For accessibility only
, toCover =
    \{ name } ->
        -- ListView.ToggleableCover
        { title = name, caption = Nothing }
, toDetails =
    \{ age } ->
        [ ( "Age", Element.text age ) ]
, selectMsg = Msg.ElementSelect
}

type alias ToggleableCover =

Cover

What is displayed in a collapsed toggleable-list.

{ title = "Some item"
, caption = Just "Created at 2020-06-10"
}

toggleableList : ToggleableConfig object msg -> ListView object msg

Toggleable-lists are a variation of select-lists where the selected element expands with details while all other's details keep collapsed.

We recommend using UI.Table instead, as it uses toggleable-lists for its responsive mode.

ListView.toggleableList
    { detailsShowLabel = "Show details" -- For accessibility only
    , detailsCollapseLabel = "Hide details" -- For accessibility only
    , toCover =
        \{ name } ->
            { title = name, caption = Nothing }
    , toDetails =
        \{ age } ->
            [ ( "Age", Element.text age ) ]
    , selectMsg = Msg.ElementSelect
    }
    |> ListView.withItems model.items
    |> ListView.withSelected isElementSelected
    |> ListView.renderElement renderConfig

NOTE: Toggleable-list elements' view is not codable.

Options

withItems : List object -> ListView object msg -> ListView object msg

Replaces the component's list of elements.

ListView.withItems
    [ { id = 0, name = "Catarina" }
    , { id = 1, name = "Gabriel" }
    ]
    someListView

withSelect : (object -> msg) -> ListView object msg -> ListView object msg

Adds a message to be dispatched when an item is selected.

ListView.withItems Msg.ElementSelect
    someListView

withSelected : (object -> Bool) -> ListView object msg -> ListView object msg

Marks every element as selected or not using a boolean-resulted lambda.

ListView.withSelected
    (\{ id } -> id == model.selectedId)
    someListView

withDomId : String -> ListView object msg -> ListView object msg

Add id attribute to the HTML tags of the elements and the list itself.

ListView.selectList
    Msg.SelectDrink
    softDrinkToString
    softDrinkView
    |> ListView.withDomId "softDrinks"

Generates:

< ... id="softDriks">
    <... id="fanta">...</...>
    <... id="coke">...</...>
    <... id="drPepper">...</...>
</...>

NOTE: Only when withDomId is used children have ids.

Extra elements

type alias SearchConfig object msg =

{ label : String

, searchMsg : String -> msg

, currentFilter : Maybe ( String, String -> object -> Bool )

}

SearchConfig assembles the required configuration for having a search field and filter.

{ title = "Elements"
, label = "Search for elements matching name.."
, searchMsg = Msg.FilterSet
, currentFilter =
    Maybe.map
        (\str -> ( str, elementHasString ))
        model.currentFilter
}

withSearchField :

SearchConfig object msg

-> ListView object msg

Replaces the component's search-field and allow filtering the elements.

ListView.withSearchFied
    { detailsShowLabel = "Show details" -- For accessibility only
    , detailsCollapseLabel = "Hide details" -- For accessibility only
    , toCover =
        \{ name } ->
            -- ListView.ToggleableCover
            { title = name, caption = Nothing }
    , toDetails =
        \{ age } ->
            [ ( "Age", Element.text age ) ]
    , selectMsg = Msg.ElementSelect
    }
    someListView

withActionBar : WithIcon msg -> ListView object msg -> ListView object msg

Replaces the component's action-bar. An action-bar is an additional pre-styled stick row that, when clicked, triggers an action.

ListView.withActionBar
    { label = "Create new element"
    , icon = Icon.add
    , onClick =
        Msg.UuidGen (Msg.ForDialog << DialogMsg.OpenElementCreation)
    }
    someListView

withSelectAllButton : (Bool -> msg) -> Bool -> ListView object msg -> ListView object msg

Adds a button to select every entry.

ListView.withSelectAllButton Msg.SelectAll
    isEverythingSelected
    someListView

withCustomExtraMenu :

msg

-> Bool

-> Element msg

-> ListView object msg

Adds button to toggle a custom menu element.

ListView.withCustomExtraMenu toggleMsg
    isMenuVisible
    menuBody
    someListView

withHeader : String -> ListView object msg -> ListView object msg

Adds a header above the list.

ListView.withHeader "ListView Header" someListView

withBadgedHeader : String -> Badge -> ListView object msg -> ListView object msg

Adds a header above the list, including a badge.

ListView.withBadgedHeader "ListView Header"
    (Badge.primaryLight "NEW")
    someListView

Width

withWidth : Length -> ListView object msg -> ListView object msg

Applies Element.width to the component.

ListView.withWidth
    (Element.fill |> Element.minimum 220)
    someListView

Select Style

type alias SelectStyle =

{ backgroundColor : Maybe Color }

The selected item can be styled using ListView.withSelectStyle.

backgroundColor: The color in which the background assumes for selected items. When Nothing no color is applied.

withSelectStyle : SelectStyle -> ListView object msg -> ListView object msg

Overwrite the appearance of the selected item.

ListView.withSelectStyle
    { backgroundColor = Palette.color toneDanger brightnessMiddle }
    someListView

Rendering

renderElement : RenderConfig -> ListView object msg -> Element msg

End of the builder's life. The result of this function is a ready-to-insert Elm UI's Element.

PaackEng/paack-ui/6.4.0

UI.ListView

Building

Toggleable variation

Options

Extra elements

Width

Select Style

Rendering

Modules