From 5dee1d2b2ce8881a2cc22752807d7c26797177da Mon Sep 17 00:00:00 2001 From: Martin Chovanec Date: Fri, 7 Jul 2017 19:51:13 +0200 Subject: [PATCH] Update module:/plot documentation. --- sacredboard/static/scripts/plot/Series.js | 51 ++++++++++++++++++++ sacredboard/static/scripts/plot/component.js | 49 +++++++++++++------ sacredboard/static/scripts/plot/plot.js | 5 +- 3 files changed, 88 insertions(+), 17 deletions(-) create mode 100644 sacredboard/static/scripts/plot/Series.js diff --git a/sacredboard/static/scripts/plot/Series.js b/sacredboard/static/scripts/plot/Series.js new file mode 100644 index 0000000..3b38124 --- /dev/null +++ b/sacredboard/static/scripts/plot/Series.js @@ -0,0 +1,51 @@ +/** + * @module + */ +define([], function () { + "use strict"; + /** + * The Series class is used to store numerical series. + * + * Its x-axis can be either a date or a number. + * The class is consumed by the {@link module:plot/component} module for plotting the data graphically. + * Issue: [#55](https://github.com/chovanecm/sacredboard/issues/55) + */ + class Series { + /** + * Create a new Series object. + * + * @param {ko.observable.Array.|ko.observable.Array.} x - X data of the series. + * Either an array of dates or numbers. + * @param {ko.observable.Array.} y - Y data of the series. + * @param {string} label - Label of the series. + * + * @example new Series( + * ko.observable([1,2,3]), // x + * ko.observable([10, 20, 30]), // y + * ko.observable("x*10")) // label + * + * @example new Series( + * ko.observable([new Date(),new Date(),new Date()]), // x + * ko.observable([10, 20, 30]), // y + * ko.observable("x*10")) // label + */ + constructor(x, y, label) { + /** + * X data of the series. + * @type {ko.observable.Array.|ko.observable.Array.} + */ + this.x = x; + /** + * Y data of the series. + * @type {ko.observable.Array.} + */ + this.y = y; + /** + * Label of the series. + * @type {string} + */ + this.label = label; + } + } + return Series; +}); \ No newline at end of file diff --git a/sacredboard/static/scripts/plot/component.js b/sacredboard/static/scripts/plot/component.js index 54e62dd..aa6f6e5 100644 --- a/sacredboard/static/scripts/plot/component.js +++ b/sacredboard/static/scripts/plot/component.js @@ -1,19 +1,33 @@ "use strict"; /** - * The Plot component () displays a chart of one or more numerical series. - * - * Issue: https://github.com/chovanecm/sacredboard/issues/55 + * The Plot component (``) displays a chart of one or more numerical series. + * This particular module is responsible for definition of the new HTML element. + * Issue: [#55](https://github.com/chovanecm/sacredboard/issues/55) * * It can: * - plot several series at once - * - define labels for x and y labels - * - show the series' label + * - define labels for x and y axes. + * - show the series' label. * - dynamically add/remove series. * - axes: numerical and date values. * - Date should be displayed in the local timezone. * - switch linear/log scale. - * Usage: see the issue or test.html for example. + * + * ### Usage: + * ```html + * + * ``` + * **The values must be Knockout observables.** + * - `xType` and `yType` are one of `linear`, `log`, `date`. The corresponding axis + * adjusts accordingly. + * - Each of the `series` objects is an instance of the {@link Series} class. + * - When a property of the {@link Series} changes, the plot should redraw automatically *(note: this is an expensive operation)*. * * @module plot/component */ @@ -32,8 +46,13 @@ define(["knockout", "escapeHtml", "text!plot/template.html", "./plotlyplot/Plotl /** * View model of the plot component. * - * @param {{series,xLabel,yLabel,xType,yType}} params - Parameters passed to the element. - * @constructor + * @param {{series,xLabel,yLabel,xType,yType}} params - Parameters passed to the `` element. + * @param {ko.observableArray.Array} params.series - Array of Series to be plotted. + * @param {ko.observable.string} params.xLabel - Arbitrary label of the x axis. + * @param {ko.observable.string} params.yLabel - Arbitrary label of the y axis. + * @param {ko.observable.string} params.xType - Type of the x axis (linear/log/date). + * The {@link Series} object expects {@link Date} objects as x-values if `xType` is `"date"`. + * @param {ko.observable.string} params.yType - Type of the y axis (linear/log/date). */ viewModel: function (params) { var self = this; @@ -49,19 +68,13 @@ define(["knockout", "escapeHtml", "text!plot/template.html", "./plotlyplot/Plotl }); - /** - * A numeric series with a label. - * - * @typedef {{x: array, y: array, label: string}} Series - */ - /** * Add a new trace to the plot. * * Also handles changes in underlying data (x, y) and replots them. * * @param {Plot} plot - Plot to use. - * @param {{x,y,label}} aSeries - Series to plot. + * @param {Series} aSeries - Series to plot. */ function addTrace(plot, aSeries) { function replot() { @@ -75,6 +88,12 @@ define(["knockout", "escapeHtml", "text!plot/template.html", "./plotlyplot/Plotl plot.addTrace(aSeries.x(), aSeries.y(), aSeries.label()); } + /** + * Tell Knockout to run the following code on elements with `data-bind="plot: null" attribute`. + * + * This will initialize the plotter on a particular HTML element. + * @type {{init: init, update: update}} + */ ko.bindingHandlers.plot = { /** diff --git a/sacredboard/static/scripts/plot/plot.js b/sacredboard/static/scripts/plot/plot.js index f11e621..8a3f617 100644 --- a/sacredboard/static/scripts/plot/plot.js +++ b/sacredboard/static/scripts/plot/plot.js @@ -2,14 +2,15 @@ /** * A module that defines interface for plotting charts. * + * Required by {@link module:plot/component} to draw {@link Series}. * @module */ define([], function () { /** * A generic plot class to plot a chart. * - * @alias module:plot/plot - * @constructor + * Required by {@link module:plot/component} to draw {@link Series}. + * @class */ class Plot { /**