ipyaggrid

https://widgetti.github.io/ipyaggrid
Admin
ipyaggrid brings the power of ag-Grid to Jupyter notebooks, allowing you to display pandas...
Tokens:18,699
Snippets:64
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Start Jupyter Notebook Server

Source: https://widgetti.github.io/ipyaggrid/dev/dev_install

Launches the Jupyter Notebook server, which can be used to open and run notebooks. The `--watch` flag enables auto-rebuilding of JavaScript assets upon changes.

```shell
# launch notebook server and open browser to the classic file system
$ jupyter notebook

# launch notebook server and open browser jupyterlab
$ jupyter lab --watch # auto rebuild
```

--------------------------------

### Install ipyaggrid Dependencies

Source: https://widgetti.github.io/ipyaggrid/dev/dev_install

Installs necessary Python packages for ipyaggrid development, including 'notebook' and requirements from the project's file.

```shell
(dev-ipyaggrid) $ pip install notebook
(dev-ipyaggrid) $ pip install -r ipyaggrid/requirements.txt
```

--------------------------------

### Clone ipyaggrid Repository

Source: https://widgetti.github.io/ipyaggrid/dev/dev_install

Clones the ipyaggrid project from GitLab and navigates into the project directory.

```shell
git clone https://gitlab.com/DGothrek/ipyaggrid
cd ipyaggrid
```

--------------------------------

### ipyaggrid Simple Example with Custom Buttons

Source: https://widgetti.github.io/ipyaggrid/guide/customize

Provides a comprehensive example of setting up ipyaggrid with column definitions, grid options, and multiple custom menu buttons. This includes defining grid behavior like column resizing, filtering, sorting, and adding custom actions to buttons.

```python
column_defs = [{'field':'origin', 'headerName': 'Origin'},
                  {'field':'make', 'headerName': 'Make'},
                  {'field':'carName', 'headerName':'Model'},
                  {'field':'price', 'headerName': 'Price'}]

grid_options = {
    'enableColResize': True,
    'columnDefs': column_defs,
    'enableFilter':True,
    'enableSorting':True,
    'animateRows':True,
    'groupMultiAutoColumn': True,
};

g = Grid(grid_data = cars,
            quick_filter=True,
            show_toggle_edit=True,
            show_toggle_delete=True,
            export_excel=True,
            export_csv=True,
            grid_options=grid_options,
            menu={'buttons':
                  [
                      {'name':'Log foo 1', 'action':'console.log("foo");'},
                      {'name':'Log bar 1', 'action':'console.log("bar");'},
                      {'name':'Log foo 2', 'action':'console.log("foo");'},
                      {'name':'Log foo 3', 'action':'console.log("foo");'},
                      {'name':'Log foo 4', 'action':'console.log("foo");'},
                  ],
                 },
            export_mode="buttons",
            theme='ag-theme-balham')
g
```

--------------------------------

### Install ipyaggrid for JupyterLab

Source: https://widgetti.github.io/ipyaggrid/guide/install

Installs the ipyaggrid package via pip and then installs the corresponding JupyterLab extension. It also includes a command to ensure the core JupyterLab manager extension is installed.

```shell
$ pip install ipyaggrid
$ jupyter labextension install ipyaggrid

# if not already installed
$ jupyter labextension install @jupyter-widgets/jupyterlab-manager
```

--------------------------------

### Install JupyterLab and Node.js

Source: https://widgetti.github.io/ipyaggrid/dev/dev_install

Installs JupyterLab and a compatible Node.js version from conda-forge, required for JupyterLab development workflows.

```shell
# node from conda forge for a compatible version
(dev-ipyaggrid) $ conda install jupyterlab nodejs -c conda-forge
```

--------------------------------

### Install ipyaggrid for Classic Notebook

Source: https://widgetti.github.io/ipyaggrid/guide/install

Installs the ipyaggrid package using pip and enables the necessary Jupyter nbextension for classic notebook environments. Assumes a notebook version less than 5.3.

```shell
$ pip install ipyaggrid

# if notebook<5.3 - but why would you not upgrade ??
$ jupyter nbextension enable --py --sys-prefix ipyaggrid
```

--------------------------------

### List JupyterLab Paths

Source: https://widgetti.github.io/ipyaggrid/dev/dev_install

Shows the application directory, user settings directory, and workspaces directory for JupyterLab.

```shell
# list jupyterlab folders
jupyter lab path
```

--------------------------------

### Build ipyaggrid Javascript Modules

Source: https://widgetti.github.io/ipyaggrid/dev/dev_install

Installs Node.js dependencies using npm ci and builds the JupyterLab extension for ipyaggrid's JavaScript components.

```shell
# from repo top folder

# build ipywidget js
$ cd ipyaggrid/js
$ npm ci
$ npm run build:labextension
```

--------------------------------

### Elaborate ipyaggrid Example with Menu Customization

Source: https://widgetti.github.io/ipyaggrid/guide/customize

This example demonstrates creating an ipyaggrid grid with extensive menu customization. It includes defining column definitions, grid options, and configuring a custom menu with buttons, input fields, and specific CSS for menu elements. JavaScript actions are embedded for button clicks.

```python
column_defs = [{'field':'origin', 'headerName': 'Origin'},
                  {'field':'make', 'headerName': 'Make'},
                  {'field':'carName', 'headerName':'Model'},
                  {'field':'price', 'headerName': 'Price'}]

grid_options = {
    'enableColResize': True,
    'columnDefs': column_defs,
    'enableFilter':True,
    'enableSorting':True,
    'animateRows':True,
    'groupMultiAutoColumn': True,
};

g = Grid(grid_data = cars,
            quick_filter=True,
            show_toggle_edit=True,
            show_toggle_delete=True,
            export_excel=True,
            export_csv=True,
            grid_options=grid_options,
            menu={'buttons':
                  [
                      {'name':'Log foo 1', 'action':'console.log("foo");'},
                      {'name':'Log bar 1', 'action':'console.log("bar");'},
                      {'name':'Log foo 2', 'action':'console.log("foo");'},
                      {'name':'Export to Excel', 'custom_css':{ 
                          'background':'lightgrey',
                          'border':'solid darkgrey 1px',
                          'border-radius': '10px'}
                      },
                      {'name':'Export to CSV', 'custom_css':{
                          'background':'lightgrey',
                          'border':'solid darkgrey 1px',
                          'border-radius': '10px'}
                      },
                      {'name':'Export Grid', 'custom_css':{
                          'background':'lightgrey',
                          'border':'solid darkgrey 1px',
                          'border-radius': '10px'}
                      },
                      {'name':'Log foo 3', 'action':'console.log("foo");'},
                      {'name':'Log foo 4', 'action':'console.log("foo");'},
                      {'name':'Log foo 5', 'action':'console.log("foo");'},
                  ],
                  'inputs':[
                      {'name':'Quick Filter', 'flex_css':
                       {'width':'100px',
                        'border-radius':'10px'}
                      }
                  ],
                  'button_default_css':
                  {
                      'color':'slateblue',
                      'border':'solid darkgrey 1px',
                      'border-radius': '10px',
                  },
                  'menu_div_css':
                  {
                      'flex-wrap':'nowrap',
                      'justify-content':'space-between',
                      'border':'solid 1px black',
                      'border-radius':'5px',
                      'align-items':'stretch'
                  },
                  'input_div_css':
                  {
                      'flex-direction':'column',
                      'align-items':'flex-end',
                      'border':'solid 1px red',
                      'border-radius':'5px',
                      'margin':'5px'
                  },
                  'button_div_css':
                  {
                      'flex-direction':'row-reverse',
                      'flex-wrap': 'wrap',
                      'flex-basis':'485px',
                      'border':'solid 1px darkred',
                      'border-radius':'5px',
                      'margin':'5px'
                  }
                 },
            export_mode="buttons",
            theme='ag-theme-balham')
g
```

```javascript
console.log("foo");
```

```javascript
console.log("bar");
```

--------------------------------

### Install Jupyter Notebook Extension

Source: https://widgetti.github.io/ipyaggrid/dev/dev_install

Installs the ipyaggrid Jupyter Notebook extension using the jupyter nbextension command. It uses a symlink for development purposes, pointing to the static files within the package.

```shell
$ jupyter nbextension install --py --symlink --sys-prefix ipyaggrid
```

--------------------------------

### List Jupyter Configuration Folders (Classic Notebook)

Source: https://widgetti.github.io/ipyaggrid/dev/dev_install

Displays the paths where Jupyter looks for configuration and data files in a classic notebook environment.

```shell
# list jupyter folders
jupyter --paths
```

--------------------------------

### Install Python Package

Source: https://widgetti.github.io/ipyaggrid/dev/dev_install

Installs the ipyaggrid Python package in development mode using pip. This command is typically run after navigating to the project's root directory.

```shell
cd ..
$ pip install -e .
```

--------------------------------

### Install JupyterLab Extension

Source: https://widgetti.github.io/ipyaggrid/dev/dev_install

Links the ipyaggrid JupyterLab extension, making it available in the JupyterLab environment. It requires the JupyterLab manager extension to be installed separately.

```shell
$ jupyter labextension link ipyaggrid/js
# Ensure JupyterLab manager is installed:
# $ jupyter labextension install @jupyter-widgets/jupyterlab-manager
```

--------------------------------

### Build VS Code Workspace for Classic Notebook Folders

Source: https://widgetti.github.io/ipyaggrid/dev/dev_install

Generates a '.code-workspace' file to open ipyaggrid extension folders in VS Code for classic notebook development.

```shell
# build .code-workspace file
python util/build_code_workspace_notebook.py
code ipyaggrid-ext-folders-notebook.code-workspace
```

--------------------------------

