Component Instantiation

The easiest way to create a grid is to create it as a web component. This declarative approach allows you to simply add attributes and markup to add functionality (instead of complicated JavaScript objects and methods).

Simple Component Instantiation

The simplest way to add functionality to your grid is with the built-in features. These are typically added as attributes to the main <zing-grid> tag and are either added as a boolean (no attribute value) or with options (add attribute value). Some examples of features added to the grid by adding a single attribute are: pagination, column sorting, cell editing, changing themes, and even setting the grid's data itself!

All attributes are also reflected properties, which means your grid will watch for and respond to changes after its initial render. For example, you can change the theme of your grid after it is rendered by just changing the [theme="..."] value with JavaScript or dev tools.

See the example below to see how easy it is to set up a grid with just a few attributes:

Simple Component HTML and Grid

<!-- One simple tag and a couple attributes get you a grid -->
<zing-grid
  caption="Hello World"
  editor
  pager
  page-size=3>
</zing-grid>

Complex Component Instantiation

For many of the attributes from the previous section, adding them as attributes is a shortcut/nicety of sorts. The real application of a feature is the markup element(s) that are created as child grid elements. For example, you can add [caption="My Caption"] to <zing-grid> and on render you'll notice that a styled container is rendered above the grid body with the attribute value set as the caption text. However, if you inspect the grid, you'll see that a new element was added as a child element to the grid: <zg-caption> (see below). Due to its nature as a reflected property, if you change the value of the attribute, the text in the new element is also updated.

<zing-grid>
  <!--
    Notice [caption] isn't added to the grid tag.
    It will be automatically reflected there on grid render.
  -->
  <zg-caption caption="Hello World"></zg-caption>
  <zg-pager></zg-pager>
</zing-grid>

Since attributes are just reflections of the child elements they represent, you can instead instantiate the grid with the matching component element instead of the attribute. On render, ZingGrid will add any appropriate attributes to the grid to keep the two systems in sync. Learn more here about using attributes versus elements here.

For most features, simply adding the attribute is sufficient and the recommended way of adding features because it requires the least amount of code. For a few of the more complex grid features, like colgroup/columns and custom dialogs, adding the grid child elements is the only way to add it; there is no equivalent attribute to add to the grid (although these features can use attributes on <zing-grid> to set configuration options).

We use the term "complexity" in relation to the amount of effort. You will need to create more markup and learn the library more to fully understand how each component is used within the <zing-grid> tag. In the complex way of instantiating ZingGrids, we add tags for each attribute.

Using Both Together

You can use a combination of both attributes and components together (see below). Outside of the features that require addition by component only, it is your preference of which method to use.

<!-- Notice pager and pagesize are defined on the root tag, but caption is not -->
<zing-grid
  pager
  page-size=5
>
  <zg-caption>Hello World</zg-caption>
</zing-grid>