mercurymedia / elm-ag-grid / AgGrid

AgGrid integration for elm.

Data Types


type Aggregation
    = AvgAggregation
    | CountAggregation
    | CustomAggregation String
    | FirstAggregation
    | LastAggregation
    | MaxAggregation
    | MinAggregation
    | NoAggregation
    | SumAggregation

Variants to aggregate values for a grouped column.


type CellEditor
    = AppEditor ({ componentName : String, componentParams : Maybe Json.Encode.Value })
    | PredefinedEditor String
    | DefaultEditor

CellEditor


type alias ColumnDef dataType =
{ field : String
, renderer : Renderer dataType
, headerName : String
, settings : ColumnSettings 
}

Column definition.

Requires field, renderer, headerName, and settings to be defined for each column.

Example

let
    defaultSettings =
        AgGrid.defaultSettings
in
[ { field = "id"
  , renderer = IntRenderer .id
  , headerName = "Id"
  , settings = defaultSettings
  }
, { field = "title"
  , renderer = StringRenderer .title
  , headerName = "Product"
  , settings =
        { defaultSettings
            | editable = False
            , pinned = AgGrid.PinnedToLeft
        }
  }
]


type alias ColumnSettings =
{ aggFunc : Aggregation
, allowedAggFuncs : Maybe (List Aggregation)
, autoHeight : Basics.Bool
, defaultAggFunc : Aggregation
, autoHeaderHeight : Basics.Bool
, cellClassRules : List ClassRule
, checkboxSelection : Basics.Bool
, customCellEditor : CellEditor
, editable : Expression.Eval Basics.Bool
, enablePivot : Basics.Bool
, enableRowGroup : Basics.Bool
, enableValue : Basics.Bool
, filter : FilterType
, filterParams : { buttons : List FilterButtonType
, closeOnApply : Basics.Bool }
, filterValueGetter : Maybe String
, flex : Maybe Basics.Int
, floatingFilter : Basics.Bool
, headerCheckboxSelection : Basics.Bool
, hide : Basics.Bool
, lockPosition : LockPosition
, minWidth : Maybe Basics.Int
, pinned : PinningType
, lockPinned : Basics.Bool
, pivot : Basics.Bool
, pivotIndex : Maybe Basics.Int
, resizable : Basics.Bool
, rowGroup : Basics.Bool
, rowGroupIndex : Maybe Basics.Int
, showDisabledCheckboxes : Basics.Bool
, sortable : Basics.Bool
, sort : Sorting
, sortIndex : Maybe Basics.Int
, suppressColumnsToolPanel : Basics.Bool
, suppressFiltersToolPanel : Basics.Bool
, suppressMenu : Basics.Bool
, suppressSizeToFit : Basics.Bool
, valueFormatter : Maybe String
, valueGetter : Maybe String
, valueParser : Maybe String
, valueSetter : Maybe String
, width : Maybe Basics.Float
, wrapHeaderText : Basics.Bool
, wrapText : Basics.Bool 
}

Column configuration settings.


type EventType
    = ColumnMoved
    | ColumnResized
    | ColumnVisible
    | FilterChanged
    | GridColumnsChanged
    | SortChanged
    | ColumnPinned
    | ColumnRowGroupChanged
    | ColumnValueChanged
    | ResetColumns

Possible variants of callbacks that can lead to a certain change.


type FilterType
    = DefaultFilter
    | DateFilter
    | NumberFilter
    | StringFilter
    | SetFilter
    | NoFilter

Possible filter options for columns.


type LockPosition
    = LockToLeft
    | LockToRight
    | NoPositionLock

Lock a column to position to left or right to always have this column displayed in that position.

Or can be configured to not lock in one position and move the column freely.


type PinningType
    = PinnedToLeft
    | PinnedToRight
    | Unpinned

Possible options to pin a column.


type Renderer dataType
    = AppRenderer ({ componentName : String, componentParams : Maybe Json.Encode.Value }) (dataType -> String)
    | BoolRenderer (dataType -> Basics.Bool)
    | CurrencyRenderer ({ countryCode : String, currency : String }) (dataType -> Maybe String)
    | DecimalRenderer ({ countryCode : String, decimalPlaces : Basics.Int }) (dataType -> Maybe String)
    | FloatRenderer (dataType -> Basics.Float)
    | GroupRenderer (dataType -> String)
    | IntRenderer (dataType -> Basics.Int)
    | MaybeFloatRenderer (dataType -> Maybe Basics.Float)
    | MaybeIntRenderer (dataType -> Maybe Basics.Int)
    | MaybeStringRenderer (dataType -> Maybe String)
    | DateRenderer (dataType -> String)
    | NoRenderer
    | PercentRenderer ({ countryCode : String, decimalPlaces : Basics.Int }) (dataType -> Maybe String)
    | SelectionRenderer (dataType -> String) (List String)
    | StringRenderer (dataType -> String)

