Namespaces

Variants
Actions

Please note that as of October 24, 2014, the Nokia Developer Wiki will no longer be accepting user contributions, including new entries, edits and comments, as we begin transitioning to our new home, in the Windows Phone Development Wiki. We plan to move over the majority of the existing entries over the next few weeks. Thanks for all your past and future contributions.

Popup JavaScript component for Web Runtime

From Wiki
Jump to: navigation, search

This article explains how to build and use a modal popup component for Symbian Web Runtime widgets. Modal popup windows or messages are useful to display important information to the user, blocking the rest of the Widget interface until the popup is disposed, typically by pressing a button.

Article Metadata
Code ExampleArticle
Created: jappit (10 Jun 2009)
Last edited: hamishwillee (07 May 2012)

Wrt popup widget.png

Contents

Popup component: how to use it

The Popup component presented in this article can be used by following these steps:

<script language="javascript" type="text/javascript" src="Popup.js"></script>
  • Include a semi-opaque image to be used to opacize the widget's content when the popup is displayed. An example image, used in this article, is the following:

Wrt popup cover image.png

Since the image will be stretched both horizontally and vertically, the image size is not a problem.

  • Before creating your first Popup, define CSS rules to customize the component appearance. The default CSS classes and ids used by the Popup component are the following (but can be easily customized by modifying the code, see implementation for details):
    • popup CSS class for the main Popup DOM element
    • popup_text CSS class for the Popup content
    • popup_buttons CSS class for the Popup buttons' container DIV
    • popup_button_ok ID for the OK button
    • popup_button_cancel ID for the CANCEL button
  • Now, all is ready to display the first Popup window. To do it, just instantiate a new Popup object, and then show it:
var popup = new Popup(
"This is just a <strong>sample popup</strong>",
"OK",
null,
"Cancel",
null);
 
popup.show();

Arguments for the Popup constructor are the following:

  • the 'popup content (any valid HTML content)
  • the text for the OK button
  • the handler function for the OK button (can be null)
  • the text for the CANCEL button (optional: if null, the cancel button will not be shown)
  • the handler function for the CANCEL button (optional, can be null)

Sample CSS rules, used in this article, are the following:

.popup {
border: 3px solid #336699;
padding: 4px;
background: white;
text-align:center;
}
 
.popup_buttons {
overflow: auto;
}
 
#popup_button_ok, #popup_button_cancel {
border: 1px solid #336699;
background-color: gray;
color:white;
min-width: 50px;
text-align:center;
padding: 10px;
}
#popup_button_ok:hover, #popup_button_cancel:hover {
background-color: #6699cc;
}
 
#popup_button_ok {
float: left;
margin-left: 10px;
background-image: url("images/accept.png");
background-position: left center;
padding-left: 16px;
background-repeat: no-repeat;
}
 
#popup_button_cancel {
float: right;
margin-right: 10px;
background-image: url("images/cancel.png");
background-position: left center;
padding-left: 20px;
background-repeat: no-repeat;
}

Popup component implementation

The Popup component is structured as shown by the following picture.

Wrt popup structure small.png

So, once the WRT widget needs to show a Popup instance, the component will perform these steps:

  • append the semi-opaque image over the Widget's content, and stretch it to cover its whole size
  • build the popop DOM structure
  • append the popup DOM element just over the cover image, centering it both horizontally and vertically

Since the image will cover the whole Widget user interface, user interactions will be forbidden until the popup, and so the image cover, will be disposed.

Now, let's see the component implementation.

Popup costructor

This Popup component built in this article has customizable features:

  • customizable popup content
  • customizable OK and CANCEL buttons' text
  • customizable handler functions on the OK and CANCEL buttons' click events

The Popup constructor allows to set all these properties through its arguments:

function Popup(popupHtml, okButtonText, okButtonHandler, cancelButtonText, cancelButtonHandler)
{
/* HTML content to be shown inside the popup */
this.popupHtml = popupHtml;
 
/* text for the ok button */
this.okButtonText = okButtonText;
 
/* text for the cancel button */
this.cancelButtonText = cancelButtonText;
 
/* handler function for the ok button */
this.okButtonHandler = okButtonHandler;
 
/* handler function for the cancel button */
this.cancelButtonHandler = cancelButtonHandler;
 
/* page cover DOM element */
this.coverElement = null;
 
/* popup DOM element */
this.popupElement = null;
}

The last 2 defined properties will hold references to the image cover and popup DOM elements, respectively.

Building and showing the Popup

Before building the popup DOM structure, some properties are defined in order to allow easier styling and customization of Popup visual appearance.

/* CSS class applied to the main popup element */
Popup.MAIN_CSS_CLASS = 'popup';
 
/* CSS class applied to popup content */
Popup.TEXT_CSS_CLASS = 'popup_text';
 
/* CSS class applied to popup buttons' container */
Popup.BUTTONS_CSS_CLASS = 'popup_buttons';
 
/* path of the image used to opacize the widget */
Popup.COVER_IMAGE_SRC = 'images/page_cover.png';
 
/* element ID of the OK button */
Popup.OK_BUTTON_ID = 'popup_button_ok';
 
/* element ID of the CANCEL button */
Popup.CANCEL_BUTTON_ID = 'popup_button_cancel';
 
/* minimum margin of the popup from screen boundaries */
Popup.MARGIN = 20;
 
/* z-index to be used for the popup DOM element */
Popup.zIndex = 10000;

The Popup DOM structure is built on the fly when the Widget needs to display it. So, all the job is done by the show() method:

Popup.prototype.show = function(beforeShowHandler)
{
/* calculate the width and height to be covered */
var bodyHeight = Math.max(document.body.offsetHeight, window.innerHeight);
var bodyWidth = document.body.offsetWidth;
 
/* build the cover that will opacize the widget's content */
var coverElement = document.createElement('img');
coverElement.src = Popup.COVER_IMAGE_SRC;
coverElement.style.position = 'absolute';
coverElement.style.width = '100%';
coverElement.style.height = bodyHeight + 'px';
coverElement.style.top = '0px';
coverElement.style.left = '0px';
coverElement.style.zIndex = Popup.zIndex - 1;
 
this.coverElement = coverElement;
 
/* append the cover element to the document's body */
document.body.appendChild(coverElement);
 
/* now, build the popup DOM element */
var popupElement = document.createElement('div');
popupElement.style.position = 'absolute';
popupElement.style.width = (bodyWidth - 2 * Popup.MARGIN) + 'px';
popupElement.style.left = (document.body.scrollLeft + Popup.MARGIN) + 'px';
popupElement.style.zIndex = Popup.zIndex;
popupElement.className = Popup.MAIN_CSS_CLASS;
 
this.popupElement = popupElement;
 
/* build the DOM element that contains the popup content */
var textElement = document.createElement('div');
textElement.className = Popup.TEXT_CSS_CLASS;
textElement.innerHTML = this.popupHtml;
popupElement.appendChild(textElement);
 
/* add the ok and cancel buttons */
var buttonsContainer = document.createElement('div');
buttonsContainer.className = Popup.BUTTONS_CSS_CLASS;
popupElement.appendChild(buttonsContainer);
 
var okButton = document.createElement('div');
okButton.id = Popup.OK_BUTTON_ID;
okButton.innerHTML = this.okButtonText;
buttonsContainer.appendChild(okButton);
 
var self = this;
 
okButton.onclick = function()
{
self.okButtonPressed();
}
 
if(this.cancelButtonText != null)
{
var cancelButton = document.createElement('div');
cancelButton.id = Popup.CANCEL_BUTTON_ID;
cancelButton.innerHTML = this.cancelButtonText;
buttonsContainer.appendChild(cancelButton);
 
cancelButton.onclick = function()
{
self.cancelButtonPressed();
}
}
 
if(beforeShowHandler)
beforeShowHandler(popupElement);
 
/* finally, append the popup element to the document's body */
document.body.appendChild(popupElement);
 
/* let's center the popup */
var popupTop = Math.max(
(document.body.scrollTop + (window.innerHeight - popupElement.offsetHeight) / 2),
document.body.scrollTop
);
 
popupElement.style.top = popupTop + 'px';
}

The show() method accepts an optional function handler as argument: if passed, it will be called just before the Popup DOM element is actually shown, in order to allow further customization of the component itself.

The steps performed by the show() method are:

  • calculating the whole widget width (bodyWidth) and height (bodyHeight), in pixels
  • building the cover image (coverElement) and appending over the widget's content
  • creating the popup DOM element (popupElement) and then populating it with its content:
    • the popup HTML content (textElement)
    • and the popup OK and CANCEL buttons (okButton and cancelButton)
    • onclick handler functions are also defined for the OK and CANCEL button, in order to respond to user interaction
  • before showing the component, the beforeShowHandler, if defined, is called
  • finally, the component is shown and its top coordinate is adjusted, to center it vertically

Popup buttons' click handlers

The following methods are used to manage user interaction for the OK and CANCEL buttons, respectively. If custom handlers were defined though the component's constructor, they'll be called as well.

/**
* Function called when the popup CANCEL button is pressed
*/

Popup.prototype.cancelButtonPressed = function()
{
this.hide();
 
if(this.cancelButtonHandler != null)
this.cancelButtonHandler();
}
/**
* Function called when the popup OK button is pressed
*/

Popup.prototype.okButtonPressed = function()
{
this.hide();
 
if(this.okButtonHandler != null)
this.okButtonHandler();
}

Hiding the component

Once the user has seen the popup, and wants to dispose it (through one of the OK and CANCEL button), the hide() method will be called to actually dispose the component:

/**
* Function to hide the popup
*/

Popup.prototype.hide = function()
{
this.popupElement.parentNode.removeChild(this.popupElement);
this.coverElement.parentNode.removeChild(this.coverElement);
 
this.popupElement = null;
this.coverElement = null;
}

Downloads

The following files are available for download:

This page was last modified on 7 May 2012, at 05:55.
322 page views in the last 30 days.

Was this page helpful?

Your feedback about this content is important. Let us know what you think.

 

Thank you!

We appreciate your feedback.

×