Component Instantiation

The easiest way to create a grid is to create it as a web component. This declaritive 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!

Many attributes are also what are called reflected properties and the grid will watch and respond to changes after the grid is rendered. 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.

Sample HTML

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

Reflected Attribute List

The following list contains all the reflected attributes for the <zing-grid> component. You can find a list of all attributes here.

Simple Component Demo

Edit
Download
CloseCopy Copied
CloseCopy Copied
CloseCopy Copied

Note: You might have noticed from the previous demo the 'Component/Object' slider in the footer. ZingGrid allows for instantiating the grid via Javascript instead of declarative components. Toggling this shows the object-based code in the 'source' demo-panel and will be remembered for each subsequent demo you view. This is discussed in the next docs section, Object Basics.

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 may 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. If you inspect the grid, you'll see that a new element was added as a child element to the grid: <zg-caption>. 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.

Since attributes are just reflections of the child elements they represent, you may instead instantiate the grid with the matching component element instead of the attribute. On render, ZingChart will add any appropriate attributes to the grid to keep the two systems in sync.

For most features, simply adding the attribute is sufficient and the least amount of code, and is the recommended way of adding features. 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 may 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.

To keep the attribute and DOM elements in-sync, the attribute takes precedence and drives the synchronization. Changing the attribute will update the DOM element, but not vice-versa. If you need to change data after render, update the attribute instead of the DOM element for this reason.

Sample HTML

CloseCopy Copied
<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>

Using Both Together

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

CloseCopy Copied
<!-- 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>
loadingloadBgloadBgloadBgloadBgloadBgloadBgloadBgloadBgloadBgloadBgloadBgloadBgloadBgloadBgloadingloadingloadingloadingloadingloadingloadingloadingloadingloadingloadingloadingloadingloadingloadingloadingloadingloadingloadingloadingloadingloading