Attribute Versus Element

It can often appear that ZingGrid has some attributes and elements that share the same purpose. This is by design to offer convenience to the developer.

Features Via Attribute

For most use cases, setting the attribute will be easier and faster than providing the equivalent markup elements. You should only need to add markup if you wish to customize the default behavior. Features added via attributes have their corresponding elements created and added to the grid automatically on render.

For example, take this grid:

<zing-grid 
  data='[{"firstName":"John", "lastName":"Doe"}, {"firstName":"Jane", "lastName":"Doe"}]'
  caption="Hello ZingGrid"
></zing-grid>

On render, the <zg-caption> tag is generated to the grid in the correct location, like so:

<zing-grid 
  data='[{"firstName":"John", "lastName":"Doe"}, {"firstName":"Jane", "lastName":"Doe"}]'
  caption="Hello ZingGrid">
  <zg-header>
    <zg-caption>Hello ZingGrid</zg-caption>
  </zg-header>
</zing-grid>
Top

Features Via Element

Conversely, you can add the caption via markup and the attribute will be added to the grid (see below). Do this if you need to customize the caption beyond plain text.

<zing-grid data='[{"firstName":"John", "lastName":"Doe"}, {"firstName":"Jane", "lastName":"Doe"}]'>
  <zg-caption><em>Hello ZingGrid<em></zg-caption>
</zing-grid>
Top

Position Options for Attributes

When you add a caption attribute to the <zing-grid> element, it only attaches to the <zg-header> tag. If you want a caption attached to the grid's footer instead, you should apply it to <zg-footer> directly, like so:

<zing-grid>
  <zg-footer>
    <zg-caption>Hello World</zg-caption>
  </zg-footer>
</zing-grid>

However, it is easier to specify the caption's position via its own predefined attributes such as:

position="bottom"

<zing-grid>
  <zg-caption position="bottom">Hello World</zg-caption>
</zing-grid>

or

position="both"

<zing-grid>
  <zg-caption position="both">Hello World</zg-caption>
</zing-grid>
Top

Attributes Take Precedence!

If both the attribute and the element(s) are added by the user, the attribute value will take precedence. Take the following for example:

<zing-grid 
  data='[{"firstName":"John", "lastName":"Doe"}, {"firstName":"Jane", "lastName":"Doe"}]'
  caption="Hello ZingGrid">
  <zg-caption>Alternate Caption</zg-caption>
</zing-grid>

In the rendered example, you can see the attribute took precedence over the matching element.

By having the attribute take precedence, the grid can read changes to the attribute after render and update the element accordingly. For example, if the caption attribute value is updated, the element value will update and you'll see the new value in the grid. If the attribute is removed, the caption element will hide and won't be visible on screen.

Try changing the caption in the accompanying demo:

https://app.zingsoft.com/demos/embed/HNGNSLB5
https://app.zingsoft.com/demos/embed/HNGNSLB5

If you inspect the grid, you'll see the caption attribute is updated, which in turn updates the <zg-caption>'s text content.

Syncing between attribute and element is unidirectional. Changes to the element directly after render will not cause the grid to update. If you cannot update via the attribute after render, you'll need to manually refresh the grid via the grid:refresh event. You can see all of the grid events on the API Events page.

Top

[guides: Attribute vs Element]