The Renderer expresses how the data is retrieved from the list of data and rendered to the view.

The editor and renderer views in the table depend on the type. For example, a BoolRenderer is displayed and can be edited with a checkbox in the table.

The Renderer may need a function to read the value for the cell from the records.

Example

If the data is list of Product, the Renderer to display the column for the title might be defined as:

type alias Product =
    { title : String }

-- Column definitions:
[{ renderer = StringRenderer .title, ... }]


type RowGroupPanelVisibility
    = AlwaysVisible
    | NeverVisible
    | OnlyWhenGroupingVisible

Row Group Panel allows the users to control which columns the rows are grouped by.


type RowSelection
    = MultipleRowSelection
    | NoRowSelection
    | SingleRowSelection

Type of row selection, set to either SingleRowSelection or MultipleRowSelection to enable selection.


type Sorting
    = SortAscending
    | SortDescending
    | NoSorting

Possible pre-configured column sorting.


type alias StateChange type_ =
{ event : { type_ : EventType }
, states : type_ 
}

Change event data for a table state changes.


type alias CsvExportParams =
{ fileName : String
, columnKeys : List String 
}

Possible configuration for the CSV export.


type alias ExcelExportParams =
{ fileName : String
, columnKeys : List String 
}

Possible configuration for the Excel export.

Grid


type alias GridConfig dataType =
{ autoGroupColumnDef : { cellRendererParams : { suppressCount : Basics.Bool
, checkbox : Basics.Bool }
, headerName : Maybe String
, minWidth : Maybe Basics.Int
, resizable : Basics.Bool
, pinned : PinningType }
, autoSizeColumns : Basics.Bool
, cacheQuickFilter : Basics.Bool
, columnStates : List ColumnState
, columnHoverHighlight : Basics.Bool
, contextMenu : Maybe ContextMenu
, csvExport : Maybe CsvExportParams
, detailRenderer : Maybe { componentName : String
, componentParams : Maybe Json.Encode.Value
, rowHeight : Maybe Basics.Int }
, disableResizeOnScroll : Basics.Bool
, excelExport : Maybe ExcelExportParams
, filterStates : Dict String FilterState
, groupDefaultExpanded : Basics.Int
, groupIncludeFooter : Basics.Bool
, groupIncludeTotalFooter : Basics.Bool
, groupSelectsChildren : Basics.Bool
, isRowSelectable : dataType -> Basics.Bool
, maintainColumnOrder : Basics.Bool
, pagination : Basics.Bool
, quickFilterText : String
, rowGroupPanelShow : RowGroupPanelVisibility
, rowHeight : Maybe Basics.Int
, rowId : Maybe (dataType -> String)
, rowMultiSelectWithClick : Basics.Bool
, rowSelection : RowSelection
, rowClassRules : List ClassRule
, rowHoverHighlight : Basics.Bool
, selectedIds : List String
, sideBar : Sidebar
, size : String
, sizeToFitAfterFirstDataRendered : Basics.Bool
, stopEditingWhenCellsLoseFocus : Basics.Bool
, suppressAggFuncInHeader : Basics.Bool
, suppressMenuHide : Basics.Bool
, suppressRowClickSelection : Basics.Bool
, suppressRowDeselection : Basics.Bool
, themeClasses : Maybe String 
}

Grid configurations.

grid : GridConfig dataType -> List (Html.Attribute msg) -> List (ColumnDef dataType) -> List dataType -> Html msg

Defines the data grid.

Example

let
    gridConfig =
        AgGrid.defaultGridConfig
            |> (\config -> { config | themeClasses = Just "ag-theme-balham ag-basic" })

    events =
        [ onCellChanged rowDecoder UpdateProduct ]

    defaultSettings =
        AgGrid.defaultSettings
            |> (\settings -> { settings | editable = True })

    columns =
        [ { field = "id"
          , renderer = IntRenderer .id
          , headerName = "Id"
          , settings = { defaultSettings | enablePivot = False }
          }
        , { field = "title"
          , renderer = StringRenderer .title
          , headerName = "Product"
          , settings = { defaultSettings | filter = StringFilter }
          }
        ]

    data =
        model.products
