Skip to content

Popups

Jump to bottom
Eric edited this page Mar 30, 2020 · 162 revisions

In OGX.JS, Popups are floating boxes with a view in them, they can be drag-able, resize-able, have and icon and buttons. They also can hold one or multiple views and can have tabs. A popup is what would be commonly called in an operating system environment, a window.

Stack

Extends

  Uxi, Touch, Resize

Requires

 Container

Complete stack

  Uxi, Overlay, Loading, Touch, Resize, Container

Configuration

 let config = {
      id:_STRING_, //Required, must be unique
      width:_NUMBER_|_STRING_, //Required, either a number (for pixels) or a percentage 
      height:_NUMBER_|_STRING_, //Required, either a number (for pixels) or a percentage 
      title:_STRING_, //Optional, the title of the popup,
      buttons:_ARRAY_, //Optional, an array of strings or objects    
      tabs:_ARRAY_, //Optional, an array of objects as required for OGX.Tabs
      icon:_STRING_, //Optional, the path to an image to use for the top left icon
      icons:_ARRAY_, //Optional, the array of icons to display in the top right corner
      scroll:_BOOL_, //Optional, if the popup body is scroll-able,
      drag:_BOOL_, //Optional, if the popup is drag-able, 
      resize:_BOOL_, //Optional, if the popup is resize-able, 
      center:_BOOL_, //Optional, if the popup is always centered,
      html:_STRING_, //Optional, some HTML content to add to the body of the popup
      template:_STRINT_, //Optional, HTML content coming from a template stored in Templater
      anim:_STRING_, //Optional, defaults to OGX.Popup.FADE,
      anim_param:_OBJECT_, //Optional, defaults to {scale:0.7}
      overlay:_BOOL_, //Optional, add an overlay, defaults to FALSE
      listen_overlay:_BOOLEAN_, //Optional, defaults to false, if the core should listen for clicks on the overlay and hide it
      zindex:_INT_ //Optional, the z-index of the popup,
      css:_STRING_ //Optional, an css class to be added to the body of the popup,
      view:_OBJECT_, //Optional, a view configuration object
 };

Simple Popup

You can build simple popups without using OML, by using the html or template properties, such as

  "[id]:Popup":{
      "width":INT|STRING(px, %), 
      "height":INT|STRING(px, %), 
      "drag":BOOL, 
      "resize":BOOL, 
      "swipe":BOOL, 
      "show":BOOL,
      "html":"<span>Hello!</span>"
  }

Example - Create a simple popup of 400px x 300px with custom HTML in it, on the current stage.

 app.addPopup({
      id:'MyPopup', 
      width:400, 
      height:300,          
      anim:OGX.Popup.FADE, 
      listen_overlay:false,
      html:'<p>Some HTML content</p>'
  });

Example - Create a simple popup of 400px x 300px with a HTML template, from an Uxi

 this.create(OGX.Popup.NAME, {
      id:'MyPopup', 
      width:400, 
      height:300,          
      anim:OGX.Popup.FADE, 
      template:'MyPopupTemplate'
  });

Note that the addPopup method is only available on the app object

OML

To create more complex Popups, you can use the node:OML property and pass it an OML tree. Popups only generate a single placeholder. Configuration for 1 View in the body

 "[id]:Popup":{
      "width":INT|STRING(px, %), 
      "height":INT|STRING(px, %), 
      "drag":BOOL, 
      "resize":BOOL, 
      "swipe":BOOL, 
      "show":BOOL,
      "node:OML":[{
             "default:Html":{
                  html:"<span>Hello!</span>"
              }
       }]
  }

You can also use OML to generate multiple placeholders for this popup via a Container. Here we create at runtime a popup on current stage

 app.create(OGX.Popup.NAME, {
      id:'myPopup',
      "width":200, 
      "height":300,         
      "node:OML":[{
             "default:Container":{
                  "tabs":false,
                  "node:OML":[
                        {"default:Html":{
                             html:"<span>Hello!</span>"
                        }},
                        {"default:Html":{
                             html:"<span>Welcome!</span>"
                        }},
                   ]
              }
       }]
 });

Buttons

Set Buttons

You can add buttons to your popup either by passing an array of strings (labels of buttons) or an array of objects. If you use strings, you will need to listen to the events of the popup, such as

  app.addPopup({
     ...
     buttons:['OK', 'Cancel']
  });

  $(document).on(OGX.Popup.CLICK_BUTTON, function(__event, __data){
      console.log(__data); //logs {index:_INT_, value:_STRING} where index is the button index and value its label
   });

If you'd rather not listen to events and have a callback called when the button is hit instead, do

  app.addPopup({
     ...
     buttons:[{label:'OK', callback:myFunction}, {label:'Cancel', callback:otherFunction}]
  });

  function myFunction(){ ... }
  function otherFunction(){ ... }

