
~~Title: Canvas Component API~~

<html><font color=#990000 size="+2"><b>Canvas Component API</b></font></html>

The <color #00a2e8>Knowledge Works™</color> data fabric tool is an interactive, drag-and-drop environment for buiding visually rich, low-code applications. Users can create interactive, Real-Time and data-driven applications powered by StreamScape's Event Faric and Cognitive Analyics AI services.  Applications and visual components offer advanced navigation and user experience previously found only in native desktop applications; including modal dialogs, windows and multi-dimensional navigation. Applications are developed in a modular fashion and centered around individual //Components// that perform specific functions such as displaying a //Pie Cart//, //Scatter Plot//, a //Knowledge Graph// or a //Data Grid//.  Functional components that are not focused on //data visualization// are also available. See [[Visual Components]] for an extensive list of what is supported.

\\

==== Component Life-Cycle Methods ====

Components are self contained visual elements such as Charts, Forms or Applications that allow yout to interact with the Data Fabric back-end.
They can be deployed in a secure, stand-alone fashion as Quilt Desktop tiles, or as part of the RTAI Application Authoring environment.  A 
Component runs inside a container such as <color #00a2e8>Quilt.OS</color>, an <color #00a2e8>RTAI Scene</color> or embedded in a host 
web page as <color #00a2e8>MDI Frame</color> element. They rely on the host container for bootstrapping and provide a secure, robust API 
for controlling life cycle and behavior.

Components are comprised of visual chart elements such as //Pie Chart// or //Scatter Plot//, and //Visual Controls// like <color #00a2e8>IO Controls</color> 
in the <color #00a2e8>Control Tab</color> that can manage behavior of the component and <color #00a2e8>Canvas Controls</color> that can be 
placed directly on the surface of chart elements. Controls can //raise events// and execute business logic, triggered by user interaction such as
data entry, button clicks or state change.  Control triggers can also control the life cycle of components, instructing them to load data or render
visual elements.

\\
  *  ''component.getVariable()'': Returns a //Shared Variable// value defined for this component.

  *  ''component.setVariable()'': Sets a //Shared Variable// value defined for this component.

  *  ''component.resetControls()'': Resets all controls and variables in a component to default state and flushes the data cache. Optionally users can specify an array of specific controls to reset as an argument.

  *  ''component.refresh()'': Updates and synchronizes all controls, their Shared Variable and renders visual changes.  Does not activate ''Spinner'' visual queue.

  *  ''component.render()'': An alias for ''refresh()'' Updates and synchronizes all controls, their Shared Variable and renders visual changes.

  *  ''component.reload()'': Fetches data from the back-end, completley reloads the //Data Model// and performs a ''refresh()''.  Activates the ''Spinner'' visual queue if enabled. The ''reload()'' function can also take //Data Source// elements as parameters and pass them as a literal or a JSON object.  This allows users to explicitly control how data are passed to the back-end function or query.

  *  ''component.show()'': Opens and displays a component as an [[ overlay_panels | Overlay Panel]], which is a light weight, in-browser window.  
  
  *  ''component.hide()'': Closes, but does not destroy the panel.
   
\\

[[ overlay_panels | Overlay Panel]] contents may need to be refreshed, reset or re-loaded prior to display as panels are //singleton// entities and initialized only once for optimization. Panel behavior, positon and vsialization can be controlled by passing a literal or a JSON object with configuration properties. See [[ overlay_panels | documentation]] for more details. 

\\ 

When a canvas component is reloaded or rendered, the accumulated changes are merged and the new values are rendered. This reflects the changed state of chart-style components like //Graph// or //Bar Chart//. Control delta buffer changes, however can be managed in a very granular way using control API calls like ''render()'' or ''refresh()'' to allow for very specific behavior during //data fetch// or //data change//. If data controls such as //Grid// or //ComboBox// are bound to results of the //Data Source// fetch, their content will automatically update if ''component.refresh()'',  ''component.render()'' or ''component.reload()'' are called.  However controls that are not //Data Source// dependent, their content will remain unchanged until their local rendering metods are called.

