Populating a Data Table

This tutorial goes over some of the different ways of populating a Data Table

It might be helpful watching the Tour of Apogee video on the Getting Started page to do this tutorial.

Create a new workspace

In the new workspace, add a data table with a static value: (example)

1. Create a data table name "year". Use the default data view colorized.

2. Inside the "data" view of the table place the number 1980.

Add a data table with a simple formula: (example)

1. Create a data table named "url".

2. Inside the "formula" view, add the single line formula below, creating a URL using a javascript string template literal and the value from our "year" table. In a formula, tables are treated as normal javascript variables.

return `https://www.apogeejs.com/web/examples/population/us${year}.json`;

Add a data table with an asynchronous formula - web request: (example)

1. Create a data table named "populationData".

2. Inside the formula view, add a single line formula, requesting a json object from the given URL.

return apogee.net.jsonRequest(url);

The formula for a data table must be synchronous. If you want to do an asynchronous action, like a web request, you can return a Promise object from the formula.

While the promise is pending, a yellow banner is displayed.When the promise resolves, on success the banner will clear. On failure an error will be displayed.

This function in the code above is from the apogee library. It is like the javascript "fetch" function except its promise returns either the body of the request, converted into a json object, or it throws an error.

Modify a data table so it throws an error: (example)

1. On the "url" table, modify the formula so it just throws an error.

throw new Error("This is an error we generated ourselves!");

//return `https://www.apogeejs.com/web/examples/population/us${year}.json`;

In apogee, errors are displayed to the user as a red banner on the table. Additionally, any table that depends on that table will also show a red banner with the message that a table on which it depends has an error.

Modify a data table so it returns INVALID VALUE: (example)

1. On the "url" table, modify the formula so it just returns apogee.util.INVALID_VALUE.

return apogee.util.INVALID_VALUE;

//return `https://www.apogeejs.com/web/examples/population/us${year}.json`;

If you return apogee.util.INVALID_VALUE, the table displays a gray banner. Additionally, any table that depends on that table will also show a gray banner. This can be done to prevent downstream tables from trying to calculate a value if one table does not have a valid value.

The purpose of this feature is so you don't have to do null checking or the equivalent in your functions. This is especially handy when you have a long cascade of tables based on a single value. Apogee does the check for you, and does not execute the code if it depends on a table with an INVALID VALUE.

This does not depend one whether the executed path will use the variable, only if it is present. What this means is you can't do an INVALID VALUE check and make a decision based on that. That is a feature that should possibly added in a future version (along with a way of handling an error in parent table).

Finished!

This concludes the tutorial. From this you should have learned some of the different ways of assigning a value to a data table.