docs-ag-grid-row-column-cell.md

title	tags	created	modified
docs-ag-grid-row-column-cell	ag-grid docs	2020-08-24T09:16:58.432Z	2020-08-24T09:17:18.324Z

docs-ag-grid-row-column-cell

Column Definitions

• Each column in the grid is defined using a column definition.
• Columns are positioned in the grid according to the order the ColDefs are specified in the grid options.

var gridOptions = {
  columnDefs: [
    // put the three columns into a group
    {
      headerName: 'Group A',
      children: [
        { headerName: 'Athlete', field: 'athlete' },
        { headerName: 'Sport', field: 'sport' },
        { headerName: 'Age', field: 'age' }
      ]
    }
  ],

}

• The grid provides additional ways to help simplify and avoid duplication of column definitions.
  • defaultColDef: contains column properties all columns will inherit.
  • defaultColGroupDef: contains column group properties all column groups will inherit.
  • columnTypes: specific column types containing properties that column definitions can inherit.
    • Column Types are designed to work on Columns only, i.e. they won't be applied to Column Groups.
• Provided Column Types
  • rightAligned
  • numericColumn
• Each column generated by the grid is given a unique ID.
  • Parts of the Grid API use Column IDs (column identifiers).
  • If the user provides colId in the column definition, then this is used, otherwise the field is used.
  • If both colId and field , then colId gets preference.
  • If neither colId or field , then numeric is provided.
    • Then finally the ID ensured to be unique by appending '_n' where n is the first positive number that allows uniqueness
• Saving and Restoring Column State
  • Examples of column state include column visibility, width, row groups and values.
  • columnApi.getColumnState() : Returns the state of a particular column.
  • columnApi.setColumnState(state) : To set the state of a particular column.
  • The column state used by the above methods is an array of objects that mimic the colDefs which can be converted to and from JSON.
• Column Changes
  • When new columns are set, the grid will compare with current columns and work out which columns are old (to be removed), new (new columns created) or kept (columns that remain will keep their state including position, filter and sort).
  • Comparison of column definitions is done on 1) object reference comparison and 2) column ID eg colDef.colId .
  • If either the object reference matches, or the column ID matches, then the grid treats the columns as the same column.
• Immutable Columns
  • By default when new columns are loaded into the grid, the following properties are not used:
    • Column Order
    • width
    • Aggregation Function (colDef.aggFunc)
    • Pivot (colDef.pivot or colDef.pivotIndex)
    • Row Group (colDef.rowGroup or colDef.rowGroupIndex)
    • Pinned (colDef.pinned)
  • This is done on purpose to avoid unexpected behavior for the application user.

Column Headers

• Each column has a header at the top that typically displays the column name and has access to column features, such as sorting, filtering and a column menu.

Column Groups

• Grouping columns allows you to have multiple levels of columns in your header and the ability, if you want, to 'open and close' column groups to show and hide additional columns.
  • Grouping columns is done by providing the columns in a tree hierarchy to the grid.
  • There is no limit to the number of levels you can provide.
• Column Definitions vs Column Group Definitions
  • The children attribute is mandatory for groups and not applicable for columns.
  • If a definition has a children attribute, it is treated as a group. If it does not have a children attribute, it is treated as a column.
  • Most other attributes are not common across groups and columns (eg groupId is only used for groups).
    • If you provide attributes that are not applicable (eg you give a column a groupId ) they will be ignored.
• A group can have children initially hidden with columnGroupShow
• Pinned columns break groups.
  • So if you have a group with 10 columns, 4 of which are inside the pinned area, two groups will be created, one with 4 (pinned) and one with 6 (not pinned).

Column Sizing

Column Moving

Column Pinning

Column Spanning

Row Height

• By default, the grid will display rows with a height of 25px.

• You can change this for each row individually to give each row a different height.

• It is possible to set the row height based on the contents of the cells.

  • To do this, set autoHeight=true on each column where height should be calculated from
  • If multiple columns are marked with autoHeight=true , then the height of the largest column is used.

• The height is calculated once when the data is first given to the grid.

  • If the data changes, or the width of a column changes, then you may require the grid to calculate the height again by calling api.resetRowHeights() .

• Lazy Height Calculation

  • Auto height works by the grid creating an off-screen (not visible to the user) temporary row with all the auto height columns rendered into it.
  • The grid then measures the height of the temporary row.
  • Because DOM interaction is required for each row this can be an intensive process.
  • For this reason the grid only calculates the height of the row when it is needed - e.g. rows not yet visible due to vertical scrolling do not have their heights calculated,
  • similarly child rows of groups where the group is not open do not have their heights calculated until the group is opened and the child rows are visible.

• Because auto-height is a DOM intensive operation, consideration should be given for when and how to use it.

  • Only apply auto-height to columns where it makes sense.
  • For example, if you have many columns that do not require a variable height, then do not set them to auto-height.

• Setting the row height is done once for each row.

  • Once set, the grid will not ask you for the row height again.
  • You can change the row height after it is initially set using a combination of api.resetRowHeights() , rowNode.setRowHeight() and api.onRowHeightChanged() .

• Row height for pinned rows works exactly as for normal rows with one difference: it is not possible to dynamically change the height once set.

  • However this is easily solved by just setting the pinned row data again which resets the row heights.
  • Setting the data again is not a problem for pinned rows as it doesn't impact scroll position, filtering, sorting or group open/closed positions as it would with normal rows if the data was reset.

Full Width Rows

• Under normal operation, ag-Grid will render each row as a horizontal list of cells.
  • Each cell in the row will correspond to one column definition.
  • It is possible to switch this off and allow you to provide one component to span the entire width of the grid and not use columns.
  • This is useful if you want to embed a complex component inside the grid instead of rendering a list of cells.
  • This technique can be used for displaying panels of information.
