Quelle  _Chapter_extend.xml   Sprache: XML

<?xml version="1.0" encoding="UTF-8"?>

<!-- This is an automatically generated file. -->
<Chapter Label="Chapter_extend">
<Heading>Adding new visualization tools</Heading>

<P/>
<Section Label="Chapter_Adding_new_visualization_tools_Section_Why_you_might_want_to_do_this">
<Heading>Why you might want to do this</Heading>

<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/>
 There are two supported way to do this.  First, for tools that you wish
 to be available to all users of this package, you can alter the package
 code itself to include the tool.  (Then please create a pull request so
 that your work might be shared with other &GAP; users in a subsequent
 release of this package.)  Second, for tools that you need for
 just one project or just one other package, there is support for
 installing such tools at runtime.  This chapter documents both
 approaches, each in its own section.  But first, we begin with the list
 of what you will need to have on hand before you begin, which is the same
 for both approaches.
<P/>
</Section>


<Section Label="Chapter_Adding_new_visualization_tools_Section_What_you_will_need">
<Heading>What you will need</Heading>

<P/>
 Begin by gathering the following information.
<List>
<Item>
A URL on the internet that serves the JavaScript code defining the new
    visualization tool you wish to add.  For instance, the ChartJS library
    is imported from CloudFlare, at
    <URL>https://cdnjs.cloudflare.com/ajax/libs/Chart.js/2.7.2/Chart.bundle.min.js</URL>.
    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>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>.js</Code> suffix at the end.
</Item>
<Item>
Knowledge of how to write a short JavaScript function that can embed
    the given tool into any given DOM <Code>Element</Code>.  For many
    tools, this is just a single call to the main class's contructor or
    the library's initialization function. Or, if you haven't imported
    any library that constructs the visualization for you, then this
    function may be more extensive, as you construct the visualization
    yourself.
</Item>
<Item>
While not necessary, it makes things easy if you know a function to
    call in your chosen library that converts JSON data into a
    visualization.  This makes it easier for users to pass all the
    required data and options from &GAP; code, which is the typical
    user's preferred way of defining a visualization.
</Item>
</List>
<P/>
 With this information available, proceed to either of the next two
 sections, depending on whether you intend to upgrade this package itself
 with a new visualization, or just install one into it at runtime.
<P/>
</Section>


<Section Label="Section_extending">
<Heading>Extending this package with a new tool</Heading>

<P/>
 This section explains how to enhance this package itself.  If you follow
 these instructions, you should submit a pull request to have your work
 added to the main repository for the package, and thus eventually
 included in the next release of &GAP;.
<P/>
 If instead you wish to install a new visualization at runtime for just
 your own use in a particular project (or in a package that depends on
 this one), refer to the instructions in the Section
 <Ref Sect="Section_runtime_extend"/> instead.
<P/>
 Throughout these steps, I will assume that the name of the new tool you
 wish to install is <Code>NEWTOOL</Code>.  I choose all capital letters
 to make it stand out, so that you can tell where you need to fill in
 blanks in the examples, but you should probably use lower-case letters,
 to match the convention used by all of the built-in tools.
<P/>
 <Enum>
   <Item>Clone the repository for this package.</Item>
   <Item>Enter the <File>lib/js/</File> folder in the repository.</Item>
   <Item>Duplicate the file <File>viz-tool-chartjs.js</File> and rename it
     suitably for the tool you wish to import, such as
     <File>viz-tool-NEWTOOL.js</File>.  It <Emph>must</Emph> begin with
     <File>viz-tool-</File>.</Item>
   <Item>Edit that file.  At the top, you will notice the installation of
     the CDN URL mentioned in the previous section.  Replace it with the
     URL for your toolkit, and replace the identifier <Code>chartjs</Code>
     with <Code>NEWTOOL</Code>.
<Log><![CDATA[
window.requirejs.config( {
    paths : {
        NEWTOOL : 'https://cdn.example.com/NEWTOOL.min.js'
    }
} );
]]></Log>


 </Item>
   <Item>In the middle of the same file, feel free to update the comments
     to reflect your toolkit rather than ChartJS.</Item>
   <Item>At the end of the same file, you will notice code that installs
     <Code>chartjs</Code> as a new function in the
     <Code>window.VisualizationTools</Code> object.  Replace it with code
     that installs your tool instead.  See the comments below for some
     guidance.