You can also add custom parameters to your callbacks per button, which are going to be passed to the callback functions such as

  app.addPopup({
     ...
     buttons:[{label:'OK', callback:myFunction, params:true}, {label:'Cancel', callback:otherFunction, params:false}]
  });

A click on the OK button of the popup will call myFunction and pass it true

Update Buttons

You can at any time update the buttons of your popup by doing

 app.find('Popup', _POPUP_NAME_).setButtons(_ARRAY_);

Enable/Disable

You can enable/disable the buttons of the popup by doing

 app.find('Popup', _POPUP_NAME_).enableButtons();
 app.find('Popup', _POPUP_NAME_).disableButtons();

Scroll

Popups can also be scroll-able, just like views. It is recommended to use the scroll component of the popup if the content of your popup will be a simple HTML or a template (without a view to interact with the display). If you need to have a view instanced in the popup, it is then recommended to enable the scroll at view level instead.

Resize

Popups can be resized with 2 anchors at the bottom of the popup, one of the bottom-left side and one on the bottom right side. They can also be resized with code (the resize:true flag is not needed to resize by code):

app.resizePopup(_NAME_, _WIDTH_, _HEIGHT_);

Tabs

Popups can also be tabbed and hold multiple views. It uses Tabs and Carousel to create tabs and containers, and binds them together. If you wish to use tabs, you must pass a tabs array as well as a views array, such as

 this.create(OGX.Popup.NAME, {
      id:'popup',
      //... 
      tabs:[{label:'Profile'}, {label:'Security'}],
      views:[
           {name:'Profile', template:'Profile', observe:false},
           {name:'Security', template:'Security', observe:false}
      ]
 });

To retrieve an object (such as a View) from a Popup, do

 app.find(OGX.Popup.NAME, 'my_popup').find(OGX.View.NAME, 'MyView');

Or you can also look that view up from a parent Uxi

 this.find(OGX.View.NAME, 'MyView');

Icons

Popups can have a multiple icons. The top left corner icon of the popup is set with the property icon of the config (path to icon file). It is optional. You can also add interactive icons in the top right corner of the popup, by passing an array of icons such as:

 let config = {..., icon:'path_to_image', icons:[
     {icon:'path_to_imageA', callback:_FUNCTION_},
     {icon:'path_to_imageB', callback:_FUNCTION_},
 ]};

The function linked to the callback parameter will be called when the end user hits it.

Exists

Check if a popup already exists on the stage in use

 app.popupExists(_NAME_);

Find

Like any other components, you can look them up using the find method. To look up at the app level

 app.find(OGX.Popup.NAME, 'my_popup');

To lookup from within where the Popup was instanced

 this.find(OGX.Popup.NAME, 'my_popup');

You can also use the value of the static

 this.find('Popup', 'my_popup');

Hide/Show

You can hide or show a popup by finding it and then calling the method. If you created the popup within a Uxi then you can directly look it up, otherwise you can use the app object to lookup the popup over the entire application.

 this.find(OGX.Popup.NAME, 'my_popup_id').show();
 app.find(OGX.Popup.NAME, 'my_popup_id').show();

If you are reusing the popup

 let popup = this.find(OGX.Popup.NAME, 'my_popup_id');
 popup.hide();

You can also hide and show popups without removing them, in the case you have a workflow with multiple popups and you wish to switch from one to the other.

app.hidePopup(_NAME_, _CALLBACK_, _PARAMS_);
app.showPopup(_NAME_, _CALLBACK_, _PARAMS_);

To retrieves a list of names of visible popups on the current stage, do

app.getVisiblePopups();

Anim

You can show/hide using an animation (or not). Only 2 animations are supported for now: OGX.Popup.FADE and OGX.Popup.SCALE, that you should set in the config of the Popup, such as

 {
      ..., 
      anim: OGX.Popup.FADE |OGX.Popup.SCALE | false
 }

OGX.Popup.SCALE can be adjusted via an additional parameter anim_param, which determines the scaling factor of the animation, and defaults to 0.7

 {
      ..., 
      anim: OGX.Popup.SCALE,
      anim_param:{scale:0.7}
 }

Move

app.centerPopup(_NAME_);
app.movePopup(_NAME_, _X_, _Y_);

Note that is your popup has center set to true, the popup will always recenter on its own. Also note that if the popup size was initially defined as a relative value (%), then the popup will also resize when the interface resizes.

Remove

You can lookup and remove a popup from the app object

 app.removePopup(_NAME_, _ANIMATION_, _CALLBACK_, _CB_PARAMS_);

Deleting a popup will also call the destroy method of any view embedded inside the popup. Note that if you want to remove a popup with no animation, you can pass false or OGX.Popup.NOANIM. If no animation value is passed, the popup will be removed reusing the animation used to show that popup.

Clone this wiki locally