
~~Title: Overlay Panels~~

<html><font color=#990000 size="+2"><b>Overlay Panels</b></font></html>

The <color #00a2e8>Knowledge Works™</color> environment lets //components// be treated as interactive, swizzable overlay panels similar to //Windows Dialogs// in a standard Desktop Application. A full component life cycle with animation and Modal Control is available for Overlay Panels.  Any canvas component can be turnd into an overlay panel and displayed on top of an //Application Scene// (dashboard screen). Panels may be draggable, resizable and several panels may be opened at once as consequence of a control action.

====Overalay Panel API====

Overlay panels support a number of properties that provide appearance, behavior and animation. Panels are //singleton// entities and initialized only once for optimization. Panel behavior, positon and visualization can be controlled by passing a literal or a JSON object with configuration properties:

\\
           * ''<color #7092be>horizontalPosition</color>'': Positions the overlay based on dimensions of browser area.  Possible settings are { 'center' | 'left' | 'right' }

           * ''<color #7092be>verticalPosition</color>'':   Positiond the overlay based on dimensions of browser are. Possible settings are { 'top' | 'bottom' | 'center'}
    
           * ''<color #7092be>padding</color>'': Screen layout padding, expressed a percentage.  For exapmle 11%.  Currently the only way to control Panel Dimensions.

           * ''<color #7092be>width</color>'': Absolute width of Panel in pixels.  For example 500px.  This is currently overriden by padding settings.

           * ''<color #7092be>height</color>'':  Absolute heigh of Panel in pixels.  For example 500px.  This is currently overriden by padding settings.

           * ''<color #7092be>closeButton</color>'': Display the close button in upper right corner, providing a Lightbox style view.
            
           * ''<color #7092be>mask</color>'' Controls shadow mask, where background is dimmed to emphasize the panel content. { 'true' | 'false' } where //true// means 0.3 opaqueness.  Or may be specificed as an opaque value 0-1.

           * ''<color #7092be>blur</color>'': Controls background blurring.  May be { true | false }

           * ''<color #7092be>desaturate</color>'': Controls color saturation of background.  May be { true | false }

\\

           *  ''component.hide()'': Closes, but does not destroy the panel.  You need to ''component.reset()'' or ''component.reload()'' if you need to reset the content.
      
           *  ''component.show()'': Opens and displays the panel.  

\\

<sxh DSQL; gutter: true;>

myCmp.show( 
  {
      horizontalPosition: 'center', // 'left' / 'right'
      verticalPosition: 'center', // 'top' / 'bottom'
      padding: 50, // '10%'
      width: '100%', // 200 / '50%'
      height: '100%', // 200 / '50%'
      // options above fixed to work as expected especially width/height. positions make difference if size of overlay less then 100%
      closeButton: true,
      mask: true, // true / false -- mask rewritten to not move altogether with overlay, but fade in independently on fixed position
      blur: true,
      desaturate: true,
      // options below added
      draggable: false,
      resizable: false,
      borderWidth: 1,
      borderColor: 'rgba(255, 255, 255, 0.4)', //'#FF0000' or rgba(255,0,0,0.5)
      componentColor: 'rgba(0, 0, 0, 0.3)', //'#FF0000' or rgba(255,0,0,0.5)
      borderRadius: 0, // 0-50
      shadowColor: 'rgba(0,0,0,0)', //'#FF0000' or rgba(255,0,0,0.5)
      shadowWidth: 0,
      animation: 'fade-in',
      /* supported animations:
        slide-in-down
        slide-in-left
        slide-in-up
        slide-in-right
        fade-in
        hinge-in-from-top
        hinge-in-from-right
        hinge-in-from-bottom
        hinge-in-from-left
        hinge-in-from-middle-x
        hinge-in-from-middle-y
        scale-in-up
        scale-in-down
        spin-in
        spin-in-ccw
      */
      animationSpeed: 'fast', // 'slow' / 'normal' / 'fast'
      animationTimimg: 'ease-in-out',
      /* supported timings:
        linear
        ease
        ease-in
        ease-out
        ease-in-out
        bounce-in
        bounce-out
        bounce-in-out
      */ 
  }
)

</sxh>

\\

====Registering Events====

