FAQ/How-Do-I-Customize-A-Visualization.md
... ...
@@ -6,22 +6,25 @@
6 6
7 7
This page is about creating a new visualization, or customizing an existing visualization. This page will explain the major statements and components of the javascript that powers a visualization.
8 8
9
-## 1. Create directory to contain visualization
9
+## Setup
10 10
11
-Create a directory with the path: izenda_root\Resources\Vis\category_name\visualization_name
11
+First, create a directory with the path: izenda_root\Resources\Vis\category_name\visualization_name
12 12
13
-## 2. Create View.html
13
+Next, create View.html. This is the main file of each visualization. It should contain:
14 14
15
-View.html is the main file of each visualization. It should contain:
15
+### CSS
16 16
17
-*Used CSS styles wrapped in style tags (attachment of external CSS files is not supported). To access proper container using Javascript, apply styles to suitable elements inside visualization area use a keyword VIS_ID, which will be replaced with valid visualization identifier in server response
17
+Any CSS styles should be wrapped in style tags (the attachment of external CSS files is not supported). To access the proper container using Javascript, apply styles to suitable elements inside visualization area using the keyword VIS_ID, which will be replaced with a valid visualization identifier in the server response:
18 18
19 19
<style type="text/css">
20 20
#VIS_ID_CONTAINER > span.theme { font-size: 14px; }
21 21
#VIS_ID > span.body { font-size: 12px; }
22 22
</style>
23 23
24
-* Markup - html template of visualization. To correctly initiate visualization, its html tempate should have root element with id="VIS_ID"; in case of complex templates (where VIS_ID is used to identify more specific area), id should be replaced with VIS_ID_CONTAINER
24
+### HTML
25
+
26
+Any HTML used to construct the visualization should also be in View.html. To correctly initiate visualization, its HTML tempate should have a root element with id="VIS_ID"; in the case of complex templates (where VIS_ID is used to identify more specific area), id should be replaced with VIS_ID_CONTAINER:
27
+
25 28
<div id="VIS_ID_CONTAINER">
26 29
<span class="theme">Title</span>
27 30
<div id="VIS_ID">
... ...
@@ -29,45 +32,48 @@ View.html is the main file of each visualization. It should contain:
29 32
</div>
30 33
</div>
31 34
32
-* To use any number of external scripts use <scriptsrc="file_name.js"></script> tag. There are several commonly used scripts, like d3, highcharts etc., all these files stored outside of visualization folder - site_path\Resources\Vis\.scripts. To use one of them in new visualization just type its name and Izenda will attach appropriate file automatically. After user open report with attached visualization, all used scripts (including scripts that contain scripting statements) will be delivered to client via AJAX request and then executed separately one by one in global context using ReportScripting.globalEval method. To debug these scripts use debugger statement in one of executed scripts, or manually place breakpoint inside globalEval method.
35
+### JavaScript
36
+
37
+You may incorporate external scripts by using the <scriptsrc="file_name.js"></script> tag. Some commonly used scripts, such as D3 and HighCharts, are stored outside of the visualization folder at site_path\Resources\Vis\.scripts. To use one of them in a new visualization just type its name and Izenda will attach the appropriate file automatically. After a user opens a report with an attached visualization, all used scripts (including scripts that contain scripting statements) will be delivered to the client via AJAX request and then executed separately one by one in global context using the ReportScripting.globalEval method. To debug these scripts, use a debugger statement in one of the executed scripts, or manually place breakpoints inside the globalEval method.
33 38
34
-## 3. Add Main script statement to View.html
39
+## Create your main script
35 40
36
-That's primary code, which should somehow execute itself. Next statement can be used as an example (name was kept to be able to use the reference to method from inside its body)
41
+This is the primary code, which should be self-executing:
37 42
<script type="text/javascript">
38 43
(function ExecuteVIS_ID() {
39 44
/* code */
40 45
})();
41 46
</script>
42 47
43
-To get access to utility code, which can help with data aggregation, general visualization workflow use global object ReportScripting. Commonly visualization begin from declaration reference to it:
48
+To get access to utility code, which can help with data aggregation, general visualization workflow, and so on, use the global object ReportScripting. Visualizations commonly begin from a declaration reference to it:
44 49
45 50
var util = window.ReportScripting;
46 51
47
-To properly recreate visualization each time window resize, use util.registerResize method, which should be called with next three parameters
52
+To properly recreate visualizations each time the browser window resizes, use the util.registerResize method, which should be called with three parameters
48 53
49 54
function registerResize(VIS_ID, execute, clearing);
50 55
51
-* VIS_ID - string value with current visualization id (must be "VIS_ID")
52
-* execute - reference to main method of visualization to run it again after resize
53
-* clearing - reference to method, which run clearing routines soexecute method can be called safety without any intersections with previously created DOM elements.
56
+* VIS_ID - A string value with current visualization id (must be "VIS_ID").
57
+* execute - A reference to the main method of the visualization to run it again after resizing.
58
+* clearing - A reference to thsi method, which runs clearing routines so the executed method can be called safety without any intersections with previously created DOM elements.
54 59
55
-Here is a simple example of registration (jq$ - reference to jQuery used all across the Izenda to avoid intersections with customers' installations of this library)
60
+Here is a simple example (jq$ is a reference to jQuery used across the Izenda platform to avoid intersections with individual customer installations of this library)
56 61
57 62
util.registerResize("VIS_ID", ExecuteVIS_ID, function () {
58 63
jq$("#VIS_ID").empty();
59 64
});
60 65
61
-To interact with the report there are four variables in context where visualization is currently executing: VIS_FORMJSASTATUS,VIS_COLUMNS, VIS_ROWS, VIS_CONTEXT. To validate input meets requirements, use method util.validate:
66
+To interact with the report, there are four variables in the context where the visualization is currently executing: VIS_FORMJSASTATUS, VIS_COLUMNS, VIS_ROWS, VIS_CONTEXT. To validate that input meets requirements, use the method util.validate:
67
+
62 68
function validate(VIS_ID, VIS_FORMJSASTATUS, VIS_CONTEXT, requirements)
63 69
64
-*VIS_ID - string with current visualization id (must be "VIS_ID")
70
+*VIS_ID - A string with current visualization id (must be "VIS_ID").
65 71
66
-*VIS_FORMJSASTATUS - status, which alerts user about problems with rendering report data on the server (in common, should equals "OK")
72
+*VIS_FORMJSASTATUS - A status, which alerts users about problems with rendering report data on the server.
67 73
68
-*VIS_CONTEXT - data about current executing context: is visualization loaded into dashboards, is visualization rendering to image or other static context, , report's title etc. To navigate and see its actual values use debugger statement, place it on the beginning of visualization and then view it using Report Viewer, or Preview tab on Report Designer.
74
+*VIS_CONTEXT - data about current executing context: is visualization loaded into dashboards, is visualization rendering to image or other static context, report's title, etc. To navigate and see its actual values, use a debugger statement at the beginning of visualization and then view it using Report Viewer, or Preview tab on Report Designer.
69 75
70
-*requirements - object, which can notify utility code to check custom environment properties and run additional validation of input data. This object support next fields: svg, canvas, d3,animation - all of them are boolean flags, which ask to run appropriate feature check. The last field "input" ask to run validation function implemented by user (to check the report have necessary structure: type, count of fields etc.), this field accept boolean value too to simply handle validation result. Here is a few examples how to use it:
76
+*requirements - An object, which can notify utility code to check custom environment properties and run additional validation of input data. This object support next fields: svg, canvas, d3,animation - all of them are boolean flags, which ask to run appropriate feature check. The last field "input" ask to run validation function implemented by user (to check the report have necessary structure: type, count of fields etc.), this field accept boolean value too to simply handle validation result. Here is a few examples how to use it:
71 77
72 78
`if (!util.validate("VIS_ID", VIS_FORMJSASTATUS, VIS_CONTEXT, { d3: true, svg: true, input: VIS_COLUMNS[0].type == 'DateTime' })) return; `
73 79
... ...
@@ -76,7 +82,8 @@ To interact with the report there are four variables in context where visualizat
76 82
* If validation fail, html template of visualization will be cleared and user will be notified with enumeration of encountered problems. In that case util.validate() will return false, any further code statement should be skipped and execution aborted.
77 83
78 84
To use use full list of available utilities, create an instance of ReportScripting by using its function as constructor, pass visualization id and all four context variables:
79
-var vis = new util("VIS_ID", VIS_FORMJSASTATUS, VIS_COLUMNS, VIS_ROWS, VIS_CONTEXT);
85
+
86
+`var vis = new util("VIS_ID", VIS_FORMJSASTATUS, VIS_COLUMNS, VIS_ROWS, VIS_CONTEXT);`
80 87
81 88
Created object have several privileged methods, which give possibility to build different data structures from plain report table suitable for current needs
82 89