### Build VS Code Workspace for JupyterLab Folders

Source: https://widgetti.github.io/ipyaggrid/dev/dev_install

Generates a '.code-workspace' file to open ipyaggrid extension folders in VS Code for JupyterLab development.

```shell
# build .code-workspace file
python util/build_code_workspace_jupyterlab.py
code ipyaggrid-ext-folders-jupyterlab.code-workspace
```

--------------------------------

### Create Simple ag-Grid with JavaScript

Source: https://widgetti.github.io/ipyaggrid/overview/ag-Grid

Demonstrates the basic setup for ag-Grid, a JavaScript data grid library. It includes defining row data, column definitions, grid options, and initializing the grid in a DOM element. The grid API is accessible after initialization for further manipulation.

```javascript
// Define the rows of the data to display
var rowDat = [
  { make: "Toyota", model: "Celica", price: 35000 },
  { make: "Ford", model: "Mondeo", price: 32000 },
  { make: "Porsche", model: "Boxter", price: 72000 }
];

// Set up the columns names
var columnDef = [
  { headerName: "Make", field: "make" },
  { headerName: "Model", field: "model" },
  { headerName: "Price", field: "price" }
];

// Add custom parameters
var gridOptions = {
  columnDefs: columnDef,
  // A bunch of different options.
  enableFilter: true,
  defaultColDef: {
    editable: true
  },
  rowSelection: "multiple",
  enableSorting: true
};

// Use an existing DOM element
var gridDiv = document.querySelector("#myGrid");
new agGrid.Grid(gridDiv, gridOptions);

// API is available
gridOptions.api.setRowData(rowDat);

```

--------------------------------

### Check Notebook Extensions Status

Source: https://widgetti.github.io/ipyaggrid/dev/dev_install

Lists the status of all installed Jupyter Notebook extensions. This helps verify if the ipyaggrid extension is correctly enabled and validated.

```shell
# notebook extensions status
$ jupyter nbextension list
```

--------------------------------

### Check JupyterLab Extensions Status

Source: https://widgetti.github.io/ipyaggrid/dev/dev_install

Lists the status of all installed JupyterLab extensions. This command verifies if the ipyaggrid extension is recognized and enabled within JupyterLab.

```shell
# jupyterlab extensions status
$ jupyter labextension list
```

--------------------------------

### Create and Activate Conda Environment

Source: https://widgetti.github.io/ipyaggrid/dev/dev_install

Creates a new Conda environment named 'dev-ipyaggrid' with Python 3 and activates it. This isolates development dependencies.

```shell
# create conda env
conda create -n dev-ipyaggrid python=3
# activate env (without source for Windows)
source activate dev-ipyaggrid
```

--------------------------------

### View Notebook Extension Configuration

Source: https://widgetti.github.io/ipyaggrid/dev/dev_install

Displays the content of the Jupyter Notebook configuration file, showing which extensions are loaded. This is useful for debugging extension loading issues.

```shell
$ cat /usr/local/anaconda3/envs/dev-ipyaggrid/etc/jupyter/nbconfig/notebook.json
```

--------------------------------

### ipyaggrid Grid Constructor Parameters (APIDOC)

Source: https://widgetti.github.io/ipyaggrid/guide/create

Defines the parameters accepted by the ipyaggrid.Grid constructor for configuring widget behavior and grid setup. These parameters control aspects like dimensions, themes, data handling, and interactive features.

```APIDOC
ipyaggrid.Grid Constructor Parameters:

# Widget options
- width : int or str
  Specifies the width of the grid widget.
- height : int
  Specifies the height of the grid widget.
- center : bool
  If True, centers the widget.
- theme : str
  The ag-Grid theme to apply (e.g., 'alpine', 'balham', 'material').

# Grid setup
- grid_data : list or pandas dataframe
  The data to be displayed in the grid. Can be a list of dictionaries or a pandas DataFrame.
- grid_options : dict
  A dictionary containing ag-Grid specific configurations, such as column definitions, row data, etc. Refer to ag-Grid documentation for details.
- grid_options_multi : list of dict
  Allows for multiple sets of grid options, potentially for advanced configurations.
- columns_fit : str
  Controls how columns are sized to fit the grid width (e.g., 'autoSize', 'sizeToFit').
- index : bool
  If True, includes the DataFrame index as a column.
- keep_multiindex : bool
  If True, preserves multi-index structure when converting to data for the grid.
- compress_data : bool
  If True, compresses the data sent to the frontend for performance.

# Menu options
- quick_filter : bool
  Enables a quick filter input box above the grid.
- export_csv : bool
  Enables a button to export the grid data to CSV.
- export_excel : bool
  Enables a button to export the grid data to Excel.
- show_toggle_delete : bool
  Shows a toggle button for deleting rows.
- show_toggle_edit : bool
  Shows a toggle button for editing rows.
- paste_from_excel : bool
  Enables pasting data from the clipboard (e.g., from Excel).
- export_mode : str
  Specifies the mode for exporting data.
- export_to_df : bool
  If True, allows exporting the grid data back to a pandas DataFrame.
- hide_grid : bool
  If True, hides the grid interface.

# Other options
- license : str
  Specifies the ag-Grid license type ('enterprise' or 'community'). Defaults to 'enterprise' if not specified, but can be set to 'community' to use the community version.
```

