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!
You can find a list of all attributes here.
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.
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.
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>
[guides: component basics]