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 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
            , onClick =
                Msg.UuidGen (Msg.ForDialog << DialogMsg.OpenElementCreation)
            }
        |> 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)

-> (RenderConfig -> 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)
    )

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

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

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.

{ 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

type alias ActionConfig msg =

{ label : String

, icon : String -> Icon

, onClick : msg

}

ActionConfig assembles the required configuration for having an action bar at the bottom of the list.

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

withActionBar : ActionConfig 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

Width

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

Applies Element.width to the component.

ListView.withWidth
    (Element.fill |> Element.minimum 220)
    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/1.0.0