--------------------------------

### Uninstall ipyaggrid from JupyterLab

Source: https://widgetti.github.io/ipyaggrid/guide/install

Uninstalls the ipyaggrid JupyterLab extension and then removes the ipyaggrid Python package using pip.

```shell
$ jupyter labextension uninstall ipyaggrid
$ pip uninstall ipyaggrid
```

--------------------------------

### Node.js Package Publishing

Source: https://widgetti.github.io/ipyaggrid/dev/publish

Instructions for building the JavaScript files and publishing the Node.js package to npmjs.org. This includes installing dependencies, building the extension, logging into npm, and publishing the package with public access.

```shell
# starting from repo top folder
# make sure the version in js/package.json is correct

# build notebook extension javascript
$ cd js
$ npm ci

# test run to see what you will publish
# npm pack

# login npm if necessary
npm login

# publish npm package to npmjs.org - using ~/.npmrc
$ npm publish --access=public
# if you made a mistake you can unpublish in the first 24h
```

--------------------------------

### Enable Jupyter Notebook Extension

Source: https://widgetti.github.io/ipyaggrid/dev/dev_install

Enables the ipyaggrid Jupyter Notebook extension for use within the Jupyter environment. This command ensures the extension is loaded automatically when notebooks are opened.

```shell
$ jupyter nbextension enable --py --sys-prefix ipyaggrid
```

--------------------------------

### Install ipyaggrid using pip

Source: https://widgetti.github.io/ipyaggrid/index

This snippet shows how to install the ipyaggrid library for Jupyter notebooks. It requires a Jupyter notebook version of 5.3 or later and is installed using pip.

```bash
# for notebook >= 5.3
$ pip install ipyaggrid
```

--------------------------------

### ipyaggrid Customization Parameters

Source: https://widgetti.github.io/ipyaggrid/guide/customize

Details the parameters available for customizing the ipyaggrid widget, including menu structure, CSS rules, and JavaScript execution.

```APIDOC
ipyaggrid Customization Parameters:

Overview of parameters controlling widget customization:

- `menu`: dict controlling the menu on top of the grid.
  - `menu_div_css`: CSS style options for the main menu div.
  - `input_div_css`: CSS style options for the input div within the menu.
  - `button_div_css`: CSS style options for the button div within the menu.
  - `button_default_css`: Default CSS for buttons.
  - `button_default_flex_css`: Default flex CSS for buttons.
  - `inputs`: List of input elements in the menu (e.g., 'Dropdown Menu', 'Quick Filter', 'Toggle Edit', 'Toggle Delete'). Each input can have `name`, `css_flex`, and `css` properties.
  - `buttons`: List of buttons in the menu. Each button can have `name`, `action` (JS code), `flex_css`, `custom_css`, and `hide` properties. Built-in buttons include 'Export to CSV', 'Export to Excel', etc. Custom buttons can also be defined.

- `css_rules`: string defining custom CSS for the widget.
- `js_pre_helpers`: string containing custom JavaScript to evaluate for use in helpers.
- `js_helpers_custom`: string containing custom JavaScript functions usable in `grid_options`.
- `js_pre_grid`: string containing custom JavaScript to execute using the `gridOptions` variable before grid instantiation.
- `js_post_grid`: string containing custom JavaScript to evaluate and run after grid instantiation.
- `user_params`: variable used for synchronization with other widgets.

Example Input Structure for `menu` parameter:

```json
{
  "buttons": [
    {
      "name": "Export to CSV",
      "action": "",
      "flex_css": {},
      "custom_css": {},
      "hide": false
    },
    {
      "name": "custom_button",
      "action": "js_code",
      "flex_css": {},
      "custom_css": {},
      "hide": false
    }
  ],
  "inputs": [
    {
      "name": "Dropdown Menu",
      "css_flex": {},
      "css": {}
    },
    {
      "name": "Toggle Edit",
      "css_flex": {},
      "css": {}
    }
  ],
  "input_div_css": {},
  "menu_div_css": {},
  "button_div_css": {},
  "button_default_css": {},
  "button_default_flex_css": {}
}
```

Widget DOM structure with CSS classes:

```
main-div
├── menu-div
|   ├── input-div
|   |   ├── dropdown-menu
|   |   ├── quick-filter
|   |   ├── toggle-edit
|   |   └── toggle-delete
|   └── button-div
|       ├── export-to-csv
|       ├── export-to-excel
|       ...
|       └── custom-button
└── grid-div
```

`menu-div`, `input-div`, `button-div` use `display: flex`.
CSS options are optional; sensible defaults are built-in.
CSS of items in input-div and button-div follows [ipywidgets CSS](https://github.com/jupyter-widgets/ipywidgets/tree/14db49e9537c79c996e34644364eb15343101d89/packages/controls/css).
```

