Popup

The popup component handles creating and managing pop-up windows.

Table of Contents

  1. Default Selectors
  2. Manual Constructor
  3. HTML Examples
  4. Context Popup with Arrow
  5. Options
  6. Events
  7. Methods
  8. Opening a Popup
  9. Closing a Popup

Default Selectors

By default, all elements with the data-role="popup" attribute are displayed as Tizen Web UI popups.

Manual Constructor

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>

HTML Examples

If the link has the data-position-to="window" option in the popup, the popup is opened to a new window after clicking.

Context Popup with Arrow

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:

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:

These options can be also set globally, and then the open method can be called without options:

Options

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.

Events

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>

Summary

Name Description
popupafteropen

Triggered when process of opening a popup is completed.
The event is triggered when the popup has completely appeared on the screen and all associated animations have completed.

beforeposition

Triggered before a popup computes the coordinates where it appears.
The event is triggered before the popup starts the opening animations and calculates the coordinates. Handling this event gives an opportunity to modify the content of the popup before it appears on the screen.

popupafterclose

Triggered when the process of closing a popup is completed.
The event is triggered when the popup has completely disappeared from the screen and all associated animations have completed.

Methods

To call a method on the component, use one of the existing APIs:

Summary

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 resize event. This callback is used to return the desired position of the popup after resizing.

setPositionCallback ( Function callback )

Sets a callback, which is called on the resize event. This callback is used to return the desired position of the popup after resizing.

option

Gets and sets component options.

* option ( string | Object? name, * value) 

The method can work in many contexts:

  • If first argument is of the object type, the method sets values for the options given in the object. The object keys are the names of the options and the values from the object are the values to set.
  • If you give only 1 string argument, the method returns the value for the given option.
  • If you give 2 arguments, and the first argument is a string, the second argument is interpreted as the value to set.

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 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"));

   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>

Opening a Popup

There are 2 ways to open a popup:

Closing a Popup

There are 2 ways to close a popup: