Quelle  chap5.html   Sprache: HTML

1."encoding"-"?

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
         "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<title>GAP (JupyterViz) - Chapter 5: Adding new visualization tools</title>
<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
<meta name="generator" content="GAPDoc2HTML" />
<link rel="stylesheet" type="text/css" href="manual.css" />
<script src="manual.js" type="text/javascript"></script>
<script type="text/javascript">overwriteStyle();</script>
</head>
<body class="chap5"  onload="jscontent()">


<div class="chlinktop"><span class="chlink1">Goto Chapter: </span><a href="chap0.html">Top</a>  <a href="chap1.html">1</a>  <a href="chap2.html">2</a>  <a href="chap3.html">3</a>  <a href="chap4.html">4</a>  <a href="chap5.html">5</a>  <a href="chap6.html">6</a>  <a href="chap7.html">7</a>  <a href="chapInd.html">Ind</a>  </div>

<div class="chlinkprevnexttop"> <a href="chap0.html">[Top of Book]</a>   <a href="chap0.html#contents">[Contents]</a>    <a href="chap4.html">[Previous Chapter]</a>    <a href="chap6.html">[Next Chapter]</a>   </div>

<p id="mathjaxlink" class="pcenter"><a href="chap5_mj.html">[MathJax on]</a></p>
<p><a id="X81249ADA79916213" name="X81249ADA79916213"></a></p>
<div class="ChapSects"><a href="chap5.html#X81249ADA79916213">5 <span class="Heading">Adding new visualization tools</span></a>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap5.html#X7DB91A9C7C03FF67">5.1 <span class="Heading">Why you might want to do this</span></a>
</span>
</div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap5.html#X858B113D80E8D32B">5.2 <span class="Heading">What you 
</span>
</div>
<div class="ContSect"><span class="tocline"><span java.lang.StringIndexOutOfBoundsException: Index 52 out of bounds for length 0
<span
</div>
<div class="ContSect"><java.lang.StringIndexOutOfBoundsException: Range [2, 1) out of bounds for length 42
<span
</div>
</java.lang.StringIndexOutOfBoundsException: Index 4 out of bounds for length 4

<h3>5 <local result;

<p# thecode  thatbuilds thecomponents of the

<h4>5.1 <span class="Heading">Why you might want to do this</span></h4>

<p>The visualization tools made available by this package (Plotly, D3, CanvasJS, etc.) provide many visualization options. However, you may come across a situation that they do not cover. Or a new and better tool may be invented after this package is created, and you wish to add it to the package.</p  # ou canleveragegraph.vertices,graph.edges, and graph.options.

<p>java.lang.StringIndexOutOfBoundsException: Index 4 out of bounds for length 4

<p><a id="X858B113D80E8D32B"

<h4>.2 <span class="Heading">What you">java.lang.StringIndexOutOfBoundsException: Range [249, 157) out of bounds for length 249

<p>Begin by gathering the following information.</p>


<java.lang.StringIndexOutOfBoundsException: Range [0, 3) out of bounds for length 0
<><>A URLon the internetthatservesthe JavaScriptcodedefiningthe visualizationyouwish  add.Forinstance ChartJS imported  CloudFlare at< ="URL"> ="https:/cdnjs..comajax/ibs/hart.s/.7.2Chart..min.js>https:/cdnjscloudflare.com/ajax/libs/Chart.js/2.7.2/Chart.bundle.min.js</a></span>. It is best if you have this URL from a Content Delivery Network (CDN) to ensure very high availability. This URL may not be necessary in all cases. For instance, perhaps the new visualization tool you wish to install can be defined using the basic JavaScript features in all browsers, or is imported via an <code class="code">iframe</code> rather than as a script in the page itself. If you choose to use such a URL, it will be imported using RequireJS, which expects you to omit the final <code class="code">.js</code> suffix at the end.</p>

</licallback elementelement.childNodes[]);
<li><p>Knowledge of 

</li>
<li><p>While not necessary, it makes things easy if you know a function""

</li>
</ul>
<p>With this information GAP code to use that new visualization tool:

<p><a id="X7E5726AC788EADCC" name="X7E5726AC788EADCC"></a></p>

<h4>5.3 <span class="Heading">Extending this package with a new    tool :="smallExample"

<p>This section explains how to enhance this package itself. If ;

<p>If instead you wish to install a new visualization at runtime for just

<p>Throughout these steps, I will assume that the name of the new tool you wish to install is <code class="code">NEWTOOL</