--------------------------------

### Custom Button with Cell Highlighting

Source: https://widgetti.github.io/ipyaggrid/guide/customize

An example of a custom button that iterates through grid nodes, checks a condition on cell data (price > 30000), and then uses the ag-Grid API's flashCells method to visually highlight matching cells.

```python
buttons=[
    {'name':'Highlight', 'action':"""
gridOptions.api.forEachNodeAfterFilterAndSort(node => {
    if (node.aggData){
        if (node.aggData.price.value > 30000){
            gridOptions.api.flashCells({rowNodes: [node], columns: ["price"]});
        }
    } else {
        if (node.data.price>30000){
            gridOptions.api.flashCells({rowNodes: [node], columns: ["price"]});
        }
    }
});
"""}
]
```

--------------------------------

### Uninstall ipyaggrid from Classic Notebook

Source: https://widgetti.github.io/ipyaggrid/guide/install

Removes the ipyaggrid package and its associated Jupyter nbextension from a classic notebook environment. Includes steps for both the nbextension and the pip package.

```shell
# if notebook<5.3
$ jupyter nbextension uninstall --py --sys-prefix ipyaggrid

$ pip uninstall ipyaggrid
```

--------------------------------

### Uninstall Python Package

Source: https://widgetti.github.io/ipyaggrid/dev/dev_install

Uninstalls the ipyaggrid Python package from the current Python environment using pip. This is the final step in the uninstallation process.

```shell
$ pip uninstall ipyaggrid
```

--------------------------------

### Data as List of Dictionaries

Source: https://widgetti.github.io/ipyaggrid/guide/create

An example of how to structure input data as a list of dictionaries, where each dictionary represents a row in the grid.

```python
cars = [
    {'carName': 'Chevelle', 'origin': 'US', 'make': 'Chevrolet', 'price': 30415},
    {'carName': 'Skylark 320', 'origin': 'US', 'make': 'Buick', 'price': 21042},
    ...
    {'carName': 'PL411', 'origin': 'Asia', 'make': 'Datsun', 'price': 27676}
]
```

--------------------------------

### Add Custom Button with Action

Source: https://widgetti.github.io/ipyaggrid/guide/customize

Demonstrates creating a completely custom button with a specific JavaScript `action` that can be executed when the button is clicked. This allows for user-defined functionality beyond the built-in export options.

```python
menu = {
    'buttons':[
        {'name':'Custom Button', 'action':'console.log("foo");'}
    ]
}
```

--------------------------------

### Custom CSS Styling for ipyaggrid Rows and Columns

Source: https://widgetti.github.io/ipyaggrid/guide/customize

This example demonstrates how to apply custom CSS rules to an ipyaggrid grid using the `css_rules` parameter. It shows how to override default styling for row and column hover effects by providing a string containing CSS selectors and properties.

```python
css_rules = """
.ag-row-hover {
    background-color: lightblue !important;
}

.ag-column-hover {
    background-color: powderblue;
}

.ag-row-hover .ag-column-hover {
    background-color: deepskyblue !important;
}
"""

column_defs = [{'field': c} for c in dfm.columns[:7]]

grid_options = {
    'columnDefs' : column_defs,
}

g = Grid(grid_data=dfm,
         css_rules=css_rules,
         grid_options=grid_options)
g
```

```css
.ag-row-hover {
    background-color: lightblue !important;
}

.ag-column-hover {
    background-color: powderblue;
}

.ag-row-hover .ag-column-hover {
    background-color: deepskyblue !important;
}
```

--------------------------------

### ag-Grid API Interaction

Source: https://widgetti.github.io/ipyaggrid/guide/customize

Demonstrates how to access and utilize the ag-Grid API methods from custom JavaScript code. The gridOptions.api object provides access to core grid functionalities like expanding/collapsing rows and manipulating cells.

```APIDOC
ag-Grid API Access:
  gridOptions.api: Provides access to the Grid API.
  gridOptions.columnApi: Provides access to the Column API.

Core Methods:
  expandAll(): Expands all row groups.
  collapseAll(): Collapses all row groups.
  flashCells(params): Highlights cells for a short duration.
    - params.rowNodes: Array of row nodes to flash.
    - params.columns: Array of column field names to flash.
  forEachNodeAfterFilterAndSort(callback): Iterates over all nodes after filtering and sorting.
    - callback(node): Function executed for each node.
      - node.aggData: Aggregated data for group rows.
      - node.data: Data for regular rows.

Related Concepts:
  - Custom Buttons: JavaScript actions triggered by UI buttons.
  - Cell Renderers/Formatters: Custom JavaScript functions for displaying cell content.
```

