# Grid HTML api
*Bridge developers notes*
## 6.5 Grid HTML api
### How is the KendoUI Grid component being used?
\
Before we can explain how it works, we must first look at how it is used.
The Kendo Grid can be used and configured via the following section of HTML code - (process known as declarative programming):
```markup
${ContactName}
```
This code is the [**Basic use**](https://aurelia-ui-toolkits-1.gitbook.io/kendoui-bridge-docs/bridge-developers-notes/pages/-LA5FsAGuG4hTL83atht#/samples/grid/basic-use) sample, which is a part of the larger set of [**Button component samples**](https://aurelia-ui-toolkits-1.gitbook.io/kendoui-bridge-docs/bridge-developers-notes/pages/-LA5FsAGuG4hTL83atht#/samples/button) shown in the [**Aurelia KendoUI catalog**](https://aurelia-ui-toolkits-1.gitbook.io/kendoui-bridge-docs/bridge-developers-notes/pages/-LA5FsAGuG4hTL83atht#/samples).
\
\
**What are the characteristics of this sample, that require this whole article to explain them?**
- We see three custom elements: `k-grid` and `k-col`. The `k-col` custom elements are inside of the `k-grid` custom element, making the `k-col` custom elements "children" of the `k-grid` custom element. The `k-template` custom element is a child element of the `k-col`.
- All three custom elements have some `@bindable` properties available, such as `k-data-source`, `k-title`, `k-command` and `for`. A bindable property is a property inside a view-model marked with the `@bindable` decorator. The `title` property is defined as `@bindable kTitle`. Because of the `@bindable` decorator, we can now set these properties from HTML: ``, and respond to changes of these properties when needed.
The `k-template` custom element is a bit special, as it has a template defined within. Let's look at this more closely:
```markup
${ContactName}
```
This `k-col` has two properties: `for` and `template`, where the `for` is easy to spot, but the `template` is somewhat hidden. The `template` property is extracted by the `` custom element from its inner content (innerHTML). \
### How does the k-template extract the template?
Let's take a look at the code of the [k-template custom element](https://github.com/aurelia-ui-toolkits/aurelia-kendoui-bridge/blob/master/src/common/k-template.js).
We use the `@bindable` properties, to configure them via attributes on the custom element. If we use ``, then Aurelia sets the `for` property on the `k-template` view-model to "template".
Now, how does it extract the template? This magic happens inside of the `@processContent` decorator.
Aurelia's docs explain the @processContent decorator as follows:
The @processContent tells the compiler that the element's content requires special processing. \
In other words, the `@processContent` decorator allows us to process the content of the custom element before anything else has happened to it. The implementation looks like this:
```javascript
@processContent((compiler, resources, element, instruction) => {
let html = element.innerHTML;
if (html !== '') {
instruction.template = html;
}
return true;
})
```
The `@processContent` decorator passes us a few arguments we can use inside of the callback function. The things we care about are `element` and `instruction`. The `element` is the HTML tag of our custom-element, so in this case, ``. It's the same thing as when you `@inject(Element)`. The `instruction` is a [BehaviorInstruction](http://aurelia.io/docs.html#/aurelia/templating/1.0.0-beta.1.0.1/doc/api/class/BehaviorInstruction). All you need to know is that this object is shared by both the `@processContent` and the actual view-model (`Template`). So, this means that we can **define properties** on this object from within the `@processContent` function, and access it from inside the view-model.
In our implementation of the `@processContent` function, we take the `innerHTML` of the `` element, and put this in the `template` property of the `instruction`. We could have chosen any property name, but we chose the name `template`. \
Now, in order for us to pull this `template` property of the [`instruction`](/kendoui-bridge-docs/bridge-developers-notes/grid-html-api.md#instruction) inside the view-model, we need to inject the `TargetInstruction`, as shown below:
```javascript
@inject(TargetInstruction)
export class Template {
@bindable template;
@bindable for = 'template';
constructor(targetInstruction) {
this.template = targetInstruction.elementInstruction.template;
}
}
```
The `targetInstruction` has an `elementInstruction` atttribute which contains the `template` we set inside the `@processContent` function. So now we can use just HTML to define all the column properties we need to pass onto Kendo's grid control! Great!
Now before we go on, let's take a look at `return true;` at the end of the `@processContent` function. What does this do? It tells Aurelia that we have handled content processing, and that no further processing should be done. This effectively removes the content of the custom element, and this is exactly what we want, because we don't want to see the template on the screen. We just want to store the template as a property of the AuClass, so we can pass this onto Kendo's grid. \
### How does the `k-template` element get to the properties of the `k-col` elements?
Let's take a step back, and look at the usage of the Grid control one more time:
```markup
${ContactName}
```
We said that all the `k-col` custom elements are "children" of the `` custom element. What we want is to reach all view-models behind the `k-col` elements, from within the view-model of the ``. Aurelia's got us covered. We need to do something else first though.
Since the `k-grid` custom element now has content, it has become a view. For Aurelia to recognize this, in addition to the `grid.js` view-model, we need to create a `grid.html` file (see [Creating Components](http://aurelia.io/docs.html#/aurelia/framework/1.0.0-beta.1.0.3/doc/article/creating-components) article for more details). In this file, we define the following:
```markup
```
The same applies for both `` and ``.
Notice the use of the `` tag. This tells Aurelia to put the content of the `` tag, at that place in the view. More information about the `` tag, can be found [here](http://patrickwalters.net/wielding-the-power-of-aurelia-content-selectors/).
Now we got this out of our way, we can get back to our problem. From inside the `Grid` view-model, we want to get the properties on the view-model's of all `` custom elements. Luckily, Aurelia has made a nice decorator for this: `@children`. It is used as follows:
```markup
@customElement('k-grid')
export class Grid {
@children('k-col') columns;
}
```
That's it! The `Grid` class now has a `columns` property, containing all the view-models of all the `k-col` custom elements, as an array. The `'k-col'` bit is a css selector, so it is pretty powerful. \
### How are we communicating the column definitions to Kendo's Grid?
Now, if we would use Kendo Grid without Aurelia, the columns would be configured like this:
```javascript
$("#grid").kendoGrid({
columns: [
{
title: "Contact Name",
field: "ContactName",
template: '
${ContactName}
'
},
{
title: "Contact Name",
field: "ContactName",
},
{
title: "Contact Title",
field: "ContactTitle",
},
{
title: "Company Name",
field: "CompanyName",
},
{
field: "Country",
}]
});
```
If you remember, all these properties (title, field, template) are defined inside the view-model's of the `k-col` custom elements. Because we have the lovely `@children` decorator, all these view-models are available in the `columns` property of the `Grid`. So, we can just pass this array in when we initialize the grid!
```javascript
$("#grid").kendoGrid({
columns: this.columns
});
```
And there we have it, Kendo's Grid now knows about the columns we want to see, configured purely via HTML. \
### High level overview
Let's take a look (at a high level) at the process.
The developer uses this piece of HTML code:
```markup
${ContactName}
```
The `k-template` viewmodel uses `@processContent` to "extract" the template which can be found in the content of the `` custom element, and it also stores the `for` property.
The `k-grid` custom element, uses `@children` to get an array of all `AuCol` instances, which contain the `k-title`, `k-field` and `template` properties.
When Kendo's Grid gets initialized, this array of `AuCol` instances is passed along. In essence, Kendo's Grid is now initialized as follows:
```javascript
$("#grid").kendoGrid({
columns: [
{
title: "Contact Name",
field: "ContactName",
template: '
${ContactName}
'
},
{
title: "Contact Name",
field: "ContactName",
},
{
title: "Contact Title",
field: "ContactTitle",
},
{
title: "Company Name",
field: "CompanyName",
},
{
field: "Country",
}]
});
```
Notice how we use Aurelia's binding syntax inside the template? How we compile this template is can be better explained in a different article.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://aurelia-ui-toolkits-1.gitbook.io/kendoui-bridge-docs/bridge-developers-notes/grid-html-api.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.