The popup component handles creating and managing pop-up windows.
By default, all elements with the data-role="popup"
attribute are displayed as Tizen Web UI popups.
To manually create a button component, use the component constructor from the tau
namespace (RECOMMENDED):
<div id="popup"> <p>This is a completely basic popup, no options set.</p> </div> <script> var popupElement = document.getElementById("popup"), popup = tau.widget.Popup(popupElement); popup.open(); </script>
If the jQuery library is loaded, you can use its method (support for backward compatibility):
<div id="popup"> <p>This is a completely basic popup, no options set.</p> </div> <script> var popup = $("#popup").popup(); popup.popup("open"); </script>
If the link has the data-position-to="window" option in the popup, the popup is opened to a new window after clicking.
<!--Definition of the link, which opens the popup and sets its position--> <a href="#center_info" data-position-to="window">Click to open popup</a> <!--Definition of the popup, which inherits property position from link--> <div id="center_info" data-role="popup" class="center_info"> <div class="ui-popup-text"> <p>Pop-up dialog box, a child window that blocks user interaction to the parent windows</p> </div> </div>
<a href="#center_title_1btn" data-position-to="window">Click to open popup</a> <!--Definition of popup with a title and button--> <div id="center_title_1btn" data-role="popup" class="center_title_1btn"> <div class="ui-popup-title"> <h1>Popup title</h1> </div> <div class="ui-popup-text"> Pop-up dialog box, a child window that blocks user interaction to the parent windows </div> <div class="ui-popup-button-bg"> <a data-role="button" data-rel="back" data-inline="true">Button</a> </div> </div>
A menu can be created by placing a list view component inside a popup.
<a href="#center_liststyle_1btn" data-position-to="window">Click to open popup</a> <div id="center_liststyle_1btn" data-role="popup" class="center_liststyle_1btn"> <div class="ui-popup-title"> <h1>Popup title</h1> </div> <div class="ui-popup-scroller-bg" data-scroll="y"> <ul data-role="listview" data-icon="1line-textonly"> <li><a href="#">List item 1</a></li> <li><a href="#">List item 2</a></li> </ul> </div> <div class="ui-popup-button-bg"> <a data-role="button" data-rel="back" data-inline="true">Cancel</a> </div> </div>
If the id
property is set in the link and the data-position-to="origin"
option in the popup, the context popup is opened after clicking.
<!--Definition of the link, which opens a popup with popup id in context style with an arrow--> <a href="#popup" id="linkId" data-position-to="origin" data-role="button" data-inline="true">Click to open context popup</a> <div id="popup" data-role="popup"> <p>This is a completely basic context popup, no options set.</p> </div>
The positionTo
option has the "origin"
value in the popup by default. However, the positionTo
property is inherited from the related link and the inherited value has a higher priority during the opening process and overwrites the previous value. So, if you do not change it in the popup and do not set the data-position-to
value to other than "origin"
in the link, the popup connected with the link is always opened in the context style.
To make sure that the popup is opened in the context style with an arrow, set the data-position-to="origin"
property as well as id
as in the example above.
The same result can be achieved by setting the id
property only and not setting the positionTo
option in the link. This is because the popup has the "origin"
value for the positionTo
option by default.
<!--In link, id is set--> <a href="#popup" id="linkId" data-role="button" data-inline="true">Click to open context popup</a> <div id="popup" data-role="popup"> <p>This is a completely basic popup, no options set.</p> </div>
After building the popup, the value of the positionTo
option can be changed by using the option
method:
<a href="#popup" id="linkId" data-role="button" data-inline="true">Click to open context popup</a> <div id="popup" data-role="popup"> <p>This is a completely basic popup, no options set.</p> </div> <script> // Change value of positionTo option by option method var popupWidget = tau.widget.Popup(document.getElementById("popup")); popupWidget.option("positionTo", "origin"); </script>
<a href="#popup" id="linkId" data-role="button" data-inline="true">Click to open context popup</a> <div id="popup" data-role="popup"> <p>This is a completely basic popup, no options set.</p> </div> <script> // Change value of positionTo option by option method $("#popup").popup("option", "positionTo", "origin"); </script>
The context popup can also be created manually for elements other than a link by pushing the options, such as positionTo
and link
to the _open
method:
<!--Element with no properties - popup is opened next to it in context style manually--> <div id="linkId">Click to open context popup</div> <div id="popup" data-role="popup"> <p>This is a completely basic popup, no options set.</p> </div> <script> // Set opening popup on click event document.getElementById("linkId").addEventListener("click", function () { // Open context popup var popupWidget = tau.widget.Popup(document.getElementById("popup")); // Open with options popupWidget.open({link: "linkId", positionTo: "origin"}); }); </script>
<!--Element with no properties - popup is opened next to it in context style manually--> <div id="linkId">Click to open context popup</div> <div id="popup" data-role="popup"> <p>This is a completely basic popup, no options set.</p> </div> <script> // Set opening popup on click event $("#linkId").on("click", function () { // Open with options $("#popup").popup("open", {link: "linkId", positionTo: "origin"}); }); </script>
These options can be also set globally, and then the open
method can be called without options:
<!--Element with no properties - popup is opened next to it in context style manually--> <div id="linkId">Link for popup</div> <div id="popup" data-role="popup"> <p>This is a completely basic popup, no options set.</p> </div> <script> // Set options var popupWidget = tau.widget.Popup(document.getElementById("popup")); popupWidget.option({positionTo: "origin", link: "linkId"}); // here we set positionTo and id of link, which sets placement of popup // Set opening popup on click event document.getElementById("linkId").addEventListener("click", function () { // If options are set, call open method without options popupWidget.open(); }); </script>
<!--Element with no properties - popup is opened next to it in context style manually--> <div id="linkId">Link for popup</div> <div id="popup" data-role="popup"> <p>This is a completely basic popup, no options set.</p> </div> <script> // Set positionTo option $("#popup").popup("option", "positionTo", "origin"); // Set opening popup on click event $("#linkId").on("click", function () { // For jQuery API, link has to be added as an option $("#popup").popup("open", {link: "linkId"}); }); </script>
Option | Input type | Default value | Description |
---|---|---|---|
data-close-link-selector | string | 'a[data-rel="back"]' | Selector for the buttons in the popup. |
data-direction-priority | Array | "bottom","top", "right", "left" | Directions of the popup placement by priority. First one has the highest priority, last one the lowest. |
data-history | boolean | false | Sets whether the URL is altered when the popup is open to support the back button. |
data-position-to | string | "origin" | Element relative to which the popup is centered. |
data-shadow | boolean | true | Sets whether a shadow is drawn around the popup. |
data-tolerance | Object | {t: 10, r: 10, b: 10, l: 10} | Minimum distance from the edge of the window for the corresponding edge of the popup. |
data-transition | string | "pop" | Default transition for the popup. |
To handle popup events, use the following code:
<!--Popup HTML code--> <div id="popup" data-role="popup"> <p>This is a completely basic popup, no options set.</p> </div> <script> // Use popup events var popup = document.getElementById("popup"); popup.addEventListener("popupafteropen", function() { // Implement code for popupafteropen event }); </script>
Name | Description |
---|---|
popupafteropen | Triggered when process of opening a popup is completed. |
beforeposition | Triggered before a popup computes the coordinates where it appears. |
popupafterclose | Triggered when the process of closing a popup is completed. |
To call a method on the component, use one of the existing APIs:
TAU API (RECOMMENDED):
var popupElement = document.getElementById("popup"), popup = tau.widget.Popup(popupElement); popup.methodName(methodArgument1, methodArgument2, ...);
jQuery API (support for backward compatibility):
$(".selector").popup("methodName", methodArgument1, methodArgument2, ...);
Method | Description |
---|---|
* option ( string | Object? name, * value ) |
Gets and sets component options. |
Popup refresh ( Object? options, number? options.positionX, number? options.positionY ) |
Refreshes the position of the opened popup. |
Open ( Object? options ) |
Opens the popup. |
Close ( Boolean immediate ) |
Closes the popup. |
setPositionCB ( Function callback )- deprecated |
Sets a callback, which is called on the |
setPositionCallback ( Function callback ) |
Sets a callback, which is called on the |
option
Gets and sets component options.
* option ( string | Object? name, * value)
The method can work in many contexts:
Parameters:
Parameter | Type | Required/optional | Default value | Description |
---|---|---|---|---|
name | string | Object | Optional | Name of the option. | |
value | * | Required | Value to set. |
Return value:
Type | Description |
---|---|
* | Return value of the option or undefined if method is used to set a value. |
Code example (TAU API RECOMMENDED):
<div id="popup" data-role="popup"> <p>This is a completely basic popup, no options set.</p> </div> <script> var popupWidget = tau.widget.Popup(document.getElementById("popup")), optionValue; optionValue = popupWidget.option("positionTo"); // Read positionTo value popupWidget.option("positionTo", "window") // Set value </script>
Code example (jQuery API support for backward compatibility):
<div id="popup" data-role="popup"> <p>This is a completely basic popup, no options set.</p> </div> <script> optionValue = $("#popup").popup("option", "positionTo"); $("#popup").popup("option", "positionTo", "window"); </script>
refresh
Refreshes the position of the opened popup.
Popup refresh ( Object? options)
In case of the context popup, the position of the arrow is not changed after calling this method. If the new position of the popup content causes disconnection from the arrow, the popup position is corrected automatically. Popup content is always set so that the arrow is placed between the left and right side of the popup container with a proper margin set in the data-tolerance
option.
Parameters:
Parameter | Type | Required/optional | Default value | Description |
---|---|---|---|---|
options | Object | Optional | Options. |
The options object contains the following values:
Name | Type | Description |
---|---|---|
options.positionX | number | Desired horizontal coordinate of the center point in the popup in pixels (it only works if both coordinates are set - top and left). |
options.positionY | number | Desired vertical coordinate of the center point in the popup in pixels (it only works if both coordinates are set - top and left). |
Return value:
Type | Description |
---|---|
Popup | Returns this. |
Code example (TAU API RECOMMENDED):
<div id="popup" data-role="popup"> <p>This is a completely basic popup, no options set.</p> </div> <script> var popupWidget = tau.widget.Popup(document.getElementById("popup")); popupWidget.refresh(); // Only refresh original position </script>
Code example (jQuery API support for backward compatibility):
<div id="popup" data-role="popup"> <p>This is a completely basic popup, no options set.</p> </div> <script> $("#popup").popup("refresh", {top: 10, left: 10}); // Set new position for the center point of popup </script>
setPositionCB: deprecated
Sets a callback, which is called on the resize event. This callback is used to return the desired position of the popup after resizing.
setPositionCB ( Function callback)
This method is deprecated, and the setPositionCallback
method must be used to set the callback.
setPositionCallback
Sets a callback, which is called on the resize event. This callback is used to return the desired position of the popup after resizing.
setPositionCallback ( Function callback)
Use this method instead of the deprecated setPositionCB
.
Parameters:
Parameter | Type | Required/optional | Default value | Description |
---|---|---|---|---|
callback | Function | Required | Method called on resizing. It is used to return the desired position of the popup as an object with the "x" and "y" properties. |
Return value:
No return valueCode example (TAU API RECOMMENDED):
<div id="popup" data-role="popup"> <p>This is a completely basic popup, no options set.</p> </div> <script> var popupWidget = tau.widget.Popup(document.getElementById("popup")); popupWidget.setPositionCallback(function() { return {x: 10, y: 20}; }); </script>
Code example (jQuery API support for backward compatibility):
<div id="popup" data-role="popup"> <p>This is a completely basic popup, no options set.</p> </div> <script> $("#popup").popup("setPositionCallback", function() { return {x: 10, y: 20}; }); </script>
There are 2 ways to open a popup:
If the link has the id
of the popup set as the value of the href
property, the popup is opened after clicking on the link.
<!--Definition of link, which opens popup with popup id--> <a href="#popup">Click to open popup</a> <div id="popup" data-role="popup"> <p>This is a completely basic popup, no options set.</p> </div>
Be aware that a context popup with an arrow is opened if the link has the id
property and data-position-to="origin"
set as in this example:
<!--Definition of link, which opens context popup with popup id--> <a href="#popup" id="linkId" data-position-to="origin" data-role="button" data-inline="true">Click to open context popup</a> <div id="popup" data-role="popup"> <p>This is a completely basic popup, no options set.</p> </div>
To open a window popup, the data-position-to="window"
property must be set in the link or popup.
<!--Definition of link, which opens window popup with popup id--> <a href="#popup" id="linkId" data-position-to="window">Click to open popup</a> <div id="popup" data-role="popup"> <p>This is a completely basic popup, no options set.</p> </div>
To open a popup with the "popup" id
property, the tau
namespace can be used (RECOMMENDED):
<div id="popup"> <p>This is a completely basic popup, no options set.</p> </div> <script> var popupElement = document.getElementById("popup"), popup = tau.widget.Popup(popupElement); popup.open(); </script>
If the jQuery library is loaded, this method can be used (support for backward compatibility):
<div id="popup" data-role="popup"> <p>This is a completely basic popup, no options set.</p> </div> <script> var popup = $("#popup").popup(); popup.popup("open"); </script>
With the TAU API, you can open a popup anywhere (RECOMMENDED):
<div id="popup"> <p>This is a completely basic popup, no options set.</p> </div> <script> tau.openPopup("#popup"); </script>
There are 2 ways to close a popup:
If the link inside the popup has the data-rel="back"
property, the popup is closed after clicking on it:
<a href="#center_title_1btn" data-position-to="window">Click to open popup</a> <!--Definition of popup with a title and button--> <div id="center_title_1btn" data-role="popup" class="center_title_1btn"> <div class="ui-popup-title"> <h1>Popup title</h1> </div> <div class="ui-popup-text"> Pop-up dialog box, a child window that blocks user interaction to the parent windows </div> <div class="ui-popup-button-bg"> <a data-role="button" data-rel="back" data-inline="true">Button</a> </div> </div>
The selector, which causes closing on click, can be changed by setting the closeLinkSelector
option in the popup.
To close a popup with the "popup" id
property, the tau
namespace can be used (RECOMMENDED):
<a href="#popup" data-position-to="window">Click to open popup</a> <div id="popup" data-role="popup"> <p>This is a completely basic popup, no options set.</p> </div> <script> var popupElement = document.getElementById("popup"), popup = tau.widget.Popup(popupElement); // Close popup after opening popupElement.addEventListener("popupafteropen", function () { popup.close(); }); </script>
If jQuery library is loaded, this method can be used (support for backward compatibility):
<a href="#popup" data-position-to="window">Click to open popup</a> <div id="popup" data-role="popup"> <p>This is a completely basic popup, no options set.</p> </div> <script> $("#popup").on("popupafteropen", function () { $("#popup").popup("close"); }); </script>
With the TAU API, you can close a popup anywhere (RECOMMENDED):
<div id="popup"> <p>This is a completely basic popup, no options set.</p> </div> <script> tau.closePopup("#popup"); </script>