--------------------------------

### Custom Buttons for Grid Actions

Source: https://widgetti.github.io/ipyaggrid/guide/customize

Defines custom buttons that can trigger actions on the ag-Grid instance. These buttons are created as a list of dictionaries, where each dictionary specifies a button's name and the JavaScript action to execute.

```python
buttons = [
    {'name':'Expand All', 'action':'''gridOptions.api.expandAll();'''},
    {'name':'Collapse All', 'action':'''gridOptions.api.collapseAll();'''}
]
```

--------------------------------

### Customize Button CSS

Source: https://widgetti.github.io/ipyaggrid/guide/customize

Shows how to customize the CSS of existing buttons, such as 'Export to CSV', by adding a `custom_css` dictionary to the button's configuration within the `menu` field. It also illustrates the option to hide buttons using `'hide': True`.

```python
menu = {
    # Possible names : 'Export to CSV', 'Export to Excel', 'Export Grid',
    #                  'Export Range', 'Export Rows', 'Export Columns'
    'buttons':[
        {'name':'Export to CSV', 'custom_css':{'color':'red'}, 'hide':False}
    ]
}
```

--------------------------------

### Export ipyaggrid Widget to HTML

Source: https://widgetti.github.io/ipyaggrid/guide/export

Demonstrates calling the `.export_html()` method on an ipyaggrid object to obtain components for embedding in HTML. This method returns a dictionary containing script tags, HTML state, manager state, and the grid's div.

```python
html_export = grid.export_html()
```

--------------------------------

### Merge ipyaggrid Widget States

Source: https://widgetti.github.io/ipyaggrid/guide/export

Illustrates the process of merging the state dictionaries of multiple ipyaggrid widgets to create a single manager state for embedding several widgets into one HTML page. This prevents duplicate manager instances.

```python
# Widget a
manager_state_a

# Widget b
manager_state_b

manager_state_a['state'] = manager_state_a['state'].update(manager_state_b['state'])
# Now manager_state_a contains both the state of a and b.
```

--------------------------------

### Configuring ipyaggrid with ag-Grid Options

Source: https://widgetti.github.io/ipyaggrid/guide/create

Demonstrates how to define column definitions and grid properties for ag-Grid, and then use them to instantiate the ipyaggrid Grid.

```python
column_defs = [{'headerName':'Continent','field':'continent','rowGroup':True, 'hide':True},
               {'headerName':'Country','field':'country','rowGroup':True, 'hide':True},
               {'headerName':'Status','field':'status'},
               {'headerName':'Date','field':'year','cellRenderer':'''function(params){
                   if (params.value !== undefined && params.value !== null){
                   return (params.value.substring(0,4));
                   }
                   return ""
               }'''
                },
               {'headerName':'Name','field':'name'},
               {'headerName':'Mass','field':'mass', 'aggFunc':'avg'},
               {'headerName':'Latitude','field':'latitude'},
               {'headerName':'Longitude','field':'longitude'},
              ]

grid_options = {
    'columnDefs' : column_defs,
    'enableSorting': True,
    'enableFilter': True,
    'enableColResize': True,
    'enableRangeSelection': True,
}

g = Grid(grid_data=dfm,
         grid_options=grid_options,
         quick_filter=True,
         show_toggle_edit=True,
         export_mode="buttons",
         export_csv=True,
         export_excel=True,
         theme='ag-theme-balham',
         show_toggle_delete=True,
         columns_fit='auto',
         index=False,
         keep_multiindex=False)
g
```

--------------------------------

### Create ipyaggrid Grid with Data and Options (Python)

Source: https://widgetti.github.io/ipyaggrid/guide/create

Demonstrates how to create an ipyaggrid Grid widget by passing data (list of dict or DataFrame) and ag-Grid options. The widget is then displayed in the Jupyter environment.

```Python
import ipyaggrid
import pandas as pd

# Sample data
data = [
    {'col1': 'value1', 'col2': 10},
    {'col1': 'value2', 'col2': 20}
]
df = pd.DataFrame(data)

# Grid options (example)
grid_options = {
    'columnDefs': [
        {'headerName': 'Column 1', 'field': 'col1'},
        {'headerName': 'Column 2', 'field': 'col2'}
    ],
    'rowData': df.to_dict('records')
}

# Create the Grid widget
grid_widget = ipyaggrid.Grid(
    grid_data=df,
    grid_options=grid_options,
    # Other widget options can be passed here, e.g.:
    # width='100%',
    # height=400,
    # theme='alpine'
)

# Display the widget (in a Jupyter environment)
grid_widget
```

--------------------------------

### Uninstall Jupyter Notebook Extension

Source: https://widgetti.github.io/ipyaggrid/dev/dev_install

Removes the ipyaggrid Jupyter Notebook extension from the system. This is the reverse operation of enabling the extension.

```shell
$ jupyter nbextension uninstall --py --sys-prefix ipyaggrid
```

--------------------------------

