Pageflakes Functions

The Pageflakes framework provides a set of functions that have been designed to work across all the major browsers, such that concise, platform independent code can be used to build flakes.

All the functions shown below are members of the PF object. They can be accessed by calling PF.functionName().

DOM Manipulation

$(id)

Shortcut for document.getElementById:


var e = document.getElementById('mytextbox');

Use:

    var e = PF.$('mytextbox');
    var i = PF.$('myradiobutton');

$$(tagName, id, className, text)

Shortcut for document.createElement.

The tagName parameter must be specified. All other parameters are optional.


var div = PF.$$('div');
var divButton = PF.$$('div', 'button', 'button_class', 'this is a button');

remove(e, p)
remove(id) 		Removes the element from the parent node.
removeAll(el) Removes all child elements from the element. It recursively traverses all children and calls remove on them.

Example

This example demonstrates how to perform some simple DOM manipulations, including assigning an element to a variable and removing an element using the PF.Remove method.

Element Visibility

nodisplay(e)
nodisplay(id)
ND(e)
ND(id)

Instead of:

e.style.display = "none";

Use any of the following:

PF.nodisplay(e);
PF.nodisplay('mydiv');
PF.ND(‘mydiv’);


T(e, text)
T(id, text)
setInnerText(e, text)

Instead of:

if (mz)
	  e.textContent = text;
else
	  e.innerText = text;

Use either of the following:

PF.T('mydiv', 'text to set');
PF.T(e, 'text to set');


display(id)
D(e)
D(id)

Instead of:


e.style.display = "block";

Use any of the following:

PF.display(e);
PF.display('mydiv');
PF.D(‘mydiv’);


isVisible(e)
isVisible(id)

Returns true if the element
is visible; false otherwise.
clearDisplay(el) Clears the e.style.display property and reverts to what is defined in CSS.
hide(el) Sets visibility style to hidden.
visible(el) Sets visibility style to visible.
toggleDisplay(el) Toggles display attribute to show/hide element.
switch(display, nodisplay)

Displays the first item and hides the second item.


PF.switch( divToShow, divToHide )

toggleVisibility(name) Toggle display style between “none” and “block”.
canYouSeeMe(target) Returns true if the item is
visible on the screen, or false if it is not
visible. It does so by walking through the ancestors and checking whether any
of them has the display attribute set to none or the visibility attribute set to hidden.

Element State

focus(e)

focus(id)

Sets focus to the element.

disabled(e)

disabled(id)

Disables an element. No mouse events will be captured.
Text color is changed to lightgrey. Useful
for disabling buttons. For example:


PF.disabled('mybutton');

Or:


PF.disabled(e);

enabled(e)

enabled(id)

Enables the element that had been disabled. For example:

PF.enabled('mybutton');
PF.enabled(e);

disableAllFrames()

Disables all frames and IFRAMEs on the page by setting
their enabled property to false.

Class Manipulations

addHover(el, className)

Adds hover behavior to an element. When the mouse hovers over the item, the specified class is added to the element. When the mouse leaves, the specified class is removed.

addClass(el, className)

Adds a CSS class to an element. Previous classes are preserved.

removeClass(el, className)

Removes a particular CSS class from element.

select(item, className, tagName)

When a series of elements exist where only one can be selected at a time (e.g. tabs or radio buttons), this function can be used to apply a class to the selected item and clear that class from unselected items.

<div onclick='PF.select(this, "selectedClass", "div")'>Item 1</div>
<div onclick='PF.select(this, "selectedClass", "div")'>Item 2</div>
<div onclick='PF.select(this, "selectedClass", "div")'>Item 3</div>

selectChild(parent, tagName,
className, expr)

Apply a class to child elements of a node based on some expression. Consider the following example:

    <ul id="tabs">
        <li>Tab 1</li>
        <li>Tab 2</li>
        <li>Tab 3</li>
    </ul>

Now, to modify the class of a particular tab, the following can be used:

PF.selectChild('tabs', 'li', 'selectedTab', function(tab) {
    return tab.innerText == 'Tab 2'; } );

This example assigns the 'selectedTab' class to 'Tab 2'.

In general, the specified class is assigned to the all elements where the specified function evaluates to true.

Positioning

centerDiv(div) Position an absolute div at the center of the visible area.
changeParent(id, newParentId) Move an element from its current parent to the new parent.
makeOnTop(el) Position the absolute element on top of any other absolute element.
getPosition(obj) Get the bounds of the specified element as an array. For example:


var pos = PF.getPosition(e);
x = pos[0];
y = pos[1];
w = pos[2];
h = pos[3];

Cursor

setBusy() Change the cursor to hourglass.
setIdle() Set cursor to the default arrow.

Progress Bar

showProgress() Display the progress bar.
hideProgress() Hide the progress bar.

Element Opacity

setOpacity(id,val) Set the opacity of an element.
changeOpacity(opacity, id) Changes the opacity of any given element by 'opacity'.
clearOpacity(id) Makes an element 100% opaque.
opacity(el, startOpacity, endOpacity, millisecond, callback) Change the opacity from a given value to new value within a fixed time defined in milliseconds. When execution is complete, the callback is invoked.
shiftOpacity(id, milliseconds) Toggles the opacity from 0 to 100 of a given element in the specified time period.
currentOpacity (id,opacEnd,millisec) Change the opacity from the current value to the specified ending value within the given time (specified in milliseconds).

Cookies

createCookie(name, value, day) Creates a cookie with the given name, value, and expiration (in days).
readCookie(name) Returns the value of the cookie
cloneObject(ob) Makes a clone of an object by copying all of its properties and  functions.

