By Josh at ZingSoft
This post is the first installment in our ‘How Its Made’ blog series. Each of these posts and videos will offer a short walkthrough of how a particular grid is created.
The video below will walk you through the basics of creating this demo. Skip the video to read the walkthrough instead.
Steps to create this grid:
- Rendering the grid to the page
- Overview of ZingGrid features
- Adding renderer functions to customize data
- Styling your grid
Before I begin
Before we dive into how to create this custom grid, I strongly encourage you to sign up for ZingGrid’s ‘Studio’ free web-app.
This free sandbox-like environment allows you to create grids and charts quickly to see how your grids might fit into your site or application. It also offers free pre-made templates to get you off the ground quickly.
Check out the Studio and start creating grids!
1. Rendering the Grid
If you are following along, you will have created the above grid and all its functionality by the end of this tutorial.
I have provided a basic HTML outline below if you decide to start from scratch.
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Global Average Absolute Sea Level Change</title>
<script src="<https://cdn.zinggrid.com/zinggrid.min.js>" defer></script>
</head>
<body> </body>
</html>
To initialize ZingGrid to the page, you should reference our library directly from our CDN by including the script tag (shown above) within the head section of your HTML.
You can also directly download the latest version of our library from our site, or install it locally with a package manager like NPM.
The next step is including the the the <zing-grid> tag to the body of your page. This is where your grid will actually be rendered.
The <zing-grid> tag is the most important tag within the library and is where you will add your data, create and customize columns, and include built in features to your grid.
<zing-grid
src="<https://zinggrid-examples-9f268.firebaseio.com/Global-Average-Sealevel>"
>
</zing-grid>In my case, I compiled our data in Firebase and referenced it using the src attribute as shown above. Notice the src attribute lives within the opening <zing-grid> tag and not between the two tags. To read how to hook up alternative data sources to your grid, visit our docs.
If you hit run, you will see that a grid renders with the data from my external source, but contains very limited styling.
To begin basic customizations of the grid, you will want to start adding captions (headers) and columns to your grid.
This can be accomplished by using the <zg-caption>, <zg-colgroup> and <zg-column> tags in-between the opening and closing <zing-grid> tags.
<zing-grid
src="<https://zinggrid-examples-9f268.firebaseio.com/Global-Average-Sealevel>"
>
<zg-caption>
<h1>Global Average Absolute Sea Level Change (1880 - 2014)</h1>
<p><em>From the US Environmental Protection Agency using data from CSIRO, 2015; NOAA, 2015.</em>
<br>
<a href="<https://datahub.io/core/sea-level-rise>" target="_blank">View Source <i class="far fa-arrow-alt-circle-right"></i></a></p>
</zg-caption>
</zing-grid>Again, To add content to the caption/header of your grid, you will use the <zg-caption> tag. Within the tag, you can format your text in normal HTML syntax. Reference above for how we added content to the header of our grid. If you render this grid, you should see the grid below.
To style the rows or only display certain pieces of data within your dataset, you need to utilize the <zg-colgroup> and <zg-column> tags.
<zing-grid
src="<https://zinggrid-examples-9f268.firebaseio.com/Global-Average-Sealevel>"
> <zg-caption>
<h1>Global Average Absolute Sea Level Change (1880 - 2014)</h1>
<p><em>From the US Environmental Protection Agency using data from CSIRO, 2015; NOAA, 2015.</em>
<br>
<a href="<https://datahub.io/core/sea-level-rise>" target="_blank">View Source <i class="far fa-arrow-alt-circle-right"></i></a></p>
</zg-caption> <zg-colgroup>
<zg-column index="Year" header="Year">
<strong>[[index.Year]]</strong>
</zg-column>
<zg-column index="CSIROAdjustedSeaLevel" header="CSIRO Adjusted Sea Level"></zg-column>
<zg-column index="LowerErrorBound" header="Lower Error Bound"></zg-column>
<zg-column index="NOAAAdjustedSeaLevel" header="NOAA Adjusted Sea Level"></zg-column>
<zg-column index="UpperErrorBound" header="Upper Error Bound"></zg-column>
</zg-colgroup></zing-grid>
You will want to add a <zg-column> for each piece of data you want to display. Referencing the above code snippet, you will notice we have included the index attribute as well as a header attribute. Each index attribute for each column needs to include the name of the property you are trying to display. Each header attribute should be set to the desired header name of your choosing.
If you render this grid, you will notice not much has changed. However, this has opened the door to customize the rows through CSS and Javascript.
2. Adding ZingGrid features
The ability to quickly add and remove features from your grid is what sets ZingGrid apart from other grid libraries.
Looking at the grid we have created thusfar, there isn’t much user interactivity available. However, we can quickly change that with the addition of a few attributes.
<zing-grid
layout="row"
layout-controls="false"
src="<https://zinggrid-examples-9f268.firebaseio.com/Global-Average-Sealevel>"
sort
pager
page-size-options="25,50,100,200"
> ...</zing-grid>
Looking at the code above, you will notice we added a few extra attributes to the <zing-grid> tag. Below is a list of these attributes and how they affect the grid.
layout= Tells ZingGrid whether to display the data in 'rows' or 'cards'layout-controls= Tells ZingGrid whether the user has the option to view the data in row or card modesrc= Tells ZingGrid where to pull the datasort= Gives the grid sorting functionality. Click the column header to change the sort orderpager= Turns on the pagination functionality for your gridpage-size-options= Allows you to choose different number of row or card values displayed on a single page
Try adding these attributes to your <zing-grid> tag and see how they affect your grid.
There are many other attributes you can include based on use case. For a full list of these features, reference the ZingGrid docs.
3. Adding a renderer function
In the case of this dataset, we want to show a clear distinction between values that are greater than 0 and less than 0. To do so, we will create a simple Javascript function and add it to each of our columns.
<script>
function renderNull(value) {
if(value == "null") {
return `<i style="font-size: 12px; color: #a1b2b5;" class="far fa-times-circle"></i> <span class="null"> ${value}</span>`;
} else if(value == "0") {
return `<span style="color: #b3c1c4; font-style: italic;">${value}</span>`;
} else if(value > "0") {
return `<span style="color: #19b29f; font-weight: bold;">${value}</span>`;
} else {
return `<span style="color: #ea5374; font-weight: bold; margin-left: -8px;">${value}</span>`;
}
}
</script>The above function will look at all the values in our dataset and display them based on if they are greater than, less than or equal to 0.
<zing-grid
src="<https://zinggrid-examples-9f268.firebaseio.com/Global-Average-Sealevel>"
> <zg-caption>
<h1>Global Average Absolute Sea Level Change (1880 - 2014)</h1>
<p><em>From the US Environmental Protection Agency using data from CSIRO, 2015; NOAA, 2015.</em>
<br>
<a href="<https://datahub.io/core/sea-level-rise>" target="_blank">View Source <i class="far fa-arrow-alt-circle-right"></i></a></p>
</zg-caption> <zg-colgroup>
<zg-column index="Year" header="Year">
<strong>[[index.Year]]</strong>
</zg-column>
<zg-column index="CSIROAdjustedSeaLevel" renderer="renderNull" header="CSIRO Adjusted Sea Level"></zg-column>
<zg-column index="LowerErrorBound" renderer="renderNull" header="Lower Error Bound"></zg-column>
<zg-column index="NOAAAdjustedSeaLevel" renderer="renderNull" header="NOAA Adjusted Sea Level"></zg-column>
<zg-column index="UpperErrorBound" renderer="renderNull" header="Upper Error Bound"></zg-column>
</zg-colgroup></zing-grid>
Now that we have created this function, we need to make sure it is applied to each column that requires these parameters. In the above code, I have added the renderer attribute to each column that will utilize the function. I have passed in the name of the function as a value of the renderer attribute. Try adding the function and renderer attribute to your code.
Now if you render this, you should see a color change for values less than or greater than 0.
4. Styling your grid
The last important thing we will discuss in this post is how to further target and style your grid using CSS. If you have even minimal experience with CSS, styling your grid should be a fairly easy affair. While we won’t cover each class we created using CSS, you will notice that you can target any ZingGrid tag and give it standard CSS properties.
body {
padding-top: 50px;
font-family: 'Rubik', sans-serif;
background: url('<https://firebasestorage.googleapis.com/v0/b/zinggrid-examples.appspot.com/o/water-levels%2Fweather-cooler.png?alt=media&token=5e6df3b4-1089-47c5-9fea-f191206bbc73>');
}zing-grid {
max-width: 750px;
margin: 0 auto;
font-family: 'Rubik', sans-serif;
border: 0px solid #03375e;
background: #004a6b;
color: #03375e;
--theme-color-primary: #ffffff;
border-radius: 6px;
-webkit-border-radius: 6px;
-moz-border-radius: 6px;
--zg-cell-background_sorted: #e3e6e8;
--zg-head-cell-background_sorted: #045282;
--zg-head-cell-color_sorted: #ffffff;
box-shadow: 0 20px 50px rgba(36, 107, 138, 0.7);
-webkit-box-shadow: 0 20px 50px rgba(36, 107, 138, 0.7);
-moz-box-shadow: 0 20px 50px rgba(36, 107, 138 , 0.7);
}zg-icon {
max-width: 15px;
}zg-caption {
background: #004a6b;
border-bottom: 1px solid #004a6b;
padding: 30px 20px;
border-radius: 6px 6px 0 0;
-webkit-border-radius: 6px 6px 0 0;
-moz-border-radius: 6px 6px 0 0;
text-align: center;
}zg-caption h1 {
color: #76d9f4;
font-size: 25px;
margin: 0;
font-weight: 300;
}zg-caption p {
font-size: 11px;
font-family: 'Roboto Mono', monospace;
color: #F8FAFC;
line-height: 1.9;
margin-bottom: -5px;
}
zg-caption a {
color: #028ecc;
text-decoration: none;
padding: 2px;
font-size: 12px;
margin-top: -15px;
}zg-caption a:hover {
color: #ffffff;
text-decoration: underline;
}zg-head-cell {
font-size: 11px;
background: #028ecc;
color: #F8FAFC;
margin-bottom: -2px;
}zg-body {
font-size: 12px;
font-family: 'Roboto Mono', monospace;
background: #F8FAFC;
color: #04769e;
border: 0px;
}zg-row, zg-cell {
padding: 0 15px;
height: 38px;
}zg-row {
border-bottom: 1px solid #dcdfe0;
}.null {
color: #a1b2b5;
font-style: italic;
}zg-footer {
font-size: 12px;
padding: 0 15px 0 15px;
display: flex;
justify-content: space-between;
color: #ffffff;
background: #004a6b;
}zg-pager {
color: #ffffff;
}zg-watermark {
border-top: 1px solid #004a6b;
background: #004a6b;
border-radius: 0 0 6px 6px;
-webkit-border-radius: 0 0 6px 6px;
-moz-border-radius: 0 0 6px 6px;
}
Take a look at the above CSS and try copying it into your either a separate <style> tag in your HTML or in a separate CSS file. After re-rendering your grid, you should see the fully styled version of the grid we showed previously.
Built using web components, ZingGrid is a fully-featured, native JavaScript data grid solution for the web. With out-of-the-box CRUD capability and ease of use via custom DOM elements, ZingGrid introduces a new way to visualize data using JS grids.