<ol>
<li><p>Clone the repository for this package.</p>

</li>
<li><p>Enter the <code class="file">lib/"""

</li>
<li>    callback( element element.childNodes[0] );

</li>
<li><p>Edit that file. At the java.lang.StringIndexOutOfBoundsException: Index 32 out of bounds for length 3


<div class="example"><pre>
window.requirejsjava.lang.StringIndexOutOfBoundsException: Index 0 out of bounds for length 0
    paths:{
        NEWTOOL : 'https://cdn.example.com/NEWTOOL.min.InstallVisualizationToolFromTemplate( "canvasjs",
    }
} );
</pre

</li>
<li><p>In the middle of the same( new window..Chart(element, json.  .render();

</li>
<li><p>At the end of the same file, you will notice codecallback element,elementchildNodes[0 ;


<div class="example"><pre>
window.VisualizationTools.NEWTOOL = function ( element, json, callback ) {
    // The variable "element" java.lang.StringIndexOutOfBoundsException: Index 32 out of bounds for length 12
java.lang.StringIndexOutOfBoundsException: Index 0 out of bounds for length 0
   /your  toolkit does its work inan SVGelement,so you needone
    var result = document.createElement( 'SVG' );
    element.append( result );
    // The variable "json" is all the data, java.lang.StringIndexOutOfBoundsException: Index 1 out of bounds for length 0
    /GAP  tell youhow createa visualization.  he data format
    // convention is up to you to explain and document with your new
    // tool.  Two attributes in particular
    
    // those in whateverdiv class=chlinkprevnextbot">&bsp;< href=chap0.html">Top of ]/>nbsp;< =".tml#"[java.lang.StringIndexOutOfBoundsException: Range [123, 122) out of bounds for length 251
   / isanexample  anSVG
    if ( json.width ) result.width = json.width;
    if ( json.height ) result.width = json.height;
    // Then use RequireJS to import your toolkit (which will use the CDN
    // URL you registered above) and use it to fill the element with the
    // desired visualization.  You may or may not need
    // before passing it div class="chlinkbot"><span class="chlink1">Goto Chapter: </span><a href="chap0.html">Top</a>  <a href="chap1.html">1</a>  <a href="chap2.html">2</a>  <a href="chap3.html">3</java.lang.StringIndexOutOfBoundsException: Index 0 out of bounds for length 0
    /you choose establish.
    require( [ 'NEWTOOL' ], function ( NEWTOOL ) {
        // Use your library to set up a visualization/tml>
        var viz = NEWTOOL.setUpVisualizationInElement( result );
        // Tell your library what to draw.  Example:
        viz.buildVisualizationFromJSON( json );
        // Call the callback when you're done.  Pass the element you were
        // given, plus the visualization you created.
        callback( element, result );
    } );
};
</pre></div>

</li>
<li><p>Optionally, in the <code class="file">lib/js/</code> folder, run the <code class="file">minify-all-scripts.sh</code> script, which compresses your JavaScript code to save on data transfer, memory allocation, and parsing time. Rerun that script each time you change your file as well.</p>

</li>
<li><p>You should now be able to use your new visualization tool in <strong class="pkg">GAP</strong>. Verify that your changes worked, and debug as necessary. If you are testing in a Jupyter Notebook, you may be able to notice the change only if you refresh in your browser the page containing notebook and also restart the <strong class="pkg">GAP</strong> kernel in that same page. Then try code like the following to test what you've done.</p>


<div class="example"><pre>
CreateVisualization( rec(
    tool := "NEWTOOL",
    # any other data you need goes here as a GAP record,
    # which the GAP json package will convert into JSON
) );
</pre></div>

</li>
</ol>
<p>At this point, you have added support in <code class="func">CreateVisualization</code> (<a href="chap7.html#X7BFFD8B7808F5BDA"><span class="RefLink">7.2-5</span></a>) for the new tool but have not extended that support to include the high-level functions <code class="func">Plot</code> (<a href="chap7.html#X811D60857B0B2B68"><span class="RefLink">7.1-1</span></a>) or <code class="func">PlotGraph</code> (<a href="chap7.html#X79FCD4E67FF49A5F"><span class="RefLink">7.1-3</span></a>). If possible, you should add that support as well, by following the steps below.</p>

<ol>
<li><p>Read the documentation for either <code class="func">ConvertDataSeriesForTool</code> (<a href="chap7.html#X7B36451A873E06B2"><span class="RefLink">7.1-2</span></a>) or <code class="func">ConvertGraphForTool</code> (<a href="chap7.html#X80380CBB7E1FA082"><span class="RefLink">7.1-4</span></a>), depending on whether the new tool you have installed supports plots or graphs. If it supports both, read both. That documentation explains the new function you would need to install in one or both of those records in order to convert the type of data users provide to <code class="func">Plot</code> (<a href="chap7.html#X811D60857B0B2B68"><span class="RefLink">7.1-1</span></a>) or <code class="func">PlotGraph</code> (<a href="chap7.html#X79FCD4E67FF49A5F"><span class="RefLink">7.1-3</span></a>) into the type of data used by <code class="func">CreateVisualization</code> (<a href="chap7.html#X7BFFD8B7808F5BDA"><span class="RefLink">7.2-5</span></a>).</p>

</li>
<li><p>Edit the <code class="file">main.gi</code> file in this package. Find the section in which new elements are added to the <code class="func">ConvertDataSeriesForTool</code> (<a href="chap7.html#X7B36451A873E06B2"><span class="RefLink">7.1-2</span></a>) or <code class="func">ConvertGraphForTool</code> (<a href="chap7.html#X80380CBB7E1FA082"><span class="RefLink">7.1-4</span></a>) records. Add a new section of code that installs a new field for your tool. It will look like one of the following two blocks (or both if your tool supports both types of visualization).</p>


<div class="example"><pre>
ConvertDataSeriesForTool.NEWTOOL := function ( series )
  local result;
  # Write the code here that builds the components of the
  # GAP record you need, stored in result.
  # You can leverage series.x, series.y, and series.options.
  return result;
end;
ConvertGraphForTool.NEWTOOL := function ( graph )
  local result;
  # Write the code here that builds the components of the
  # GAP record you need, stored in result.
  # You can leverage graph.vertices, graph.edges, and graph.options.
  return result;
end;
</pre></div>

</li>
<li><p>Test your work by loading the updated package into <strong class="pkg">GAP</strong> and making a call to <code class="func">Plot</code> (<a href="chap7.html#X811D60857B0B2B68"><span class="RefLink">7.1-1</span></a>) or <code class="func">PlotGraph</code> (<a href="chap7.html#X79FCD4E67FF49A5F"><span class="RefLink">7.1-3</span></a>) that specifically requests the use of your newly-supported visualization tool.</p>


<div class="example"><pre>
# for plots:
Plot( x -> x^2, rec( tool := "NEWTOOL" ) );
# or for graphs:
PlotGraph( RandomMat( 5, 5 ), rec( tool := "NEWTOOL" ) );
</pre></div>

<p>Verify that it produces the desired results.</p>

</li>
<li><p>Once your changes work, commit them to the repository and submit a pull request back to the original repository, to have your work included in the default distribution.</p>

</li>
</ol>
<p>A complete and working (but silly) example follows. It is a tiny enough visualization tool that it cannot support either plotting data nor drawing graphs, so we don't have to install high-level API support. This portion would go in <code class="file">lib/js/viz-tool-color.js</code>:</p>


<div class="example"><pre>
// No need to import any library from a CDN for this little example.
window.VisualizationTools.color = function ( element, json, callback ) {
    // just writes json.text in json.color, that's all
    var span = document.createElement( 'span' );
    span.textContent = json.text;
    span.style.color = json.color;
    callback( element, span );
};
</pre></div>

<p>This is an example usage of that simple tool from <strong class="pkg">GAP</strong> in a Jupyter notebook:</p>


<div class="example"><pre>
CreateVisualization( rec(
    tool := "color",
    text := "Happy St. Patrick's Day.",
    color := "green"
) );
</pre></div>

<p><a id="X8434DB9C80EC7E6B" name="X8434DB9C80EC7E6B"></a></p>

<h4>5.4 <span class="Heading">Installing a new tool at runtime</span></h4>

<p>This section explains how to add a new visualization tool to this package at runtime, by calling functions built into the package. This is most useful when the visualization tool you wish to install is useful in only a narrow context, such as one of your projects or packages.</p>

<p>If you have a visualization tool that might be of use to anyone who uses this package, consider instead adding it to the package itself and submitting a pull request to have it included in the next release. The previous section explains how to do that.</p>

<p>To install a new visualization tool at runtime, you have two methods available. You can either provide all the JavaScript code yourself or you can provide the necessary ingredients that will be automatically filled into a pre-existing JavaScript code template. We will examine both methods in this section.</p>

<p>The previous section thoroughly documents the two types of code that are likely to show up in the definition of a new tool: the installation into RequireJS of the tool's CDN URL and the installation into <code class="code">window.VisualizationTool</code> of a function that uses that tool to create a visualization from a given JSON object.</p>

<p>If you have all of this JavaScript code already stored in a single GAP string (or in a file that you can load into a string), call it <code class="code">S</code>, then you can install it into this package with a single function call, like so:</p>


<div class="example"><pre>
InstallVisualizationTool( "TOOL_NAME_HERE", S );
</pre></div>

<p>Here is a trivial working example. It is sufficiently small that it does not install any new JavaScript libraries into RequireJS.</p>


<div class="example"><pre>
# GAP code to install a new visualization tool:
InstallVisualizationTool( "smallExample",
"""
window.VisualizationTool.smallExample =
function ( element, json, callback ) {
    element.innerHTML = '<span color=red>' + json.text + '</span>';
    callback( element, element.childNodes[0] );
}
"""
) );

# GAP code to use that new visualization tool:
CreateVisualization( rec(
    tool := "smallExample",
    text := "This text will show up red."
) );
</pre></div>

<p>Because the assignment of a function to create visualizations from JSON is the essential component of installing a new visualization, we have made that step easier by creating a template into which you can just fill in the function body. So the above call to <code class="func">InstallVisualizationTool</code> (<a href="chap7.html#X83454CD67FF0EED7"><span class="RefLink">7.2-3</span></a>) is equivalent to the following call to <code class="func">InstallVisualizationToolFromTemplate</code> (<a href="chap7.html#X876DFB2B87FC3732"><span class="RefLink">7.2-4</span></a>).</p>


<div class="example"><pre>
InstallVisualizationToolFromTemplate( "smallExample",
"""
    element.innerHTML = '<span color=red>' + json.text + '</span>';
    callback( element, element.childNodes[0] );
