Web Components Web Component Grid

ag-Grid can be used as a Web Component grid inside your application. This page details how to get started.

Web Components are reusable user interface widgets that are created using open Web technology. They are part of the browser and so they do not depend on external libraries such as AngularJS 1.x or JQuery.

Web Components are of particular interest to ag-Grid as I see them as the future for reusable components. A true Web Component will be reusable in any framework. Angular's directives are based on Web Components.

Web components are an emerging technology and not available in all browsers. Some browsers lacking support can be plugged using polyfills. The examples on this page use webcomponent.js polyfill from Google. The examples on this page have been tested to work with latest versions of Chrome and Firefox on Windows. They failed using IE 11 and Safari on Windows. I have not done extensive testing on which browsers Web Components as what browsers support Web Components and which don't is not a grid problem / discussion, it's specific to Web Components. If you are going to use Web Components in your application, then which browsers your application will run on is a big question you need to answer for yourself. Full working examples of the ag-Grid Web Component can be found in Github, illustrating both a Simple Grid and a Rich Grid.

Dependencies

Using ag-Grid as a Web Component requires two dependencies: ag-grid-webcomponent and either ag-grid or ag-grid-enterprise,.

Download ag-Grid-WebComponent

Bower install ag-Grid Bower
bower install ag-grid-webcomponent 		NPM install ag-Grid NPM
npm install ag-grid-webcomponent 		Github install ag-Grid Github
Download from Github

Referencing ag-Grid-WebComponent

To use ag-grid-webcomponent you need to import it in your html file:

<link rel="import" href="path-to-ag-grid-webcomponent/ag-grid-webcomponent/ag-grid.html">

Download ag-Grid

Bower
bower install ag-grid-community 		NPM
npm install ag-grid-community 		Github
Download from Github

Referencing ag-Grid

ag-Grid is distributed as both a self contained bundle (that places ag-Grid on the global scope) and also via a CommonJS package.

Using the bundled version is the quickest way to get going - reference this version in your HTML file is all you need to do.

<script src="path-to-ag-grid-/ag-grid-community.js"></script>

Download ag-Grid-Enterprise

Bower
bower install ag-grid-enterprise 		NPM
npm install ag-grid-enterprise 		Github
Download from Github

Referencing ag-Grid-Enterprise

ag-Grid-Enterprise is also distributed as both a self contained bundle and also via a CommonJS package.

As with the ag-Grid example, all we need to do is reference the ag-grid-enterprise dependency and we're good to go:

<script src="path-to-ag-grid/ag-grid-community.js"></script>

Using the ag-Grid Web Component

To use the ag-Grid Web Component you need to use ag-grid in your template:

<body> <ag-grid id="myGrid" style="height: 140px; width: 350px;" class="ag-theme-balham"></ag-grid> </body>

You can also provide simple properties at the same time, for example:

<body> <ag-grid id="myGrid" style="height: 140px; width: 350px;" class="ag-theme-balham"> enable-col-resize enable-sorting enable-filter</ag-grid> </body>

Note here that the properties need to be lower case and hyphenated, as per the Web Components standard.

A complete html file might look something like this:

<!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <title>ag-Grid Web Component - Simple Example</title> <!-- webcomponents polyfill - must be before any wc related javascript is executed --> <span style="font-weight: bold"><script src=../../node_modules/@webcomponents/custom-elements/custom-elements.min.js></script></span> <!-- before the ag-grid web component --> <!-- either ag-grid or ag-grid-enterprise, depending on which you're using --> <span style="font-weight: bold"><script src="../../node_modules/ag-grid/dist/ag-grid.min.js"></script></span> <!-- the ag-grid-webcomponent--> <span style="font-weight: bold"><link rel="import" href="../../node_modules/ag-grid-webcomponent/ag-grid.html"></span> <!-- the application code --> <span style="font-weight: bold"><script src="simple-grid-example.js"></script></span> </head> <body> <span style="font-weight: bold"><ag-grid id="myGrid" style="height: 140px; width: 350px;" class="ag-theme-balham"></ag-grid></span> </body> </html>

Note here we're including a polyfill to support older browsers without full support for Web Components (likely to be the case for a while yet), then the ag-Grid dependency, the ag-Grid-WebComponent dependency and finally our application code.

ag-Grid Enterprise Bundle Types

Again similar to ag-Grid, ag-Grid-Enterprise has 4 bundles:

  • dist/ag-grid-enterprise.js -> standard bundle containing JavaScript and CSS
  • dist/ag-grid-enterprise.min.js -> minified bundle containing JavaScript and CSS
  • dist/ag-grid-enterprise.noStyle.js -> standard bundle containing JavaScript without CSS
  • dist/ag-grid-enterprise.min.noStyle.js -> minified bundle containing JavaScript without CSS

Even if you are using React, AngularJS 1.x, Angular, VueJS or Web Components, the above is all you need to do. Any grid you create will be an enterprise grid once you load the library.

Basic Web Components Example

The example below shows a simple grid using Web Components.

Complex Web Components Example

The complex example for Web Components is similar to that for Angular. This is on purpose as Angular components are based on Web Components. The example demonstrates the following:

  • Events: All data out of the grid comes through events. These events are native browser events and can be listened to one of:
    a) Calling addEventListener(eventName, handler) on the element
    b) Add an onXXX handler directly to the element or
    c) Add an onXXX handler directly to the grid options.
    In the example, the event 'columnResized' is added in each of these three ways.
  • Attributes: Attributes can be used for setting up the grid. The example uses such properties for the simple data types (ie when they are not Javascript objects). Notice that boolean attributes are defaulted to 'true' IF the attribute is provided WITHOUT any value. If the attribute is not provided, it is taken as false. Attributes can be changed after the grid is initialised, and the grid will update if appropriate (eg open up your dev tools and change the 'group-headers' and set it to 'false').
  • Properties: The more complex properties (eg row and column data) are attached directly to the grid DOM element.
  • Grid API: The grid can be interfaced with through it's API. The following interact via the API:
    a) The quickFilter text.
    b) The Grid API and Column API buttons
    c) The 'Refresh Data via API' buton
  • Changing Attributes & Properties: When an attribute or property changes value, the grid, if appropriate, acts on this change. This is done in the example in the following locations:
    a) The 'Show Tool Panel' checkbox has it's value bound to the 'showToolPanel' property of the grid.
    b) The 'Refresh Data via Element' generates new data for the grid by attaching it to the rowData property.

Destroy

To get the grid to release resources, call api.destroy(). If you do not do this, old grids will hang around and add to a memory leak problem in your application.

Next Steps...

Now you can go to interfacing to learn about accessing all the features of the grid.