00001 # JavaScript ROOT
00002
00003 The JSROOT project intends to implement ROOT graphics for web browsers.
00004 Reading of binary ROOT files is supported.
00005 It is the successor of the JSRootIO project.
00006
00007
00008 ## Installing JSROOT
00009
00010 In most practical cases it is not necessary to install JSROOT on the local computer - it can be used directly from project web sites <https:
00011
00012 In rare cases one need to install JSROOT on separate web server - for such case one could use provided packages from <https:
00013
00014 One could use JSROOT directly from local file system. If source code was unpacked in `/home/user/jsroot/` subfolder, one could just open it in browser with <file:
00015
00016
00017
00018 ## Reading ROOT files in JSROOT
00019
00020 [The main page](https:
00021
00022 The following parameters can be specified in the URL string:
00023
00024 - file, files - name of the file(s), which will be automatically open with page loading
00025 - json - name of JSON file with stored ROOT object like histogram or canvas
00026 - item, items - name of the item(s) to be displayed
00027 - opt, opts - drawing option(s) for the item(s)
00028 - layout - can be 'simple', 'flex', 'collapsible', 'tabs' or 'gridNxM' where N and M integer values
00029 - nobrowser - do not display file browser
00030 - load - name of extra JavaScript to load
00031 - optimize - drawing optimization 0:off, 1:only large histograms (default), 2:always
00032 - paltte - id of default color palette, 51..121 - new ROOT6 palette (default 57)
00033 - interactive - enable/disable interactive functions 0-disable all, 1-enable all
00034 - noselect - hide file-selection part in the browser (only when file name is specified)
00035 - mathjax - use MathJax for latex output
00036
00037 When specifying `file`, `item` or `opt` parameters, one could provide array like `file=['file1.root','file2.root']`. One could skip quotes when specifying elements names `item=[file1.root/hpx,file2.root/hpy]` or `opt=['',colz]`.
00038
00039 Examples:
00040
00041 - <https:
00042 - <https:
00043 - <https:
00044
00045 Many examples of URL string usage can be found on [JSROOT examples](https:
00046
00047
00048 One can very easy integrate JSROOT graphic into other HTML pages using a __iframe__ tag:
00049
00050 <iframe width="600" height="500" src="https:
00051 </iframe>
00052
00053
00054 ## Reading ROOT files from other servers
00055
00056 In principle, one could open any ROOT file placed in the web, providing the full URL to it like:
00057
00058 <https:
00059
00060 But one should be aware of [Same-origin policy](https:
00061 To enable CORS on Apache web server, hosting ROOT files, one should add following lines to `.htaccess` file:
00062
00063 <IfModule mod_headers.c>
00064 <FilesMatch "\.root">
00065 Header set Access-Control-Allow-Origin "*"
00066 Header set Access-Control-Allow-Headers "range"
00067 Header set Access-Control-Expose-Headers "content-range,content-length,accept-ranges"
00068 Header set Access-Control-Allow-Methods "HEAD,GET"
00069 </FilesMatch>
00070 </IfModule>
00071
00072 More details about configuring of CORS headers can be found [here](https:
00073
00074 Other solution - copy all JSROOT files to the same location than where the data files are located.
00075 In such case one could use the server with its default settings.
00076
00077 A simple case is to copy only the top index.htm file on the server and specify the full path to JSRootCore.js script like:
00078
00079 ...
00080 <script type="text/javascript" src="https://root.cern.ch/js/latest/scripts/JSRootCore.js?gui"></script>
00081 ...
00082
00083 In such case one can also specify a custom files list:
00084
00085 ...
00086 <div id="simpleGUI" path="files/subdir" files="userfile1.root;subdir/usefile2.root">
00087 loading scripts ...
00088 </div>
00089 ...
00090
00091
00092 ## JSROOT with THttpServer
00093
00094 THttpServer provides http access to objects from running ROOT application.
00095 JSROOT is used to implement the user interface in the web browsers.
00096
00097 The layout of the main page coming from THttpServer is similar to the file I/O one.
00098 One could browse existing items and display them. A snapshot of running
00099 server can be seen on the [demo page](https:
00100
00101 One could also specify similar URL parameters to configure the displayed items and drawing options.
00102
00103 It is also possible to display one single item from the THttpServer server like:
00104
00105 <https:
00106
00107
00108 ## Data monitoring with JSROOT
00109
00110 ### Monitoring with http server
00111
00112 The best possibility to organize the monitoring of data from a running application
00113 is to use THttpServer. In such case the client can always access the latest
00114 changes and request only the items currently displayed in the browser.
00115 To enable monitoring, one should activate the appropriate checkbox or
00116 provide __monitoring__ parameter in the URL string like:
00117
00118 <https:
00119
00120 The parameter value is the update interval in milliseconds.
00121
00122
00123 ### JSON file-based monitoring
00124
00125 Solid file-based monitoring (without integration of THttpServer into application) can be
00126 implemented in JSON format. There is the TBufferJSON class, which is capable to potentially
00127 convert any ROOT object (beside TTree) into JSON. Any ROOT application can use such class to
00128 create JSON files for selected objects and write such files in a directory,
00129 which can be accessed via web server. Then one can use JSROOT to read such files and display objects in a web browser.
00130 There is a demonstration page showing such functionality:
00131
00132 <https:
00133
00134 <iframe width="500" height="300" src="https:
00135 </iframe>
00136
00137 This demo page reads in cycle 20 json files and displays them.
00138
00139 If one has a web server which already provides such JSON file, one could specify the URL to this file like:
00140
00141 <https:
00142
00143 Here the same problem with [Cross-Origin Request](https:
00144 If the web server configuration cannot be changed, just copy JSROOT to the web server itself.
00145
00146
00147 ### Binary file-based monitoring (not recommended)
00148
00149 Theoretically, one could use binary ROOT files to implement monitoring.
00150 With such approach, a ROOT-based application creates and regularly updates content of a ROOT file, which can be accessed via normal web server. From the browser side, JSROOT could regularly read the specified objects and update their drawings. But such solution has three major caveats.
00151
00152 First of all, one need to store the data of all objects, which only potentially could be displayed in the browser. In case of 10 objects it does not matter, but for 1000 or 100000 objects this will be a major performance penalty. With such big amount of data one will never achieve higher update rate.
00153
00154 The second problem is I/O. To read the first object from the ROOT file, one need to perform several (about 5) file-reading operations via http protocol.
00155 There is no http file locking mechanism (at least not for standard web servers),
00156 therefore there is no guarantee that the file content is not changed/replaced between consequent read operations. Therefore, one should expect frequent I/O failures while trying to monitor data from ROOT binary files. There is a workaround for the problem - one could load the file completely and exclude many partial I/O operations by this. To achieve this with JSROOT, one should add "+" sign at the end of the file name. Of course, it only could work for small files.
00157
00158 The third problem is the limitations of ROOT I/O in JavaScript. Although it tries to fully repeat logic of binary I/O with the streamer infos evaluation, the JavaScript ROOT I/O will never have 100% functionality of native ROOT. Especially, the custom streamers are a problem for JavaScript - one need to implement them once again and keep them synchronous with ROOT itself. And ROOT is full of custom streamers! Therefore it is just great feature that one can read binary files from a web browser, but one should never rely on the fact that such I/O works for all cases.
00159 Let say that major classes like TH1 or TGraph or TCanvas will be supported, but one will never see full support of TTree or RooWorkspace in JavaScript.
00160
00161 If somebody still wants to use monitoring of data from ROOT files, could try link like:
00162
00163 <https:
00164
00165 In this particular case, the histogram is not changing.
00166
00167
00168 ## Stand-alone usage of JSROOT
00169
00170 Even without any server-side application, JSROOT provides nice ROOT-like graphics,
00171 which could be used in arbitrary HTML pages.
00172 There is [example page](https:
00173 where a 2-D histogram is artificially generated and displayed.
00174 Details about the JSROOT API can be found in the next chapters.
00175
00176
00177 ## JSROOT API
00178
00179 JSROOT consists of several libraries (.js files). They are all provided in the ROOT
00180 repository and are available in the 'etc/http/scripts/' subfolder.
00181 Only the central classes and functions will be documented here.
00182
00183 ### Scripts loading
00184
00185 Before JSROOT can be used, all appropriate scripts should be loaded.
00186 Any HTML pages where JSROOT is used should include the JSRootCore.js script.
00187 The `<head>` section of the HTML page should have the following line:
00188
00189 <script type="text/javascript" src="https:
00190
00191 Here, the default location of JSROOT is specified. One could have a local copy on the file system or on a private web server. When JSROOT is used with THttpServer, the address looks like:
00192
00193 <script type="text/javascript" src="http:
00194
00195 In URL string with JSRootCore.js script one should specify which JSROOT functionality will be loaded:
00196
00197 + '2d' normal drawing for objects like TH1/TCanvas/TGraph
00198 + 'more2d' more classes for 2D drawing like TH2/TF1/TEllipse
00199 + '3d' 3D drawing for 2D/3D histograms
00200 + 'geo' 3D drawing of TGeo classes
00201 + 'io' binary file I/O
00202 + 'math' advanced mathemathical functions
00203 + 'mathjax' loads MathJax.js and use it for latex output
00204 + 'gui' default gui for offline/online applications
00205 + 'load' name of user script(s) to load
00206 + 'onload' name of function to call when scripts loading completed
00207
00208 For instance, to load functionality with normal 2D graphics and binary ROOT files support, one should specify:
00209
00210 <script type="text/javascript" src="https:
00211
00212 One could use minified version of all scripts (as shown in example) - this reduce page loading time significantly.
00213
00214
00215 ### Use of JSON
00216
00217 It is strongly recommended to use JSON when communicating with ROOT application.
00218 THttpServer provides a JSON representation for every registered object with an url address like:
00219
00220 http:
00221
00222 Such JSON representation generated using the [TBufferJSON](http:
00223
00224 To access data from a remote web server, it is recommended to use the [XMLHttpRequest](http:
00225 JSROOT provides a special method to create such class and properly handle it in different browsers.
00226 For receiving JSON from a server one could use following code:
00227
00228 var req = JSROOT.NewHttpRequest("http:
00229 req.send(null);
00230
00231 In the callback function, one gets JavaScript object (or null in case of failure)
00232
00233
00234 ### Objects drawing
00235
00236 After an object has been created, one can directly draw it. If somewhere in a HTML page there is a `<div>` element:
00237
00238 ...
00239 <div id="drawing"></div>
00240 ...
00241
00242 One could use the JSROOT.draw function:
00243
00244 JSROOT.draw("drawing", obj, "colz");
00245
00246 The first argument is the id of the HTML div element, where drawing will be performed. The second argument is the object to draw and the third one is the drawing option.
00247 One is also able to update the drawing with a new version of the object:
00248
00249
00250 JSROOT.redraw("drawing", obj2, "colz");
00251
00252 The JSROOT.redraw() function will call JSROOT.draw if the drawing was not performed before.
00253
00254 In the case when changing of HTML layout leads to resize of element with JSROOT drawing,
00255 one should call JSROOT.resize() to let JSROOT adjust drawing size. One should do:
00256
00257 JSROOT.resize("drawing");
00258
00259 As second argument one could specify exact size for draw elements like:
00260
00261 JSROOT.resize("drawing", { width: 500, height: 200 } );
00262
00263 To correctly cleanup JSROOT drawings from HTML element, one should call:
00264
00265 JSROOT.cleanup("drawing");
00266
00267 Many examples of supported ROOT classes and draw options can be found on [JSROOT examples](https:
00268
00269
00270 ### File API
00271
00272 JSROOT defines the JSROOT.TFile class, which can be used to access binary ROOT files.
00273 One should always remember that all I/O operations are asynchronous in JSROOT.
00274 Therefore, callback functions are used to react when the I/O operation completed.
00275 For example, reading an object from a file and displaying it will look like:
00276
00277 var filename = "https:
00278 JSROOT.OpenFile(filename, function(file) {
00279 file.ReadObject("hpxpy;1", function(obj) {
00280 JSROOT.draw("drawing", obj, "colz");
00281 });
00282 });
00283
00284
00285 ## More API examples
00286
00287 Many different examples of JSROOT API usage can be found on [JSROOT API](https: