Skip to content

Popups

Jump to bottom
Eric edited this page Sep 28, 2018 · 162 revisions

In OGX.JS, Popups are floating boxes with a view in them, they can be draggable, have and icon and buttons. A popup is what would be commonly called in an operating system environment, a window.

Popups are parts of the core, have a size and a view. For the following documentation consider app being an instance of Core.

Instantiate

 let config = {
      name:_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    
      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
      scroller:_BOOL_, //Optional, if the popup contains a scroller     
      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.MobileCore.POPUP_FADE 
      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
 };

 app.addPopup(config);

Example - Create a simple popup of 400px x 300px with custom HTML in it

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

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

 app.addPopup({
      name:'MyPopup', 
      width:400, 
      height:300,          
      anim:OGX.Popup.POPUP_FADE, 
      overlay:true,
      listen_overlay:false,
      template:'MyPopupTemplate'
  });

Example - Create a popup of 400x300px, pass it a view 'MyView', with an empty object, a fade animation and ignore user interactions on the underlying overlay (tapping the overlay won't do anything).

 app.addPopup({
      name:'MyPopup', 
      width:400, 
      height:300,          
      anim:OGX.Popup.POPUP_FADE, 
      listen_overlay:false,
      view:{name:'MyView', scroll:false, observe:false}, 
  });

Same but with percent instead

 app.addPopup({
      name:'MyPopup', 
      width:'80%',
      height:'80%',           
      anim:OGX.App.POPUP_FADE, 
      listen_overlay:false,
      view:{name:'MyView', scroll:false, observe:false}, 
 });

It is important to remember that HTML content can be injected either at popup level or view level, same remark for scrollers. In the following example, the HTML content and the scroller are at view level inside a popup

 app.addPopup({
      name:'MyPopup', 
      width:'80%',
      height:'80%',           
      anim:OGX.App.POPUP_FADE, 
      listen_overlay:false,
      view:{name:'MyView', template:'SomeTemplate', scroll:true, observe:false}, 
 });

But we could also have used the built in scroller and have the template at popup level, it all depends on how your view is architeched.

  app.addPopup({
      name:'MyPopup', 
      width:'80%',
      height:'80%',           
      anim:OGX.App.POPUP_FADE, 
      listen_overlay:false,
      template:'SomeTemplate', 
      scroll:true,
      view:{name:'MyView', scroll:false, observe:false}, 
 });

Note that using scrollers at view level is only useful when you have multiple views in the same popup. Otherwise, if your popup only contains 1 view then you should use the popup scroller instead.

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

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.

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.

Add/Remove views

To add a view to a popup

 app.addToPopup(
      {
          name: _POPUP_NAME, //Required, String, name of the popup
          view: _VIEW_, //Required, Object, config object of the view
          data: _OBJECT_, //Object, the data object for the view, optional
          container: _SELECTOR_ //String, optional. The container where the view is going to be append to, i.e. '#mydiv'. Defaults to '.ogx_popup_body:first'
      }
  );

If the container is not set, the default view for the popup will be used. But if your popup was instantiated with HTML content, and you wish to create a view inside the HTML element (corresponding to the selector '.my_selector'), do

 app.addToPopup(
      {
          name:'MyPopup', 
          view: {name:'MyView', scroll:true|false, observe:true|false},
          container:'.my_selector'
      }
  );

To remove a view from a popup

 app.removeFromPopup(_POPUP_NAME_, _SELECTOR_);

For instance, remove the view that was instanced in the popup at the default container

 app.removeFromPopup('MyPopup');

To remove a specific view in a specific container

 app.removeFromPopup('MyPopup', '.my_selector');

Exists

Check if a popup already exists on the stage in use

 app.popupExists(_NAME_);

Hide/SHow

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_);
app.showPopup(_NAME_);

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

app.getVisiblePopups();

Resize

app.resizePopup(_NAME_, _WIDTH_, _HEIGHT_);

Move

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

Remove

 app.removePopup(_NAME_, _ANIMATION_);

Deleting a popup will also call the destroy method of any view embedded inside the popup.

Clone this wiki locally