### Uninstall JupyterLab Extension

Source: https://widgetti.github.io/ipyaggrid/dev/dev_install

Unlinks the ipyaggrid JupyterLab extension, removing it from the JupyterLab environment. This is the reverse operation of linking the extension.

```shell
$ jupyter labextension unlink ipyaggrid/js
```

--------------------------------

### ipyaggrid Grid Constructor Parameters

Source: https://widgetti.github.io/ipyaggrid/guide/create

Defines the constructor signature for the ipyaggrid Grid class, outlining various parameters for grid initialization, data handling, and UI features.

```APIDOC
Grid:
  __init__(self, width='100%', height=0, center=False, theme='ag-theme-fresh', grid_data=[], grid_options={}, grid_options_multi=[], columns_fit='size_to_fit', index=False, keep_multiindex=False, compress_data=True, quick_filter=False, export_csv=False, export_excel=False, show_toggle_delete=False, show_toggle_edit=False, paste_from_excel=False, export_mode='disabled', export_to_df=True, hide_grid=False, js_helpers_custom='', js_pre_helpers=[], js_pre_grid=[], js_post_grid=[], css_rules='', menu=None, user_params={}, license=''):
    Parameters:
      width (str): Width of the grid.
      height (int): Height of the grid.
      center (bool): Whether to center the grid.
      theme (str): The ag-Grid theme to apply.
      grid_data (list or pandas.DataFrame): The data to display in the grid.
      grid_options (dict): Dictionary of ag-Grid options.
      grid_options_multi (list): List of grid options for multiple grids.
      columns_fit (str): Strategy for fitting columns ('size_to_fit', 'auto').
      index (bool): Whether to display the DataFrame index.
      keep_multiindex (bool): Whether to keep multi-index structure.
      compress_data (bool): Whether to compress data.
      quick_filter (bool): Enable quick filter functionality.
      export_csv (bool): Enable CSV export button.
      export_excel (bool): Enable Excel export button.
      show_toggle_delete (bool): Show toggle for deleting rows.
      show_toggle_edit (bool): Show toggle for editing rows.
      paste_from_excel (bool): Enable pasting from Excel.
      export_mode (str): Mode for export functionality ('disabled', 'buttons').
      export_to_df (bool): Export data to DataFrame.
      hide_grid (bool): Whether to hide the grid.
      js_helpers_custom (str): Custom JavaScript helper functions.
      js_pre_helpers (list of str): JavaScript code to run before grid initialization.
      js_pre_grid (list of str): JavaScript code to run before grid rendering.
      js_post_grid (list of str): JavaScript code to run after grid rendering.
      css_rules (str): Custom CSS rules.
      menu (dict): Menu configuration.
      user_params (dict): User-defined parameters.
      license (str): License key.
```

--------------------------------

### Apply Multiple Grid Options

Source: https://widgetti.github.io/ipyaggrid/guide/create

Demonstrates how to apply multiple sets of grid options to the same data, allowing users to switch between different configurations via a dropdown. This enables compact representation and avoids data duplication.

```Python
css_rules = ""
.number-cell {
    text-align: left;
}
.price-high {
    color: red;
}

"

ccf = "function(params) { return params.value >32000 ? 'price-high' : ''; }"
column_defs_1 = [{'field':'origin', 'headerName': 'Origin'},
                  {'field':'make', 'headerName': 'Make'},
                  {'field':'carName', 'headerName':'Model'},
                  {'field':'price', 'headerName': 'Price', 'cellClass': ccf}]

column_defs_2 = [{'field':'origin', 'headerName': 'Origin', 'hide':True, 'rowGroup':True},
                  {'field':'make', 'headerName': 'Make'},
                  {'field':'carName', 'headerName':'Model'},
                  {'field':'price', 'headerName': 'Price'}]

grid_options_1 = {
    'columnDefs' : column_defs_1,
    'enableSorting': True,
    'enableFilter': True,
    'enableColResize': False,
}

grid_options_2 = {
    'columnDefs' : column_defs_2,
    'enableSorting': False,
    'enableFilter': False,
    'enableColResize': True,
    'rowSelection': 'multiple',
}

g = Grid(grid_data=cars,
            css_rules=css_rules,
            grid_options_multi=[('Sorting, color, filter', grid_options_1),
                                ('Selection, grouping, no-filter', grid_options_2)],
            theme='ag-theme-balham')
g
```

--------------------------------

### ipyaggrid: Set Grid Dimensions and Placement

Source: https://widgetti.github.io/ipyaggrid/guide/create

Demonstrates setting the `width`, `height`, and `center` parameters for an `ipyaggrid` instance to control the grid's size and alignment. Width can be a number of pixels or a percentage string.

```python
column_defs = [{'field': c} for c in dfm.columns[:3]]

grid_options = {
    'columnDefs' : column_defs,
}

g = Grid(grid_data=dfm,
         width=600,
         height=500,
         grid_options=grid_options,
         center=True)
g
```