<Log><![CDATA[
window.VisualizationTools.NEWTOOL = function ( element, json, callback ) {
    // The variable "element" is the HTML element in the page into
    // which you should place your visualization.  For example, perhaps
    // your new toolkit does its work in an SVG element, so you need one:
    var result = document.createElement( 'SVG' );
    element.append( result );
    // The variable "json" is all the data, in JSON form, passed from
    // GAP to tell you how to create a visualization.  The data format
    // convention is up to you to explain and document with your new
    // tool.  Two attributes in particular are important here, "width"
    // and "height" -- if you ignore everything else, at least respect
    // those in whatever way makes sense for your visualization.  Here
    // is an example for an SVG:
    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 to modify "json"
    // before passing it to your toolkit; this is up to the conventions
    // you choose to establish.
    require( [ 'NEWTOOL' ], function ( NEWTOOL ) {
        // Use your library to set up a visualization.  Example:
        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 );
    } );
};
]]></Log>


 </Item>
   <Item>Optionally, in the <File>lib/js/</File> folder, run the
     <File>minify-all-scripts.sh</File> 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.</Item>
   <Item>You should now be able to use your new visualization tool in
     &GAP;.  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 &GAP; kernel in that same page.  Then
     try code like the following to test what you've done.
<Log><![CDATA[
CreateVisualization( rec(
    tool := "NEWTOOL",
    # any other data you need goes here as a GAP record,
    # which the GAP json package will convert into JSON
) );
]]></Log>


 </Item>
 </Enum>
 At this point, you have added support in
 <Ref Func="CreateVisualization"/> for the new tool but have not extended
 that support to include the high-level functions <Ref Func="Plot"/> or
 <Ref Func="PlotGraph"/>.  If possible, you should add that support as
 well, by following the steps below.
 <Enum>
   <Item>Read the documentation for either
     <Ref Func="ConvertDataSeriesForTool"/> or
     <Ref Func="ConvertGraphForTool"/>, 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 <Ref Func="Plot"/> or
     <Ref Func="PlotGraph"/> into the type of data used by
     <Ref Func="CreateVisualization"/>.</Item>
   <Item>Edit the <File>main.gi</File> file in this package.  Find the
     section in which new elements are added to the
     <Ref Func="ConvertDataSeriesForTool"/> or
     <Ref Func="ConvertGraphForTool"/> 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).
<Log><![CDATA[
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;
]]></Log>


 </Item>
   <Item>Test your work by loading the updated package into &GAP; and
     making a call to <Ref Func="Plot"/> or
     <Ref Func="PlotGraph"/> that specifically requests the use of your
     newly-supported visualization tool.
<Log><![CDATA[
# for plots:
Plot( x -> x^2, rec( tool := "NEWTOOL" ) );
# or for graphs:
PlotGraph( RandomMat( 5, 5 ), rec( tool := "NEWTOOL" ) );
]]></Log>


 Verify that it produces the desired results.
 </Item>
   <Item>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.</Item>
 </Enum>
 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 <File>lib/js/viz-tool-color.js</File>:
<Log><![CDATA[
// 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 );
};
]]></Log>


<P/>
 This is an example usage of that simple tool from &GAP; in a Jupyter
 notebook:
<P/>
<Log><![CDATA[
CreateVisualization( rec(
    tool := "color",
    text := "Happy St. Patrick's Day.",
    color := "green"
) );
]]></Log>


<P/>
</Section>


<Section Label="Section_runtime_extend">
<Heading>Installing a new tool at runtime</Heading>

<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/>
 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/>
 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/>
 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>window.VisualizationTool</Code> of a function that uses that tool
 to create a visualization from a given JSON object.
<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>S</Code>, then you can install it into this package with a single
 function call, like so:
<Log><![CDATA[
InstallVisualizationTool( "TOOL_NAME_HERE", S );
]]></Log>


 Here is a trivial working example.  It is sufficiently small that it does
 not install any new JavaScript libraries into RequireJS.
<Log><![CDATA[
# GAP code to install a new visualization tool:
InstallVisualizationTool( "smallExample",
"""
window.VisualizationTool.smallExample =
function ( element, json, callback ) {
    element.innerHTML = '' + json.text + '';
    callback( element, element.childNodes[0] );
}
"""
) );

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


<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
 <Ref Func="InstallVisualizationTool"/> is equivalent to the following
 call to <Ref Func="InstallVisualizationToolFromTemplate"/>.
<Log><![CDATA[
InstallVisualizationToolFromTemplate( "smallExample",
"""
    element.innerHTML = '' + json.text + '';
    callback( element, element.childNodes[0] );
"""
) );
]]></Log>


<P/>
 If you provide a third parametr to
 <Ref Func="InstallVisualizationToolFromTemplate"/>, 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>require</Code> call.  For instance, the
 CanvasJS library (which is built into this package) could have been
 installed with code like the following.
<Log><![CDATA[
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"
) );
]]></Log>


 While RequireJS demands that you omit the <Code>.js</Code> suffix from
 such an URL, <Ref Func="InstallVisualizationToolFromTemplate"/> will
 automatically remove it for you if you forget to remove it.
<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 <Ref Sect="Section_extending"/>.
</Section>


</Chapter>