-
Notifications
You must be signed in to change notification settings - Fork 4
API Draft v0.1
The template is defined on the HTML page itself and data is passed to it by reference.
Here, the chart data is provided as part of the chart's config object which is referenced on the global scope:
// index.html
<!-- data (section and chart both) and chart config objects available on the global scope directly referenced in the template -->
<script>
window.dvData1 = {
title: "Hi",
message: "This is the first DV instance and a simple chart."
};
window.dvChartConfig1 = {
xAxis: {
categories: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
]
},
series: [{
data: [29.9, 71.5, 106.4, 129.2, 144.0, 176.0, 135.6, 148.5, 216.4, 194.1, 95.6, 54.4],
type: 'column'
}]
}
};
</script>
<script src="https://eccc.cdn.ca/[email protected]"></script>
<div dv-root dv-data="dvData1" dv-id="dv1">
<h2>{{ title }}</h2>
<p>{{ message }}</p>
<dv-chart dv-chart-config="dvChartConfig1"></dv-chart>
</div>The chart data can be referenced separately from the chart's config object:
// index.html
<script>
window.dvData2 = {
title: "Hi",
message: "This is the first DV instance and a simple chart."
};
window.dvChartConfig2 = {
xAxis: {
categories: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
]
},
series: [{
// data is provided separatelly
type: 'column'
}]
}
};
window.dvChartData2 = [[29.9, 71.5, 106.4, 129.2, 144.0, 176.0, 135.6, 148.5, 216.4, 194.1, 95.6, 54.4]];
</script>
<script src="https://eccc.cdn.ca/[email protected]"></script>
<div dv-root dv-data="dvData2" dv-id="dv2">
<h2>{{ title }}</h2>
<p>{{ message }}</p>
<dv-chart dv-chart-data="dvChartData2" dv-chart-config="dvChartConfig2"></dv-chart>Template and chart config can be provided via a callback function:
// index.html
<!-- the template references functions available on the global scope which return data (section and chart both) and chart config (either a plain object of a Promise) -->
<script>
window.getDVData3 = () => ({
title: "Hi",
message: "This is the first DV instance and a simple chart."
});
window.getDVChartConfig3 = () => ({
xAxis: {
categories: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
]
},
series: [{
data: [29.9, 71.5, 106.4, 129.2, 144.0, 176.0, 135.6, 148.5, 216.4, 194.1, 95.6, 54.4],
type: 'column'
}]
}
});
</script>
<script src="https://eccc.cdn.ca/[email protected]"></script>
<div dv-root dv-data="getDVData3()" dv-id="dv3">
<h2>{{ title }}</h2>
<p>{{ message }}</p>
<dv-chart dv-chart-config="getDVChartConfig3()"></dv-chart>
</div>When creating a standalone chart without a template section, there is no need to provide data object to the dv-root:
// index.html
<script>
window.getDVChartConfig4_1 = () => ({
xAxis: {
categories: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
]
},
series: [{
data: [29.9, 71.5, 106.4, 129.2, 144.0, 176.0, 135.6, 148.5, 216.4, 194.1, 95.6, 54.4],
type: 'column'
}]
}
});
</script>
<script src="https://eccc.cdn.ca/[email protected]"></script>
<div dv-root>
<dv-chart dv-chart-config="getDVChartConfig4_1()"></dv-chart>
</div>Just a template, without a chart:
// index.html
<script>
window.getDVData4_2 = {
title: "Hi",
message: "This is the first DV instance and a simple chart."
};
</script>
<script src="https://eccc.cdn.ca/[email protected]"></script>
<div dv-root dv-data="dvData4_2">
{{ title }}
{{ message }}
</div>No extra JavaScript code is required with this setup - DV instances will be auto-bootstrapped when their respective data/configs become available.
DV instances can be retrieved using their ids specified in the template; if no id was specified, the DQV global object exposes all available DV instances.
// index.js
DQV.getDV(id: string): DVInstance
DQV.allDVs(): DVInstance[]The template, data and chart config can be provided using API calls. DQV exposes a single global object name DQV which works as a constructor for DV instances.
// index.html
<script src="https://eccc.cdn.ca/[email protected]"></script>
<div id="dvMountPoint1"></div>// index.js
const template = `<div dv-id="dv5">
<h2>{{ title }}</h2>
<p>{{ message }}</p>
<dv-chart dv-chart-id="dvChart5_1"></dv-chart>
<dv-chart dv-chart-id="dvChart5_2"></dv-chart>
</div>`;
const data = {
title: "Hi",
message: "This is the first DV instance and a simple chart."
};
// config object includes configs for all the charts in the DV instance
const chartConfig = {
dvChart5_1: {
xAxis: {
categories: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
},
series: [{
data: [29.9, 71.5, 106.4, 129.2, 144.0, 176.0, 135.6, 148.5, 216.4, 194.1, 95.6, 54.4],
type: 'column'
}]
},
dvChart5_2: {...}
};
// create a new DVInstance
const dv: DVInstance = new DQV({ data, template, chartConfig/*, chartData */});
// mount it to an HTML element
dv.mount(document.getElementById('dvMountPoint1'));data, template, and chartConfig can be supplied separately.
const dv: DVInstance = new DQV();
dv.setData(data);
dv.setTemplate(template);
dv.setChartConfig(chartConfig);
dv.mount(document.getElementById('dvMountPoint1'));If chart data is not supplied with the chart config, it needs to be set separately:
// index.js
const template = `<div dv-id="dv6">
<dv-chart dv-chart-id="dvChart6"></dv-chart>
</div>`;
const chartConfig = {
dvChart6: {
xAxis: {
categories: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
]
},
series: [{
// data provided separately
type: 'column'
}]
}
};
const chartData = {
dvChart6: [[29.9, 71.5, 106.4, 129.2, 144.0, 176.0, 135.6, 148.5, 216.4, 194.1, 95.6, 54.4]]
};
const dv: DVInstance = new DQV();
dv.setTemplate(template);
dv.setChartConfig(chartConfig);
dv.setChartData(chartData);
// or
const dv: DVInstance = new DQV({template, chartConfig, chartData});If there are several charts in a DV instance, chart data and configs can also be set individually for each chart.
// index.js
const template = `<div dv-id="dv7">
<dv-chart dv-chart-id="dvChart7"></dv-chart>
</div>`;
const dv: DVInstance = new DQV({ template });
dv.setChartConfig({ dvChart7: chartConfig });
dv.setChartData({ dvChart7: chartData });Even an empty DV instance can be mounted, but it will be rendered, well, empty.
// index.js
// default template = ""
// default data = {}
// default chartConfig = {}
// default chartData = {}
const dv: DVInstance = new DQV();
dv.mount(document.getElementById('dvMountPoint1'));Calling setData(), setChartConfig(), setChartData() or setTemplate() after the DV instance is mounted, will re-compile and re-mount the instance.
It's possible to change data belonging to the template inline, without calling setData(), but that won't work for charts.
// index.js
const data = {
title: "Hi",
message: "This is the first DV instance and a simple chart."
};
const dv: DVInstance = new DQV({ data, template, chartConfig , chartData});
data.title = 'Hi, there!'Templates are defined on the HTML page, but data and chart configs are supplied using API calls.
// index.html
<script src="https://eccc.cdn.ca/[email protected]"></script>
<div dv-root dv-id="dv8">
<h2>{{ title }}</h2>
<p>{{ message }}</p>
<dv-chart dv-chart-id="dvChart8_1"></dv-chart>
<dv-chart dv-chart-id="dvChart8_2"></dv-chart>
</div>// index.js
const data = {
title: "Hi",
message: "This is the first DV instance and a simple chart."
};
// config object includes configs for all the charts in the DV instance
const chartConfig = {
dvChart8_1: {
xAxis: {
categories: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
]
},
series: [{
// data is supplied separately
type: 'column'
}]
},
dvChart8_1: {
xAxis: {
categories: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
]
}
}
};
const chartData = {
dvChart8_1: [[29.9, 71.5, 106.4, 129.2, 144.0, 176.0, 135.6, 148.5, 216.4, 194.1, 95.6, 54.4]]
};
// a DV instances will not auto-mount when declared on the page without data or config
const dv = DQV.get('dv8');
dv.setData(data);
dv.setChartConfig(chartConfig);
dv.setChartData(chartData);
// a DV instance will auto-mount when all four components are provided (data, template, chartConfig, and chartData).Marks the root node of a DV instance. Each DV instance must be marked with dv-root. Nesting DV instances is not allowed.
// index.html
<div dv-root>
{{ message }}
</div>Used to retrieve a DV instance using an API call.
// index.html
<div dv-root dv-id="dv1">
{{ message }}
</div>// index.js
const dv = DQV.get('dv1');Points to the data source (object or function) for the DV instance on the global scope.
// index.html
<div dv-root dv-data='dataOjbect'>
{{ message }}
</div>Used to set chart's config and data object; the Highcharts reference can be retreived using an API call.
// index.html
<div dv-root dv-id="dv2">
<dv-chart dv-chart-id="chart2"></dv-chart>
</div>// index.js
const dv = DQV.get('dv2');
dv.setChartData({ chart2: chartData });
const chart = dv.getChart('chart2'); // returns an instance of Highcharts chartPoints to the data source (object or function) for the DV chart on the global scope. It's possible to provide chart data in the config object.
// index.html
<div dv-root>
<dv-chart dv-chart-config="configObject"></dv-chart>
</div>Points to the data source (object or function) for the DV chart on the global scope. A chart config must be provided separately when using dv-chart-data.
// index.html
<div dv-root>
<dv-chart dv-chart-config="configObject" dv-chart-data="dataObject"></dv-chart>
</div>Constructor. Creates a new instance of DV; takes a single optional argument in the form of:
template: string, // valid HTML string
data: object, // free form object to provide data to the template,
chartConfig: object, // top-level properties are named to match chart ids from the template
chartData: object // top-level properties are named to match chart ids from the template// index.js
const dv: DVInstance = new DQV({ template, data, chartConfig, chartData });Called against a DV instance. Sets its template, re-compiles, and re-mounts the instance:
// index.js
const dv: DVInstance = new DQV({ ... });
dv.setTemplate(newTemplate);Called against a DV instance. Sets its data, re-compiles, and re-mounts the instance:
// index.js
const dv: DVInstance = new DQV({ ... });
dv.setData(newTemplate);This call will re-compile and re-mount the DV instance.
Called against a DV instance. Sets configs for all the charts or a specific chart available in the instance (it's possible to provide chart data in its config):
// index.js
const dv: DVInstance = new DQV({ ... });
dv.setChartConfig(newConfig);
// or
const dv: DVInstance = new DQV({ ... });
dv.setChartConfig({ charId: newConfig });This call will re-compile and re-mount the DV instance.
Called against a DV instance. Sets data for all the charts or a specific chart available in the instance (it's not possible to provide chart config in its data).
Each chart data object is an array of data arrays, one for each series of the chart.
// index.js
const newConfig = {
...,
series: [{
type: 'column'
},
{
type: 'line'
}]
};
const newData = {
chart1: [
[1,2,3,4],
[5,6,7,8]
]
};
const dv: DVInstance = new DQV({ ... });
dv.setChartConfig(newConfig);
dv.setChartData(newData);
// or
dv.setChartConfig(newConfig);
dv.setChartData({ chart1: newData.chart1 });This call will re-compile and re-mount the DV instance.
Called against a DV instance. Compiles and mounts a DV instance on (inside?) the element provided:
// index.js
const dv: DVInstance = new DQV({ ... });
dv.mount(element);Calling on already mounted instance will remove the existing instance, re-compile, and re-mount on (inside?) the new target.