--------------------------------

### ipyaggrid: Apply Grid Themes

Source: https://widgetti.github.io/ipyaggrid/guide/create

Shows how to set the `theme` parameter to customize the visual appearance of the grid. It lists several available themes, including the default 'ag-theme-fresh' and the custom 'ag-theme-excel'.

```python
column_defs = [{'field': c} for c in dfm.columns[:7]]

grid_options = {
    'columnDefs' : column_defs,
}

themes = [
    'ag-theme-balham',
    'ag-theme-balham-dark',
    'ag-theme-material',
    'ag-theme-fresh',
    'ag-theme-dark',
    'ag-theme-blue',
    'ag-theme-bootstrap',
    'ag-theme-excel', # custom style added by ipyaggrid
]

g = Grid(grid_data=dfm,
         theme='ag-theme-balham-dark',
#          theme='ag-theme-balham',
#          theme='ag-theme-excel',
         grid_options=grid_options)
g
```

--------------------------------

### Python Package Publishing

Source: https://widgetti.github.io/ipyaggrid/dev/publish

Steps to publish the Python package to PyPI. This involves ensuring the package version is correct in __meta__.py, clearing previous build artifacts, building the source distribution (sdist) and universal wheel, and uploading the distribution files using twine.

```shell
# starting from repo top folder
# make sure package version is correct in __meta__.py

# clear dist/ from previous bundles
rm -rf dist

# build Python package
$ python setup.py sdist
$ python setup.py bdist_wheel --universal

# upload package to PyPI - using ~/.pypirc
$ twine upload dist/*
# if you made a mistake you can remove the package on pypi.org
```

--------------------------------

### Enable QuickFilter in ipyaggrid

Source: https://widgetti.github.io/ipyaggrid/guide/create

Shows how to activate the quick filter feature, which adds a search field above the grid for real-time filtering. This provides a convenient basic search functionality, complementing column-specific filtering.

```python
column_defs = [{'field':'origin', 'headerName': 'Origin'},
                  {'field':'make', 'headerName': 'Make'},
                  {'field':'carName', 'headerName':'Model'},
                  {'field':'price', 'headerName': 'Price'}]

grid_options = {
    'columnDefs' : column_defs,
}

g = Grid(grid_data=cars,
         grid_options=grid_options,
         quick_filter=True)
g
```

--------------------------------

### ipyaggrid: Configure Column Sizing Behavior

Source: https://widgetti.github.io/ipyaggrid/guide/create

Illustrates the `columns_fit` parameter, which controls how columns adjust to fit the grid's width. Options include 'size_to_fit' (fills space), 'auto' (minimum required space), or an empty string for manual sizing.

```python
column_defs = [{'field': c, 'width':500} for c in dfm.columns]

grid_options = {
    'columnDefs' : column_defs,
}

g = Grid(grid_data=dfm,
         grid_options=grid_options,
         columns_fit="auto")
g
```

--------------------------------

### Git Commit and Tagging

Source: https://widgetti.github.io/ipyaggrid/dev/publish

Steps to commit code changes and tag a new version using Git. This involves staging changes, committing with a message, and creating a tag corresponding to the Python version, followed by pushing commits and tags to the remote repository.

```shell
# starting from repo top folder

# possibly: start afresh
git clean -fdxn # dry run - recommended as cannot be undone
git clean -fdx

# commit
git add .
git commit -m 'my comment'
git tag '<python version e.g. 0.1.0>'
git push
git push --tags
```

--------------------------------

### ipyaggrid: Enable Data Export to CSV and Excel

Source: https://widgetti.github.io/ipyaggrid/guide/create

Demonstrates enabling the `export_csv` and `export_excel` parameters, which add buttons above the grid to allow users to download the data. Excel export is an enterprise feature.

```python
column_defs = [{'field': c} for c in dfm.columns[:7]]

grid_options = {
    'columnDefs' : column_defs,
}

g = Grid(grid_data=dfm,
         grid_options=grid_options,
         export_csv=True,
         export_excel=True)
g
```

--------------------------------

### Sync Grid: Automatic Grid Sync on Initialization/Update in ipyaggrid

Source: https://widgetti.github.io/ipyaggrid/guide/create

Setting `sync_grid=True` ensures that the grid's data is automatically synchronized with its internal representation (`.grid_data_out['grid']`) upon initialization or after a data update. This provides real-time access to the grid's current state without manual calls, though it may impact performance with large datasets.

```python
df2 = pd.DataFrame({'val':['a']})
column_defs = [{'headerName': 'Col', 'field': 'val', 'editable': True}]

grid_options = {
    'columnDefs': column_defs
}

g = Grid(grid_data=df2,
         grid_options=grid_options,
         sync_grid=True,
         width=200,
         height=100)

display(g)

# upon initialization or grid data update the dataframe is: g.grid_data_out['grid']
```
Tokens:
Raw