var clone = new PF.cloneObject(someObj);

Miscellaneous

addScript(id, url)

Adds a script tag in the <head> section. Use this to dynamically download script blocks.

htmlEncode(text)

HTML encodes a string by replacing special characters with
their HTML equivalents.

urlParam(name)

Returns the value of the query string parameter.

For example, if the current URL is:

http://example.com/default.aspx?id=123

Then to get the “123” value the following can be used:

var id = PF.urlParam("id");

dumpException(exp)

 Used to handle exceptions produced form server side calls.
Whenever you call a server side method, the 3rd argument is an exception
callback. For example:

this.callback = function(result) { ... }
this.error = function(exception)
{
  PF.dumpException(exception);
}
ContentProxy.GetUrl(url, callback, error);

isFlashInstalled()

Returns true if a Flash player is installed, false
otherwise.

getErrorMessage(exp)

Get the error message from the exception.

exec(string)

Executes any JavaScript code passed as parameter.

stripTags(value)

Removes all HTML tags from the provided string and returns the result as a string.

formatText(text)

Format the supplied text by replacing line breaks with <br/>.

helpText(textbox, text)

This function grays out the specified text box, filling it in with the text specified. This can be used to provide help text on how the text box should be filled in.

When the user selects the text box, the box clears the text and restores the normal background color.

Events

F(object, function)

Delegate

Returns a delegate reference that fires the function on the context of the passed object. F(...) should be used in callbacks such that the callback can use the this pointer. For more information see Avoid memory leaks and understand 'this'.

ContentProxy.GetUrl(url, PF.F(this, this.callback));

addEvent(e, eventName, handler)

Adds an event handler to an element. This is a cross-browser solution for subscribing events on UI elements. The following way of hooking into events should not be used:

Somebutton.onclick = function(e) { }

This leaks memory in Internet Explorer 6 if not used carefully. Moreover, it removes any existing event handler on the same event. Instead, do it this way:

PF.addEvent(Somebutton, 'click', callback);

And define the callback function outside the scope:

function callback(e) { ... }

The benefit of this type of event handler is that the event parameter is passed in the callback in a cross-browser implementation. This e has the same parameters and functions in all browsers.
removeEvent(e, eventName, handler)

Removes an event handler from an element. However, only event handlers that were subscribed by calling addEvent can be removed.

This function ensures that event handlers are released properly to prevent IE 6 from leaking memory. Event handlers should be removed as soon as they are no longer required.

PF.removeEvent(somebutton, 'click', callback);

removeAllEvents(e)

clearEvent(e) [deprecated]

Clears all event handlers from an element. This ensures that the DOM element is ready to be released and solves a memory leak problem in Internet Explorer 6.

fix(event)

IE treats events differently that other browsers. IE uses window.Event which Firefox doesn't support. Moreover, most browsers pass the event as an argument to the event callback function, which IE does not.

In order to avoid such problems, all event handlers can be declared by giving them an argument for getting the event, and inside the event,  the fix function can be invoked to ensure that the event parameter has the right value. For example:

function onresize(event) { event = PF.fix(event); ...}

It is also possible to use the Callback function, described below.

Callback(code)

This method provides a browser independent method of invoking event callbacks (for additional information see also the fix() function above).

Specifically, it takes care of the difference between Internet Explorer, and all other browsers in passing the event data to the event handler. For example:

PF.addEvent(item, 'click', PF.Callback("alert(event.target)");

The code is evaluated only when the event fires.

The function is defined as:

PF.Callback = function(code)
    {
      return function(event)
      {
         event = PF.fix(event);
         eval(code);
      }
    }

stopBubble(event)

Prevents the event from bubbling up to the parent element.

delayCall(func)

DC(func)

Calls the specified function in a timer with near zero delay. In Firefox, if the innerHTML of an element is set and the child nodes are accessed immediately, the operation will sometimes fail since the DOM elements are not immediately available.

As a workaround, the following code can be used to complete the code execution and access the elements with a delay:

div.innerHTML = "<div id='childDiv'>...</div>";

// This will fail in FF sometimes if the browser does not create
the childDiv immediately

PF.D('childDiv');

// This will not fail

PF.DC( function() { PF.D('childDiv') } );

Window

scrollTop()

Scrolls to top of the page.
scrollBottom()

Scrolls to bottom of the page.
getContentHeight()

Returns the height of the document.
getViewportWidth()

Returns the width of the window.
getViewportHeight()

Returns the height of window.
getViewportScrollX()

Returns the horizontal scrollbar position
getViewportScrollY()

Returns the vertical scrollbar position

XML

getXmlDoc(xmlString)

Returns an XML DOM object from an XML string.
Use the DOM object with the following two functions.
getFirstNode(xmlDoc, pattern)

Returns the first XML node from the provided XML document that matches the provided pattern. For example:

var node = PF.getFirstNode(xmlDoc, "book");

To find an element by specifying multiple node names, use a pattern like this:

var node = PF.getFirstNode(xmlDoc, "book:author:firstname");
getNodes(xmlDoc, pattern)

Returns and array of XML nodes (JavaScript Node objects) from the provided XML document that match the provided pattern. For example:

var nodes = PF.getNodes(xmlDoc, "book");

To find elements by specifying multiple node names, use a pattern like this:

var nodes = PF.getNodes(xmlDoc, "book:author:firstname");

Page

blockUI(msg)

Dims the whole page, such that a popup or other overlay can be displayed.

If the msg parameter is specified, it displays a small dialog with a message inside it.
unblockUI()

Returns the page to its normal state.