"""
) );
</pre></div>

<p>If you provide a third parametr to <code class="func">InstallVisualizationToolFromTemplate</code> (<a href="chap7.html#X876DFB2B87FC3732"><span class="RefLink">7.2-4</span></a>), it is treated as the CDN URL for an external library, and code is automatically inserted that installs that external library into RequireJS and wraps the tool's function body in a <code class="code">require</code> call. For instance, the CanvasJS library (which is built into this package) could have been installed with code like the following.</p>


<div class="example"><pre>
InstallVisualizationToolFromTemplate( "canvasjs",
"""
    ( new window.CanvasJS.Chart( element, json.data ) ).render();
    window.resizeToShowContents( element );
    callback( element, element.childNodes[0] );
""",
"https://cdnjs.cloudflare.com/ajax/libs/canvasjs/1.7.0/canvasjs.min.js"
) );
</pre></div>

<p>While RequireJS demands that you omit the <code class="code">.js</code> suffix from such an URL, <code class="func">InstallVisualizationToolFromTemplate</code> (<a href="chap7.html#X876DFB2B87FC3732"><span class="RefLink">7.2-4</span></a>) will automatically remove it for you if you forget to remove it.</p>

<p>After using either of those two methods, if the new visualization tool is capable of drawing either plots or graphs, and you wish to expose it to the high-level API, you should follow the steps for doing so documented in the second half of Section <a href="chap5.html#X7E5726AC788EADCC"><span class="RefLink">5.3</span></a>.</p>


<div class="chlinkprevnextbot"> <a href="chap0.html">[Top of Book]</a>   <a href="chap0.html#contents">[Contents]</a>    <a href="chap4.html">[Previous Chapter]</a>    <a href="chap6.html">[Next Chapter]</a>   </div>


<div class="chlinkbot"><span class="chlink1">Goto Chapter: </span><a href="chap0.html">Top</a>  <a href="chap1.html">1</a>  <a href="chap2.html">2</a>  <a href="chap3.html">3</a>  <a href="chap4.html">4</a>  <a href="chap5.html">5</a>  <a href="chap6.html">6</a>  <a href="chap7.html">7</a>  <a href="chapInd.html">Ind</a>  </div>

<hr />
<p class="foot">generated by <a href="http://www.math.rwth-aachen.de/~Frank.Luebeck/GAPDoc">GAPDoc2HTML</a></p>
</body>
</html>