in
grid gridConfig events columns data

Defaults

defaultGridConfig : GridConfig dataType

Retrieve a GridConfig record with default configuration.

Can be used when implementing the grid.

    { autoGroupColumnDef =
        { cellRendererParams =
            { suppressCount = False
            , checkbox = False
            }
        , headerName = Nothing
        , minWidth = Nothing
        , resizable = True
        }
    , autoSizeColumns = False
    , cacheQuickFilter = False
    , columnStates = []
    , columnHoverHighlight = False
    , detailRenderer = Nothing
    , disableResizeOnScroll = False
    , filterStates = Dict.empty
    , groupDefaultExpanded = 0
    , groupIncludeFooter = False
    , groupIncludeTotalFooter = False
    , groupSelectsChildren = False
    , isRowSelectable = always True
    , pagination = False
    , quickFilterText = ""
    , rowGroupPanelShow = NeverVisible
    , rowHeight = Nothing
    , rowHoverHighlight = True
    , rowMultiSelectWithClick = False
    , rowSelection = MultipleRowSelection
    , selectedIds = []
    , sideBar = defaultSidebar
    , size = "65vh"
    , sizeToFitAfterFirstDataRendered = True
    , stopEditingWhenCellsLoseFocus = True
    , suppressAggFuncInHeader = False
    , suppressMenuHide = False
    , suppressRowClickSelection = False
    , suppressRowDeselection = False
    , themeClasses = Nothing
    }

defaultSettings : ColumnSettings

Retrieve a ColumnSettings record with default configuration.

Can be used when implementing column configurations for the table.

Default column settings:

{ aggFunc = NoAggregation
, allowedAggFuncs = Nothing
, autoHeight = False
, defaultAggFunc = SumAggregation
, autoHeaderHeight = False
, cellClassRules = []
, checkboxSelection = False
, customCellEditor = DefaultEditor
, editable = Const False
, enablePivot = True
, enableRowGroup = True
, enableValue = True
, filter = DefaultFilter
, filterParams =
    { buttons = [ ClearButton ]
    , closeOnApply = False
    }
, filterValueGetter = Nothing
, flex = Nothing
, floatingFilter = False
, headerCheckboxSelection = False
, hide = False
, lockPinned = False
, lockPosition = NoPositionLock
, minWidth = Nothing
, pinned = Unpinned
, pivot = False
, pivotIndex = Nothing
, resizable = True
, rowGroup = False
, rowGroupIndex = Nothing
, showDisabledCheckboxes = False
, sortable = True
, sort = NoSorting
, sortIndex = Nothing
, suppressColumnsToolPanel = False
, suppressFiltersToolPanel = False
, suppressMenu = False
, suppressSizeToFit = True
, valueFormatter = Nothing
, valueGetter = Nothing
, valueParser = Nothing
, valueSetter = Nothing
, width = Nothing
, wrapHeaderText = False
, wrapText = False
}

Events

onCellChanged : Json.Decode.Decoder dataType -> (Result Json.Decode.Error dataType -> msg) -> Html.Attribute msg

Detect change events on cells.

Decodes the changed row according to the provided dataDecoder and passes the result to the message toMsg.

Handles the cellValueChanged event from Ag Grid.

onCellDoubleClicked : Json.Decode.Decoder dataType -> (( Result Json.Decode.Error dataType, String ) -> msg) -> Html.Attribute msg

Detect doubleclick events on cells.

Decodes the row of the clicked cell according to the provided dataDecoder and the field name of the clicked cells as tuple and passes the result to the message toMsg.

Handles the cellDoubleClicked event from Ag Grid.

onCellClicked : Json.Decode.Decoder dataType -> (( Result Json.Decode.Error dataType, String ) -> msg) -> Html.Attribute msg

Detect click events on cells.

Decodes the row of the clicked cell according to the provided dataDecoder and the field name of the clicked cells as tuple and passes the result to the message toMsg.

Handles the cellClicked event from Ag Grid.

onSelectionChange : Json.Decode.Decoder node -> (Result Json.Decode.Error (List node) -> msg) -> Html.Attribute msg

Detect selection change events.

Sends the current selection of nodes to the toMsg.

onContextMenu : Json.Decode.Decoder dataType -> (( Result Json.Decode.Error dataType, String ) -> msg) -> Html.Attribute msg

Detect click on custom context menu actions

ColumnState


