No description or website provided.
JavaScript
Pull request Compare This branch is 89 commits behind MG-RAST:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
css
documentation
fonts
images
js
renderers
widgets
.gitignore
README.md

README.md

Retina & stm

OVERVIEW

Retina is a webframework to support dynamic usage of reusable web components. It uses the short term memory (stm) module to provide an organized storage of data within the client memory. In Retina there are two component concepts - renderers and widgets.

A renderer is an independent visualization library that given data and a DOM target renders the data within the target element. It has no concept or knowledge of its surroundings and simply renders the data given to it. It expects the data to be in the format it requires and makes no assumptions about the rendering space given to it. A renderer can be parameterized and offer an arbitrary amount of options, including callback functions to events captured by the renderer. It offers useful defaults for all parameters. An example of a renderer would be a piechart, a table or a three-dimensional graph.

A widget is a component that handles the flow of data for a specific task. It uses the stm to retrieve the data and to store the intermediate data products. It prepares the data in such a way that it can be used by chosen renderers to display and offer a user interface to transform it.

STM is a client side storage for data. It represents the data in a JSON hash of data types, each being a list of data ids, which in turn point at the individual data objects. The data can be retrieved from a REST API, put in directly via javascript calls or be loaded from a file. STM provides callback functions for asynchronously retrieved data.

USAGE

HTML setup

First you should set up a basic HTML page to initialize the modules. We use bootstrap basic layouting functionality. In the head section of the document, link the required libraries:

      <!--external javascript files-->
      <script type="text/javascript" src="jquery.min.js"></script>
      <script type="text/javascript" src="bootstrap.min.js"></script>

      <!--basic javascript files-->
      <script type="text/javascript" src="stm.js"></script>
      <script type="text/javascript" src="retina.js"></script>

      <!--bootstrap style-->
      <link rel="stylesheet" type="text/css" href="bootstrap.css">

Then use a jQuery function call to set up Retina and stm:

     <!--initialization-->
     <script type="text/javascript">
             jQuery( document ).ready(function(){
              stm.init({});
          Retina.init({});
          Retina.load_widget("myWidget").then( function () {
               Retina.Widget.myWidget.create("myWidget", { WIDGET PARAMETERS });
          });
          });
    </script>

Then in the body of the HTML page simply place a div with the id passed to the widget you want to display. Note that you can use an arbitrary amount of widgets on the page. You can also directly use a renderer if you wish.

STM

init(params)

Initializes the stm, optionally setting default parameters. If stm was already set up, this will purge all data in the storage. This function must be called before any operations with stm can occur. Possible parameters are:

  • DataRepositories
    A list of data repositories that can be accessed by the get_objects function. See 'add_repository' for details.
  • DataRepositoryDefault
    Name of the default data repository to use for the get_objects function.
  • Authentication
    Authentication string to be used for the get_objects function.
  • AuthHeaderName
    Name of the header porperty to hold the authentication string. Default is 'AUTH'.
  • Data
    Initial data to be present in the storage. See 'import_data' for details.
  • SourceOrigin
    The allowed source origin for trans-frame messaging. Default is '*'.
  • TargetOrigin
    The allowed target origin for trans-frame messaging. Default is '*'.
  • useDB
    Boolean whether data should be loaded from indexedDB if available. If set to true the database name can be passed as parameter dbName. If this option is used, the function returns a promise which is fulfilled once the data is loaded. Default is false.
  • dbName
    Name of the indexedDB database to load the data from. This option is only valid if useDB is set to true. Default is 'stm'.

add_repository(params)

Adds a repository to the stm. If the repository is the first to be added to the current stm instance, it will be set to be the default repository. The parameters are:

  • url
    Base URL of the data resource.
  • name
    Name of the resource
  • description
    (Optional) Description of the resource.
  • auth
    Boolean whether this resource requires authentication, default is false.
  • isDefault
    Boolean whether this is the default resource. Default is false.

remove_repository(repo_name)

Removes a repository from the repository list of stm.

default_repository(repo_name)

If a repository name is passed, it will be set to be the default repository. The function always returns a reference to the current default repository.

import_data(params)

The import data function accepts three types of data, a list of objects, a hash of objects or a single object instance. The optional parameter 'merge' determines whether a type is replaced if it exists or whether only existing ids will be overwritten.

file_upload

If this function is set as the onchange event of a input type file HTML element, any file selected by the user with that file browse diablog will be attempted to be loaded into the storage. The contents of the file will JSON.parsed and must have the same structure as the storage (a hash of types, each pointing to a hash of ids, each pointing to an object instance). This function can be used to load a dump of the storage back into memory. Note that existing data in the storage will not be cleared, the data will simply be added.

