PaackEng / paack-ui / UI.Filter

The UI.Filter is a reusable dialog, hidden in a button, used for filtering the results of a list.

Common


type Filter msg

Holds the filter's visual element information.

Size


type FilterSize

Describes a compatible size.

withSize : FilterSize -> Filter msg -> Filter msg

Scale the component between the compatible sizes.

sizeMedium : FilterSize

Default size.

sizeExtraSmall : FilterSize

Smallest size.

withWidth : Element.Length -> Filter msg -> Filter msg

Sets the width with Element.

withAlignRight : Filter msg -> Filter msg

Aligns the filter to the right.

Rendering

renderElement : UI.RenderConfig.RenderConfig -> Filter msg -> Element msg

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

Pre-defined filters

There are the predefined filters, which have states and updates, and includes sorting buttons.

model =
    { someFilter =
        Filter.singleTextFilter Nothing .artist
            |> Filter.setItems [ example1, example2 ]
    , isFilterOpen = False
    }

type Msg
    = FilterOpen
    | FilterClose
    | FilterEdit Filter.FilterMsg

view renderConfig model =
    Filter.fromModel label
        Msg.FilterEdit
        model.someFilter
        |> Filter.renderElement renderConfig

Builders


type FilterModel msg item

Holds a pre-defined filter's current state.

fromModel : String -> (FilterMsg -> msg) -> FilterModel msg item -> Filter msg

Creates the visual component from the model of a pre-built filter.

fromModel
    label
    Msg.ForFilter
    model.someFilter

singleTextFilter : Maybe String -> (item -> String) -> FilterModel msg item

A pre-built, single text field filter.

singleTextField (Just "initial filtering value") .someStringField

multiTextFilter : List String -> (item -> String) -> FilterModel msg item

A pre-built filter, with multiple text fields.

multiTextField [] .someStringField

singleDateFilter : Time.Zone -> Maybe Time.Posix -> (item -> Time.Posix) -> FilterModel msg item

A pre-built filter, for a single date.

singleDateFilter timeZone (Just model.someInitialTime) .someTimeField

rangeDateFilter : Time.Zone -> Maybe Time.Posix -> Maybe Time.Posix -> (item -> Time.Posix) -> FilterModel msg item

A pre-built filter, for a range of date.

rangeDateFilter timeZone
    (Just model.someInitialBeginningTime)
    (Just model.someInitialEndingTime)
    .someTimeField

periodDateFilter : String -> Time.Zone -> Maybe Time.Posix -> Maybe Basics.Order -> (item -> Time.Posix) -> FilterModel msg item

A pre-built filter, for a period (before, on, or after) some date.

periodDateFilter "some-dom-id"
    timeZone
    (Just model.someInitialBeginningTime)
    (Just GT)
    .someTimeField

radioFilter : String -> List String -> Maybe Basics.Int -> (item -> Basics.Int -> Basics.Bool) -> FilterModel msg item

A pre-built filter, for a custom radio group.

radioFilter "some-dom-id"
    [ "Orange", "Strawberry", "Pineapple", "Watermelon" ]
    (Just 0)
    (\fruit selected -> fruitsIndex fruit == selected)


type FilterMsg

Contains a pre-defined filter's change.

update : (FilterMsg -> msg) -> FilterMsg -> FilterModel msg item -> ( FilterModel msg item, UI.Effects.Effects msg )

A classic update function.

setItems : List item -> FilterModel msg item -> FilterModel msg item

Feed the filter with items.

getItems : FilterModel msg item -> List item

Retrieve items, sorted and filtered.

Sorting

filterSorting model =
    Filter.sorting
        { sortAscendingMsg = Sort True
        , sortDescendingMsg = Sort False
        , clearSortingMsg = ClearSorting
        }
        |> Filter.withAppliedSorting Filter.sortingAscending
        |> Filter.withSortingPreview "A" "Z"


type FilterSorting msg

Describes the filter's sorting information.

withSorting : FilterSorting msg -> Filter msg -> Filter msg

Adds sorting buttons to the filter.

sorting : { sortAscendingMsg : msg, sortDescendingMsg : msg, clearSortingMsg : msg } -> FilterSorting msg

Builds a FilterSorting for custom sorting.

withSortingPreview : { smaller : String, larger : String } -> FilterSorting msg -> FilterSorting msg

Add example of the sorting order to the sorting buttons.


type FilterAppliedSorting

Describes the applied sorting state.

withAppliedSorting : FilterAppliedSorting -> FilterSorting msg -> FilterSorting msg

Sets the current sorting state.

sortingAscending : FilterAppliedSorting

For when the current sorting is ascending.

sortingDescending : FilterAppliedSorting

For when the current sorting is descending.

notSorting : FilterAppliedSorting

For when not sorting.

Custom filters

There is also the possibility to create a custom filter, where you set the sorting, the filter fields/body, and the avaiable buttons.

model =
    { etc | isFilterOpen = False }

type Msg
    = Sort Bool
    | ClearSorting
    | Etc -- ...

view renderConfig model =
    Filter.customFilter label
        { openMsg = openMsg, closeMsg = closeMsg, isOpen = model.isFilterOpen }
        |> Filter.withSorting (filterSorting model)
        |> Filter.withBody (filterBody renderConfig model)
        |> Filter.withButtons (filterButtons renderConfig model)
        |> Filter.withAppliedHeader clearMsg labelWhenApplied
        |> Filter.renderElement renderConfig

Builder

customFilter : String -> { openMsg : msg, closeMsg : msg, isOpen : Basics.Bool } -> Filter msg

Builds a custom filter, where you create the messages and treat the states.

Customizer

withBody : List (Element msg) -> Filter msg -> Filter msg

Sets the content of the filter's dialog when open.

withButtons : List (UI.Button.Button msg) -> Filter msg -> Filter msg

Sets the buttons at the bottom of the filter's dialog when open.

withBodyHeight : Basics.Int -> Filter msg -> Filter msg

Limits the vertical size of the filter's body

withCalendarBody : UI.DatePicker.DatePicker msg -> Filter msg -> Filter msg

Sets the content of the filter's dialog as a date-picker.

Header when filter applied


type FilterAppliedHeader msg

Describes the applied filter state.

withAppliedHeader : Maybe (FilterAppliedHeader msg) -> Filter msg -> Filter msg

Sets the closed filter visually different when with filtering applied.

appliedHeader : String -> msg -> FilterAppliedHeader msg

Sets a preview of how many items (or which ones) were selected for filtering, with a button to fastly clear the filtering.