Popups - globules-io/OGX.JS GitHub Wiki
In OGX.JS, Popups are floating boxes with a view in them, they can be drag-able, resize-able, have an 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.
Extends
Uxi, Touch, Resize
Requires
Container
Complete stack
Uxi, Overlay, Loading, Touch, Resize, Container
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
min_width:_NUMBER_ //Optional, if resizable, the min width in pixels
min_height:_NUMBER_ //Optional, if resizable, the min height in pixels
max_width:_NUMBER_ //Optional, if resizable, the max width in pixels
max_height:_NUMBER_ //Optional, if resizable, the max height in pixels
x:_NUMBER_, //Optional, the x position at start
y:_NUMBER_, //Optional, the x position at start
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,
keep_ratio:_BOOL_, //Optional, if the popup will keep its aspect ratio when resizing,
center:_BOOL_, //Optional, if the popup is always centered,
maximize:_BOOL_, //Optional, if the popup can be maximized
maximize_dbc : _BOOL_, //Optional, if the popup can be maximized on double click of the head
group:_STRING_, //Optional, if group name for merging popups
group_icon: _STRING_, //Optional, if a group has a default icon
html:_STRING_, //Optional, some HTML content to add to the body of the popup
template:_STRING_, //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}
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,
delay_oml:_BOOL_, //Optional, if set, the OML content will be rendered in the next thread
};
You can build simple popups without using
OML
, by using thehtml
ortemplate
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:'fade',
html:'<p>Some HTML content</p>'
});
Example - Create a simple popup of 400px x 300px with a HTML template, from an
Uxi
this.create('Popup', {
id:'MyPopup',
width:400,
height:300,
anim:'fade',
template:'MyPopupTemplate'
});
Same as above but using
app.addPopup
passing theUxi
to create from, as parameter
app.addPopup({
id:'MyPopup',
width:400,
height:300,
anim:'fade',
template:'MyPopupTemplate'
}, this);
Note that the
addPopup
method is only available on theapp
object
Popup supports size expressions. Size can be passed as number or string (with or without unit). For more info about this, check out the Data component.
width:'300px|600|100%';
You can also change the size on the fly by doing
my_popup.width(500);
my_popup.height(600);
You can also specify an anim flag and a callback
my_popup.height(600, true, () => { ... });
You can retrieve a dimension by using the
width
orheight
method with parameters. Note that if you used a size expression, it will return the size expression. To get the computed size, usemy_popup.el.width()
ormy_popup.el.height()
.
To create more complex Popups, you can use the
node:OML
property and pass it anOML
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('Popup', {
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>"
}},
]
}
}]
});
If you are storing the
OML
content of your popup
app.addPopup({
id:'myPopup',
"width":200,
"height":300,
'node:OML':'{{oml myFile}}'
});
You can add buttons to your popup by passing an array of objects.
app.addPopup({
...
buttons:[{label:'OK'}, 'label':'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
You can at any time update the buttons of your popup by doing
app.cfind('Popup', _ID_).buttons(_ARRAY_);
Also retrieve the current buttons
app.cfind('Popup', _ID_).buttons();
You can enable/disable the buttons of the popup by doing
app.cfind('Popup', _ID_).enableButtons();
app.cfind('Popup', _ID_).disableButtons();
or by targeting a single button passing its zero-based index
app.cfind('Popup', _ID_).enableButton(0);
app.cfind('Popup', _ID_).disableButton(0);
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.
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(_ID_, _WIDTH_, _HEIGHT_);
To have a popup take the entire width and height of its parent
app.cfind('Popup', __ID__).maximize();
To restore a popup to its former size (size before
maximize
)
app.cfind('Popup', __ID__).normalize();
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('Popup', {
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.cfind('Popup', 'my_popup').find('View', 'MyView');
Or you can also look that view up from a parent
Uxi
this.find('View', 'MyView');
Note that
cfind
uses the app's cache, whilefind
lookups down the tree of an object's nodes
You can get/set the title at anytime using the
title
method
myPopup.title('new title');
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.
You can also get/set icons on the fly using the
icons
method
myPopup.icons([{icon:'path_to_imageA', callback:_FUNCTION_},{icon:'path_to_imageA', callback:_FUNCTION_}]);
Check if a popup already exists on the stage in use
app.popupExists(_ID_);
Like any other components, you can look them up using the
find
method. To look up at the app level
app.find('Popup', 'my_popup');
To retrieve directly from the app's cache
app.cfind('Popup', 'my_popup');
To lookup from within where the Popup was instanced
this.find('Popup', 'my_popup');
You can also use the value of the static
this.find('Popup', 'my_popup');
app.find('Popup', 'my_popup');
app.cfind('Popup', 'my_popup');
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 theapp
object to lookup the popup over the entire application.
this.find('Popup', 'my_popup_id').show();
app.cfind('Popup', 'my_popup_id').show();
If you are reusing the popup
let popup = this.find('Popup', '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(_ID_, _CALLBACK_, _PARAMS_);
app.showPopup(_ID_, _CALLBACK_, _PARAMS_);
To retrieves a list of names of visible popups on the current stage, do
app.getVisiblePopups();
You can show/hide using an animation (or not). Only 2 animations are supported for now:
OGX.Popup.FADE
andOGX.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 parameteranim_param
, which determines the scaling factor of the animation, and defaults to 0.7
{
...,
anim: OGX.Popup.SCALE,
anim_param:{scale:0.7}
}
Note that you can also use the value of the constant, such as
'fade'
or'scale'
, using the constant is recommended in case of future changes.
app.centerPopup(_ID_);
app.movePopup(_ID_, _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.
You can lookup and remove a popup from the
app
object
app.removePopup(_ID_, _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
orOGX.Popup.NOANIM
. If no animation value is passed, the popup will be removed reusing the animation used to show that popup.
OGX.Popup.HIDE;
OGX.Popup.SHOW;
OGX.Popup.CLOSE;
OGX.Popup.GROUP;
OGX.Popup.UNGROUP;