This function is suited for loading data dumped by stm.dump

dump(useDB, dbName)

Dumps the content of the stm.DataStore to a new window. If the content is saved to a file, it can later be loaded by the file_upload.

If useDB is set to true, the data will be dumped to an indexedDB with the name dbName (default is 'stm'). In this case the function will return a promise that is fulfilled once the data import is complete.

save_as (data, filename)

Opens a 'save as' file dialog and stores the data passed under the filename passed.

get_objects({repository, type, id, options})

This will retrieve one or more objects from the specified repository. The function returns a promise, which is fulfilled once the data is loaded into the storage. If no repository is passed, the default repository will be used. The stm will make an api call, using the repositories base url, appending the type and optional id as path parameters. Options will be passed as query parameters. All returned data objects will be put into the storage organized under the type passed in the type parameter.

If you want to provide visual feedback on the loading progess from the get_objects function, you can place a div with the id 'progressIndicator' into your page that contains a div with the id 'progressBar'. The indicator will be set to visible when data load occurs. The progressBar field will show the amount of data that has been loaded so far.

delete_object(type, id)

Deletes the object identified by type and id from the storage.

delete_objects(type, ids)

Deletes the objects identified by the type and the list of ids from the storage.

delete_object_type(type)

Deletes all instances of the specified data type from the storage.

send_data(frame, data, type)

Sends data to an stm in a different window or iframe. The frame parameter can be either a string with the id of an iframe, an iframe object or a window object. The data parameter must hold a data structure suitable for the stm.DataStore and type defines the data type within the data store that the data should be stored in.

If security is of concern, the allowed source and target origin of the message may be set by changing stm.SourceOrigin and stm.TargetOrigin. The default value for both is '*' (allow to/from any origin). If this is to be changed from the default setting, it must be changed in both source and target window.

Retina

init({renderer_resources, widget_resources, library_resource})

Initializes the Retina instance. All passed parameters are optional.

require(library_name, success_callback, error_callback)

If the javascript library identified by the name passed is not yet loaded into the page, it will be asynchronously loaded. The function will return a promise which is fulfilled once the library is loaded.

load_renderer({ name: renderer_name, resource: renderer_base_location })

Loads a renderer into memory, returning a promise which fulfills once the renderer is loaded.

load_widget({ name: widget_name, resource: widget_base_location })

Loads a widget into memory, returning a promise which fulfills once the widget is loaded.

load_library({ name: library_name, resource: library_base_location })

Loads a javascript library into memory, returning a promise which fulfills once the script is loaded.

Retina - Convenience functions

each(array, function)

Executes the function on each of the elements of the array passed.

values(object)

Returns all attribute values of the object passed as an array.

keys(object)

Returns all keys of an object as an array.

propSort (property, direction)

Sorts a list of objects by a property in the given direction.

Numsort(a,b)

Sorting function for numbers that can be used by the javascript sort function.

capitalize(string)

Returns the passed string with the first character capitalized.

wait (ms)

Waits for the defined number of milliseconds before it returns.

date_string

Returns the current date as the local time string.

uuidv4

Returns an RFC4122 complient UUID v4.

mouseCoords(event)

Returns an object with x and y attributes, containing the absolute mouse position of the event passed, relative to the top left of the document (including scrolls).

findPos(DOM object)

Returns an array with x and y coordinates of the object passed, relative to the top left of the document (including scrolls).

Base64

Offers encode and decode functions for Base64 encoding.

svg2png(source, target, width, height)

If the source parameter is an SVG element and the target parameter is a container element, this function will render the SVG as a PNG in the target container. The width and height parameters will scale the target image.

cgiParam (param)

Returns the value of the cgi parameter.

dateString (date)

Returns a neatly formatted string for a time value.

Retina - Prototype functions

Number.formatString

Formats a number to a fixed number of digits and puts in 1000 separators.

Number.padLeft

Prefixes a number with 0s until the defined length is hit.

Number.byteSize

Returns a string formatted to show the number of B/KB/MB and such.

String.hex[Encode|Decode]

Returns the hexadecimal value of a string or string value of a hexadecimal.

Array.[max|min]

Returns the maximum / minimum value inside an array respectively.

Retina - VARIABLES

RendererInstances

Stores an array of references to all instanciated renderers. Each renderer has a property 'index' which is the index in this array.

WidgetInstances

Stores an array of references to all instanciated widgets. Each widget has a property 'index' which is the index in this array.