‣ RunJavaScript ( script ) | ( function ) |
Returns: an object that, if rendered in a Jupyter notebook, will run script as JavaScript
If evaluated in a Jupyter notebook, its result, when rendered by that notebook, will run the JavaScript code in script.
When the given code is run, the varible element
will be defined in its environment, and will contain the output element in the Jupyter notebook corresponding to the code that was just evaluated. The script is free to write to that output element.
This function is not intended for use in the GAP REPL.
‣ LoadJavaScriptFile ( filename ) | ( function ) |
Returns: the string contents of the file whose name is given
Interprets the given filename relative to the lib/js/
path in the Jupyter-Viz package's installation folder, because that is where this package stores its JavaScript libraries. A .js
extension will be added to filename iff needed. A .min.js
extension will be added iff such a file exists, to prioritize minified versions of files.
If the file has been loaded before in this GAP session, it will not be reloaded, but will be returned from a cache in memory, for efficiency.
If no such file exists, returns fail
and caches nothing.
‣ CreateVisualization ( data[, code] ) | ( function ) |
Returns: an object that, if rendered in a Jupyter notebook, will run a script to create the desired visualization
The data must be a record that will be converted to JSON using GAP's json package.
The second argument is optional, a string containing JavaScript code to run once the visualization has been created. When that code is run, the variables element
and visualization
will be in its environment, the former holding the output element in the notebook containing the visualization, and the latter holding the visualization element itself.
The data should have the following attributes.
tool
(required) - the name of the visualization tool to use. Currently supported tools:
anychart
, whose JSON data format is given here:
canvas
, that is, a regular HTML canvas element, on which you can draw using arbitrary JavaScript included in the code parameter
canvasjs
, whose JSON data format is given here:
chartjs
, whose JSON data format is given here:
http://www.chartjs.org/docs/latest/getting-started/usage.html
cytoscape
, whose JSON data format is given here:
d3
, which is loaded into an SVG element in the notebook's output cell, and the caller can call any D3 methods on that element thereafter, using arbitrary JavaScript included in the code parameter
html
, which fills the output element with arbitrary HTML, which the caller should provide as a string in the html
field of data, as documented below
plotly
, whose JSON data format is given here:
https://plot.ly/javascript/plotlyjs-function-reference/#plotlynewplot
data
(required) - subobject containing all options specific to the content of the visualization, often passed intact to the external JavaScript visualization library. You should prepare this data in the format required by the library specified in the tool
field, following the documentation for that library cited above.
width
(optional) - width to set on the output element being created
height
(optional) - similar, but height
CreateVisualization( rec( tool := "html", data := rec( html := "I am <i>SO</i> excited about this." ) ), "console.log( 'Visualization created.' );" );
Using the convention common to GAP packages, we prefix all methods not intended for public use with a sequence of characters that indicate our particular package. In this case, we use the JUPVIZ
prefix. This is a sort of "poor man's namespacing."
None of these methods should need to be called by a client of this package. We provide this documentation here for completeness, not out of necessity.
‣ JUPVIZAbsoluteJavaScriptFilename ( filename ) | ( function ) |
Returns: a JavaScript filename to an absolute path in the package dir
Given a relative filename, convert it into an absolute filename by prepending the path to the lib/js/
folder within the Jupyter-Viz package's installation folder. This is used by functions that need to find JavaScript files stored there.
A .js
extension is appended if none is included in the given filename.
‣ JUPVIZLoadedJavaScriptCache | ( global variable ) |
A cache of the contents of any JavaScript files that have been loaded from this package's folder. The existence of this cache means needing to go to the filesystem for these files only once per GAP session. This cache is used by LoadJavaScriptFile
(2.1-2).
‣ JUPVIZFillInJavaScriptTemplate ( filename, dictionary ) | ( function ) |
Returns: a string containing the contents of the given template file, filled in using the given dictionary
A template file is one containing identifiers that begin with a dollar sign ($
). For example, $one
and $two
are both identifiers. One "fills in" the template by replacing such identifiers with whatever text the caller associates with them.
This function loads the file specified by filename by passing that argument directly to LoadJavaScriptFile
(2.1-2). If no such file exists, returns fail
. Otherwise, it proceed as follows.
For each key-value pair in the given dictionary, prefix a $
onto the key, suffix a newline character onto the value, and then replace all occurrences of the new key with the new value. The resulting string is the result.
The newline character is included so that if any of the values in the dictionary contains single-line JavaScript comment characters (//
) then they will not inadvertently affect later code in the template.
‣ JUPVIZRunJavaScriptFromTemplate ( filename, dictionary ) | ( function ) |
Returns: the composition of RunJavaScript
(2.1-1) with JUPVIZFillInJavaScriptTemplate
(2.2-3)
This function is quite simple, and is just a convenience function
‣ JUPVIZRunJavaScriptUsingRunGAP ( jsCode ) | ( function ) |
Returns: an object that, if rendered in a Jupyter notebook, will run jsCode as JavaScript after runGAP
has been defined
There is a JavaScript function called runGAP
, defined in the using-runGAP.js
file distributed with this package. That function makes it easy to make callbacks from JavaScript in a Jupyter notebook to the GAP kernel underneath that notebook. This GAP function runs the given jsCode in the notebook, but only after ensuring that runGAP
is defined globally in that notebook, so that jsCode can call runGAP
as needed.
Here is an example use, from JavaScript, of the runGAP
function.
var calculation = "2^50"; runGAP( calculation + ";", function ( result, error ) { if ( result ) alert( calculation + "=" + result ); else alert( "There was an error: " + error ); } );
‣ JUPVIZRunJavaScriptUsingLibraries ( libraries, jsCode ) | ( function ) |
Returns: an object that, if rendered in a Jupyter notebook, will run jsCode as JavaScript after all libraries have been loaded
There are a set of JavaScript libraries stored in the lib/js/
subfolder of this package's installation folder. The Jupyter notebook does not, by default, know about any of those libraries. This GAP function runs the given jsCode in the notebook, but only after ensuring that all JavaScript files on the list libraries have been loaded, so that jsCode can make use of the functions and variables that they define.
If the first parameter is given as a string instead of a list of strings, it is treated as a list of just one string.
JUPVIZRunJavaScriptUsingLibraries( [ "mylib.js" ], "alert( 'My Lib defines foo to be: ' + window.foo );" ); # Equivalently: JUPVIZRunJavaScriptUsingLibraries( "mylib.js", "alert( 'My Lib defines foo to be: ' + window.foo );" );
This code is documented for completeness's sake only. It is not needed for clients of this package. Package maintainers may be interested in it in the future.
The JupyterKernel package defines a method JupyterRender
that determines how GAP data will be shown to the user in the Jupyter notebook interface. When there is no method implemented for a specific data type, the fallback method uses the built-in GAP method ViewString
.
This presents a problem, because we are often transmitting string data (the contents of JavaScript files) from the GAP kernel to the notebook, and ViewString
is not careful about how it escapes characters such as quotation marks, which can seriously mangle code. Thus we must define our own type and JupyterRender
method for that type, to prevent the use of ViewString
.
The declarations documented below do just that. In the event that ViewString
were upgraded to more useful behavior, this workaround could probably be removed. Note that it is used explicitly in the using-library.js
file in this package.
‣ JUPVIZIsFileContents ( arg ) | ( filter ) |
Returns: true
or false
The type we create is called FileContents
, because that is our purpose for it (to preserve, unaltered, the contents of a text file).
‣ JUPVIZIsFileContentsRep ( arg ) | ( filter ) |
Returns: true
or false
The representation for the FileContents
type
‣ JUPVIZFileContents ( arg ) | ( operation ) |
A constructor for FileContents
objects
Elsewhere, the Jupyter-Viz package also installs a JupyterRender
method for FileContents
objects that just returns their text content untouched.
generated by GAPDoc2HTML