• Full width rows were initially introduced into ag-Grid to support Master/Detail before the grid provided direct support for master/detail.
  • Now that master/detail is directly supported, the usefulness of full width is reduced.
• A fullWidth (full width) component takes up the entire width of the grid. A full width component:
  • is not impacted by horizontal scrolling.
  • is the width of the grid, regardless of what columns are present.
  • is not impacted by pinned sections of the grid, will span left and right pinned areas regardless.
  • does not participate in the navigation, rangeSelection (ag-Grid Enterprise) or contextMenu (ag-Grid Enterprise) of the main grid.

Row Spanning

Row Pinning

Row Animation

• Row animations occur after sorting, filtering, resizing height and expanding/collapsing a row group.
  • Each of these animations is turned OFF by default.
  • They are all turned on using the property animateRows=true .

Row Dragging

Cell Content

• Cell content with regards how values are provided into the cells.

  • Value Getter
    • Instead of specifying colDef.field , you can use colDef.valueGetter to provide a function for getting cell values.
    • This is more flexible than providing field values for specific cells.
  • Value Formatters
    • Use formatters to format values.
  • Expressions
    • Use strings instead of functions for value getters and formatters.
  • Reference Data
    • Reference data is used to display alternative values rather that what is in your data, eg you data could have USA but you want to display 'America'.

• value formatters are for text formatting and cell renderers are for when you want to include HTML markup and potentially functionality to the cell.

• Column Definition Expressions vs Functions

  • The advantage of functions is that they are easier to work with for you.
    • Functions will be treated by your IDE as functions and thus benefit from compile time checks, debugging e.t.c.
  • The advantage of expressions are:
    • They keep your column definitions as simple JSON objects (just strings, no functions) which makes them candidates for saving in offline storage (eg storing a report definition in a database).
    • They make the definitions more compact, thus may make your code more maintainable.

• A shortcoming of cell expression is that the expression belongs to the column and cannot be defined as part of the data, or in other words, the expression is for the entire column, it cannot be set to a particular cell.

• When you provide and expression to the grid, the grid converts the expression into a function for you and then executes the function

• Rendering Flow

  • If valueGetter is provided, it will be used, otherwise the field will be used.
  • If valueFormatter is provided, it will be used, otherwise the value is not formatted.
  • The cellRenderer , if provided, gets the result of the above.
    • The grid then either appends the HTML from the cellRenderer , or it just sets the cells textContent to the value.

Cell Rendering

• By default the grid renders values into the cells as strings.

• If you want something more complex, you use a cell renderer.

• The cell editor for a column is set via colDef.cellRenderer and can be any of the following types:

  • undefined/null: Grid renders the value as a string.
  • String: The name of a cell renderer component.
  • Class: Direct reference to a cell renderer component.
  • Function: A function that returns either an HTML string or DOM element for display.

• To build your own cell renderer, see the section Cell Rendering Components.

• Many Renderers One Column

  • It is also possible to use different renderers for different rows in the same column.
  • Typically an application might check the rows contents and choose a renderer accordingly.
  • To configure this, set colDef.cellRendererSelector to a function that returns the name of the component to be used as a renderer and optionally the custom params to be passed into it

Flashing Cells

• The grid can flash cells to highlight data changes.
• Flashing Cells vs Custom Cell Renderers
  • Flashing cells is a simple and quick way to visually show to the user that the data has changed.
  • It is also possible to have more intelligent animations by putting animations into custom Cell Renderers.
  • Cell Renderers have a refresh method that gets called when data changes, allowing custom animations to highlight data changes.

Cell Editing

• You configure cell editors as part of the column definition and can be one of the following:

  • undefined/null: The grid uses the default text cell editor.
  • string: The name of a cell renderer registered with the grid.
  • Class: Provide your own cell renderer component directly without registering.

• editing will start upon any of the following:

  • Edit Key Pressed: One of the following is pressed: Enter, F2, Backspace, Delete.
  • Printable Key Pressed: Any of the following characters
  • Mouse Double Click: If the mouse is double-clicked
  • api.startEditingCell() : If you call startEditingCell() on the grid API

• An editor can be in a popup or in cell.

• In Cell editing means the contents of the cell will be cleared and the editor will appear inside the cell.

  • The editor will be constrained to the boundaries of the cell, so if it is larger than the provided area it will be clipped.
  • When editing is finished, the editor will be removed and the renderer will be placed back inside the cell again.

• The popup will behave like a menu in that any mouse interaction outside of the popup will close the popup.

  • The popup will appear over the cell, however it will not change the contents of the cell.
  • Behind the popup the cell will remain intact until after editing is finished which will result in the cell being refreshed.
  • If you want your editor to appear in a popup (such as a dropdown list), then you can have it appear in a popup

• From a lifecycle and behavior point of view, 'in cell' and 'popup' have no impact on the editor.

  • You can create a cell editor and change this property and observe how your editor behaves in each way.
  • To have an editor appear in a popup, have the isPopup() method return true.
  • If you want editing to be done within a cell, either return false or don't provide this method at all.

• Value setters and value parsers are the inverse of value getters and formatters.

• Many Editors One Column

  • It is also possible to use different editors for different rows in the same column.
  • Typically an application might check the rows contents and choose an editor accordingly.
  • To configure this set colDef.cellEditorSelector to a function that returns the name of the component to be used as an editor and optionally the custom params to be passed into it.

Undo/Redo Edits

• Users can change the contents of cells through the following grid features:
  • Cell Editing
  • Copy/Paste
  • Fill Handle
• This Undo/Redo feature is designed to be a recovery mechanism for user editing mistakes.
  • Performing grid operations that change the row/column order, e.g. sorting, filtering and grouping, will clear the undo/redo stacks.