Goto Chapter: Top 1 2 3 Ind
 [Top of Book]  [Contents]   [Previous Chapter]   [Next Chapter] 

2 Function reference
 2.1 Public API
 2.2 Internal methods
 2.3 Representation wrapper

2 Function reference

2.1 Public API

2.1-1 RunJavaScript
‣ 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.

2.1-2 LoadJavaScriptFile
‣ 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 JupyterViz 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.

2.1-3 CreateVisualization
‣ 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.

CreateVisualization( rec(
    tool := "html",
    data := rec( html := "I am <i>SO</i> excited about this." )
), "console.log( 'Visualization created.' );" );

2.2 Internal methods

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.

2.2-1 JUPVIZAbsoluteJavaScriptFilename
‣ 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 JupyterViz 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.

2.2-2 JUPVIZLoadedJavaScriptCache
‣ 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).

2.2-3 JUPVIZFillInJavaScriptTemplate
‣ 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.

2.2-4 JUPVIZRunJavaScriptFromTemplate
‣ 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

2.2-5 JUPVIZRunJavaScriptUsingRunGAP
‣ 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 );
} );

2.2-6 JUPVIZRunJavaScriptUsingLibraries
‣ 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 );" );

2.3 Representation wrapper

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.

2.3-1 JUPVIZIsFileContents
‣ 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).

2.3-2 JUPVIZIsFileContentsRep
‣ JUPVIZIsFileContentsRep( arg )( filter )

Returns: true or false

The representation for the FileContents type

2.3-3 JUPVIZFileContents
‣ JUPVIZFileContents( arg )( operation )

A constructor for FileContents objects

Elsewhere, the JupyterViz package also installs a JupyterRender method for FileContents objects that just returns their text content untouched.

 [Top of Book]  [Contents]   [Previous Chapter]   [Next Chapter] 
Goto Chapter: Top 1 2 3 Ind

generated by GAPDoc2HTML