-
Notifications
You must be signed in to change notification settings - Fork 4
Popups
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.
Extends
Uxi, Touch, Resize
Requires
Container
Complete stack
Uxi, Overlay, Loading, Touch, Resize, Container
Popups only generate a single placeholder. Configuration for 1 View in the body
"[name]:Popup":{
"width":INT|STRING(px, %),
"height":INT|STRING(px, %),
"drag":BOOL,
"resize":BOOL,
"swipe":BOOL,
"show":BOOL,
"default:View":OML (Object)
}
Configuration to hold multiple Views via a Container
"[name]:Popup":{
...,
"default:Container":OML (Array)
}
You can also create a Popup during runtime
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.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,
style:_CONSTANT_, //Optional, the style of popup
};
this.addPopup(config);
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.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.addPopup({
id:'MyPopup',
width:400,
height:300,
anim:OGX.Popup.POPUP_FADE,
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).
this.addPopup({
id:'MyPopup',
width:400,
height:300,
anim:OGX.Popup.POPUP_FADE,
view:{name:'MyView', scroll:false, observe:false},
});
Same but with percent instead
this.addPopup({
id:'MyPopup',
width:'80%',
height:'80%',
anim:OGX.App.POPUP_FADE,
view:{name:'MyView', scroll:false, observe:false},
});
Using
OML
this.addPopup({
id:'MyPopup',
width:'80%',
height:'80%',
anim:OGX.App.POPUP_FADE,
listen_overlay:false,
'node:OML':[
{'default:Views.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
this.addPopup({
id:'MyPopup',
width:'80%',
height:'80%',
anim:OGX.App.POPUP_FADE,
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.
this.addPopup({
id:'MyPopup',
width:'80%',
height:'80%',
anim:OGX.App.POPUP_FADE,
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.
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
this.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
this.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
this.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
this.getPopup(_POPUP_NAME_).setButtons(_ARRAY_);
You can enable/disable the buttons of the popup by doing
this.getPopup(_POPUP_NAME_).enableButtons();
this.getPopup(_POPUP_NAME_).disableButtons();
If you want to have a head-less popup
{.., style:OGX.Popup.STYLE_NONE, ...}
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):
this.resizePopup(_NAME_, _WIDTH_, _HEIGHT_);
Popups can also be tabbed and hold multiple views. It uses OGX.Tabs and OGX.ViewSwiper 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.addPopup({
id:'popup',
//...
tabs:[{label:'Profile'}, {label:'Security'}],
views:[
{name:'Profile', template:'Profile', observe:false},
{name:'Security', template:'Security', observe:false}
]
If you then want to get the instance of the current/displayed view, do
this.getPopupView('popup');
To get the instances of all views
this.getPopupViews('popup');
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.
To add a view to a popup
this.addToPopup(_NAME_, _VIEW_);
Example
this.addToPopup('myPopup',
{
id: 'VIews.MyView',
data:{id:123},
observe:false
}
);
By default, the view's container will be the body of the popup. If you wish to add a view to a specific element of the popup up, you can specify the container
this.addToPopup('myPopup',
{
name: 'MyView',
data:{id:123},
container:'#some_element',
observe:false
}
);
To remove a view from a popup
this.removeFromPopup(_POPUP_NAME_, _SELECTOR_);
For instance, remove the view that was instanced in the popup at the default container
this.removeFromPopup('MyPopup');
To remove a specific view in a specific container
app.removeFromPopup('MyPopup', '.my_selector');
Check if a popup already exists on the stage in use
this.popupExists(_NAME_);
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.
this.hidePopup(_NAME_);
this.showPopup(_NAME_);
To retrieves a list of names of visible popups on the current stage, do
this.getVisiblePopups();
this.centerPopup(_NAME_);
this.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.
this.removePopup(_NAME_, _ANIMATION_);
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.
- Welcome
- Changelog
- Structure
- Configuration
- Getting started
- CLI
- Poly
- Core
- Templating
- Routing
- Controllers
- Components
- Extra Components
- Helpers
- Styling
- Debugging