\\

   *  ''component.setOption(.)'': Sets the option of a specific component to a value.  Options are dotted-notation path equivalents of //Component Editor// tree structures. The method take a path literal and a value as parameters.

   *  ''component.getOption(.)'': Sets the option of a specific component to a value.  Options are dotted-notation path equivalents of //Component Editor// tree structures.

   *  ''component.getControl()'': Returns a specific control that is part of this component.  Takes the name of a control as parameter. 

   *  ''component.getIcon(.)'': Returns a specific //Icon Resource// that has been registered with the //Component// or returns ''undefined'' if icon does not exist. 

\\   
   
=== Trigger Example: ===

<sxh DSQL; gutter: true;>

function(options, component, control, path, event) {  
    console.log('Resource to be removed: ' + component.getVariable('mRN'));
  
    if( (component.getVariable('mRN') == '') || (component.getVariable('accountId') == '') )  { 
        // Display error on the form'' canvas using a label, and return  
        component.setVariable('error_msg', 'Resource Name or Account is empty..');
        component.refresh();
        return;
        }
  
    // Attempt removal of Resource using account and name  ..log the Result. 
    component.reload( { accountId: component.getVariable('accountId'), mRN: component.getVariable('mRN'), remove: true } );
    
    component.refresh();
    var dt = component.data;
    console.log('Data Object: ', dt);
    ..
    }

</sxh>      

\\

=== Scene Example: ===

<sxh DSQL; gutter: true;>

 crNavigator.addTrigger('cr_Navigator.btn_ok.Click', function(eventId, data) {
    // Trigger for an Event raised by component button click
    console.log('crNavigator Data: ', data);
    crClusteringTaskList.resetControls(['txt_accountId', 'txt_userId']);
    crClusteringTaskList.reload();
    ..
    ..
    // Access specific component Control  
    var c = aioRemoveMAccount.getControl('txt_accountId');
    aioRemoveMAccount.resetControls();
    aioRemoveMAccount.setVariable('accountId', data);
    c.readOnly = true;
    aioRemoveMAccount.reload();
    ..
});

</sxh>

\\

=== Component Event Triggers ===

All RTAI Components support definition of //Event Triggers//.  These are peices of JavaScript logic that can execute conditionally based on //Canvas//, //Component// or //Application// events.  Currently the application level triggers are not supported.  However a wide range of // Canvas// and //Component// trigger actions can be defined.

\\

=== One Time Triggers ===

The RTAI Component API also suports ''component.addOneTimeTrigger(..)'' method. It fires just like a normal trigger added via ''addTrigger(.)'' but it will only be exeuted once and then removed automatically.  This may be useful in situations where a single action needs to be taken on a component's initialization.

\\

=== Working with Image Resources ===

Example button click trigger to illustrate //Icon Resource// API:

<sxh DSQL; gutter: true;>

function(options, component, control, path, event) {   
  // if we have icon with name 'star' - it's data url will be returned, undefined otherwise
  // console.log(component.getIcon('star')); 
  ..
  // read 'star' icon from library and assign it to button options.
  control.setOption('icon.url', component.getIcon('star')); 
  control.render();
}

</sxh>

\\

=== Component Data Source Options ===

A component may have one or more //Data Source// queries defined that are used to fetch data and perform back-end operations.  Data sources
support several options that control component behavior and data caching.  Components can also be configured to serve their data competley from
//Data Cache// instead of fetching it fro the back-end.  Users can control cache loading behavior expicitly using a combinatyion of ''reload()''
 and ''refresh()''and other methods shown above.

   *  ''Live Control'': Instructs the component to ''autofetch'' data at an interval, specified in seconds. This employs non-blocking polling that can refresh the 
component's data in background, providing a smooth animated transition of values or visual elements.  The ''LED'' control can be added to a components canvas
to alert users when new data is fetched.  Fetching data every 10-15 seconds can be reasonable and will not impact the back-end system even if several hunred users are
accessing the same data concurrently.  At higher user volumes it may make sense to increase the polling period, cache contents that do not change often or deploy a 
cluster of nodes.

   *  ''Autoload'': Tells the control to fetch data immediatley when the user clicks a ''<color #7092be>Reload</color>''' button during development or when the component is first created. This is typically useful for charts or other visual elements that need to present data upon initialization. This setting can be turned off if the component needs to control it's own data fetch strategy.  In these cases, user must call ''compoent.reload()'' explicitly.