An application (Scene) may register <i>Event Triggers</i> upon initialization.  The so-called OnReady(..) event fires when the Scene initializes.  This 
allow users to register triggers for Events that are raised by canvas components or overlay components that may be loaded by various controls or 
operations such as button clicks, menu, icon selection or chart actions. 

<sxh DSQL; gutter: true;>
console.log('ONREADY:', {components,dashboard}); 

// Register Event Trigger for a for a Standard Component Event raised by RTAI Framework
myComponent.addTrigger('chartClick', function(evt, data) { 
   console.log('Chart Click Event: ', event);
  // Set variable for an Overlay Component
  crDocument.setVariable('sourceDoc', "Source Document Id: " + event.data.value[2]);
  crDocument.reload({docId:event.data.value[2]});
  crDocument.show();  
});

// Register a Trigger for Custom Events raised by UI Controls
crNavigatorV2.addTrigger('cr_Navigator_v2.btn_brain.Click', function(eventId, data) {
    console.log('crNavigatorV2 Data: ', data);
    crClusteringTaskList.reload();
    crClusteringTaskList.show();
});

</sxh>

In this example we have two types of events being subsrcibed to.  One on standard RTAI Events that are generated by the EChart framework
and another on Custom Events whose Event Id ''cr_Navigator_v2.btn_brain.Click'' is defined by the user.  The difference between the types of
events is that Frameowrk Event Id are generated by the framework, and their ''data'' payload will reference Data Series and other Component
elements, whereas Custom Eventds pass data relevant to the IO Controls as par of their payload, and users can set any valid value as Event Id.

====Passing Values to Overlay Component====


<sxh DSQL; gutter: true;>
  ..
  ..
   components.details.instance.patchOptions = {
     vars:{
       buttonText:event.data.name,
       buttonValue:event.data.value,
       inputValue:'hello world..' 	      // Shared Variable linked to Input Value
     }};
   components.details.instance.reload();      // Reload Component Instance using the Options
  ..     
  ..
</sxh>

<WRAP left round info 100%>
This API syntax may change in the comin versions but operation squence remains the same.
</WRAP>
<WRAP clear/>

====Passing Data Source Parameters to Overlay Component====

In this example we reload the Instance and pass a Datasource Parameter to it.


<sxh DSQL; gutter: true;>
  ..
  ..
  // reload with datasource parameters object as argument 
  components.details.instance.reload({myDatasourceParm_1:event.data.name});
  ..
  ..
</sxh>  

In this case ''myDatasourceParm_1'' is the name of the Data Source Function or Query
parameter.  The names must match.  

====Triggering Panel Reload and Visibility====

Listeners can triger actions in Overlay Panel Components

<sxh DSQL; gutter: true;>
  ..
  ..
  components.details.instance.on('myComponent.click', function(eventName, options, control, path, event) {
    console.log('COOL CLICK:',eventName, options, control, path, event);
  });
  
  ..
  ..
</sxh>


====Overlay Panel Life Cycle Control====

Overlay Panels can be triggered conditionally using a timer. This allows you to control the life cycle of an overlay panel, for example to shpw the
panel for a limited period of time such as an Alert, or Real-Time Assistance Pop-Up that instructs or guides the user based on event-riven logic.

<sxh DSQL; gutter: true;>
..
   components.details.instance.reload({i:event.data.name});
   dashboard.showOverlay('details');

  _.delay(function(){
     dashboard.hideOverlay('details');
  },3000); 					// 3sec
..
</sxh>


=== Controlling Overlay Panel Behavior ===

<sxh DSQL; gutter: true;>
  dashboard.showOverlay('MyWindow', {
      horizontalPosition: 'center', 	// { 'center' | 'left' | 'right' }
      verticalPosition: 'center', 	// 'top' / 'bottom'
      padding: 50, 			// '10%'
      width: undefined, 		// Pixels orPercent - 200, '50%'
      height: undefined, 		// Pixels or Percent - 200, '50%'
      closeButton: true,
      mask: true, 			// Controls shadow mask - true means 0.3
      blur: true, 			// Controls background blurring { true | false }
      desaturate: true, 		// Controls color saturation of background
    });

</sxh>

=== Checking for Component Load Errors ===

<sxh DSQL; gutter: true;>
// Assuming myComponent is a Desktop component like Pie Chart or Sankey
if(myComponent.error) {
  console.log('oh no, it failed..', mycmp);
} else {
  // do your stuff
}

</sxh>