type alias ColumnState =
{ aggFunc : Maybe String
, colId : String
, flex : Maybe Basics.Int
, hide : Maybe Basics.Bool
, pinned : Maybe String
, pivot : Maybe Basics.Bool
, pivotIndex : Maybe Basics.Int
, rowGroup : Maybe Basics.Bool
, rowGroupIndex : Maybe Basics.Int
, sort : Maybe String
, sortIndex : Maybe Basics.Int
, width : Basics.Float 
}

Column state.

Can be used to evaluate the current table state whenever a change to the structure of the table happens (e.g. sorting, order, sizing, or visiblity of columns changed).

Might be used to persist the table state of the user to the localstorage or some other external storage. Column states can be restored through the columnState on the GridConfig.

onColumnStateChanged : (StateChange (List ColumnState) -> msg) -> Html.Attribute msg

Detect change events to the table structure (e.g. sorting or moved columns).

Decodes the EventType of the change and the current states of the grid columns and passes the result to the toMsg.

columnStatesDecoder : Json.Decode.Decoder (List ColumnState)

Decoder for the current column states.

Can be used to retrieve and decode the column states from an external storage.

columnStatesEncoder : List ColumnState -> Json.Encode.Value

Encode a collection of ColumnState.

Can be used to persist the current list of ColumnState for the grid to an external storage.

applyColumnState : GridConfig dataType -> List (ColumnDef dataType) -> List (ColumnDef dataType)

Apply the column state from the GridConfig to the given ColumnDefs.

The values from the cache overwrite the values on the ColumnDef. The order is also according to the order in the column state. New columns, that don't exist in the column state, are appended to the end.

This function is mainly exposed to allow unit-testing, as this is automatically applied to ColumnDefs passed to the grid.

FilterState


type FilterState
    = TextFilterState TextFilterAttrs
    | NumberFilterState NumberFilterAttrs
    | DateFilterState DateFilterAttrs
    | SetFilterState SetFilterAttrs

Filter state.

Can be used to evaluate the current filter configuration whenever a filter on a column gets changed.

Might be used to persist the filters applied to the table for the users to the localstorage or some other external storage. Filter states can be restored through the filterState on the GridConfig.

AG Grid reference: https://www.ag-grid.com/javascript-data-grid/filtering/#column-filter-types

onFilterStateChanged : (StateChange (Dict String FilterState) -> msg) -> Html.Attribute msg

Detect change events to the table filters.

Decodes the EventType of the change and the filter configuration of the grid columns and passes the result to the toMsg.

filterStatesEncoder : Dict String FilterState -> Json.Encode.Value

Encode a collection of FilterState.

Can be used to persist the current collection of FilterState for the grid to an external storage.

filterStatesDecoder : Json.Decode.Decoder (Dict String FilterState)

Decoder for the filter states.

Can be used to retrieve and decode the filter states from an external storage.

Sidebar


type alias Sidebar =
{ panels : List SidebarType
, defaultToolPanel : Maybe SidebarType
, position : SidebarPosition 
}

Sidebar configuration.


type SidebarType
    = ColumnSidebar
    | FilterSidebar

Possible options for displayed sidebars.


type SidebarPosition
    = SidebarLeft
    | SidebarRight

Position for the sidebar.

defaultSidebar : Sidebar

Retrieve a Sidebar with default configuration.

Can be used to ease the sidebar configuration.

    { panels = []
    , defaultToolPanel = Nothing
    , position = SidebarRight
    }

Type parser

aggregationToString : Aggregation -> Maybe String

Stringify an Aggregation.

This matches the configuration for AgGrid and equals the value retrieved from the ColumnState. Further, it can be used for external communication if necessary.

pinningTypeToString : PinningType -> Maybe String

Stringify a PinningType.

This matches the configuration for AgGrid and equals the value retrieved from the ColumnState. Further, it can be used for external communication if necessary.

sortingToString : Sorting -> Maybe String

Stringify the Sorting.

This matches the configuration for AgGrid and equals the value retrieved from the ColumnState. Further, it can be used for external communication if necessary.

toAggregation : Maybe String -> Aggregation

Parse a string to an Aggregation.

This can be used in combination with the value on the ColumnState. Further, it can be used for external communication if necessary.

toPinningType : Maybe String -> PinningType

Parse a string to a PinningType.

This can be used in combination with the value on the ColumnState. Further, it can be used for external communication if necessary.

toSorting : Maybe String -> Sorting

Parse a string to the Sorting type.

This can be used in combination with the value on the ColumnState. Further, it can be used for external communication if necessary.