The Spry HTML Panel Widget is used to load and inject remote HTML content into a specific container on the page. The HTML Panel Widget can load a fragment file: a file with no HTML or BODY tags; just a small piece of HTML, or it can load the contents of an element with a specific id from a full HTML page.
The widget structure consists of a single container element, which can be any block or inline container, unless otherwise noted below. The widget container element can contain static markup/content, or contain no content at all. If widget container has static markup/content, this content will be discarded if the widget is told to load remote HTML content.
The following tags cannot be used for the panel, since InnerHTML is locked for these tags:
A basic example that uses an HTML panel would be:
<a href="#" onclick="hpanel.loadContent("frag-01.html"); return false;">Fragment-1</a> <div class="HTMLPanel" id="samplePanel"> <p>This is some static content within an HTMLPanel container. It will disappear once content is loaded into the panel via one of the links above.</p> </div> <script language="JavaScript" type="text/javascript"> var hpanel = new Spry.Widget.HTMLPanel("samplePanel"); </script>
In the example above, an HTML Panel widget is created an bound to the <div> container element with the id of "samplePanel". If the user clicks on the link, it will trigger the HTML Panel to load some remote/external HTML content from a file named "frag-01.html".
Widget Constructors are small pieces of javascript that activate the markup into the working widget. These scripts must come AFTER the markup on the page, since the markup needs to exist before the constructor fires.
<script type="text/javascript">
<!--
var hpanel = new Spry.Widget.HTMLPanel("samplePanel");
//-->
</script>
A basic constructor specifies the name of the widget and identifies the ID of the main markup container. The name of the widget is used to identify the widget for functions and methods.
<script type="text/javascript"> var widgetname = new Spry.Widget.HTMLPanel("id of widget container"); </script>
Constructor options allow users to specify certain attributes of the widget.
Constructor options follow the ID parameter, wrapped in curly braces {}. Options are name:value pairs, separated by a colon (:).
Option | Type | Default | Description |
---|---|---|---|
evalScripts | Boolean | true | Determines if <script> tags found within the panel content are to be run. |
errorStateClass | String | HTMLPanelError | The custom class to use if the HTML Panel encountered an error while loading content. |
loadingStateClass | String | HTMLPanelLoading |
The custom class to use if the HTML Panel is in the process of loading content. This class is placed on the container element just before a load is kicked off. |
loadingContentClass | string | HTMLPanelLoadingContent |
The custom class to for the content to be used when the HTML Panel is loading data. |
errorContentClass | String | HTMLPanelErrorContent | The custom class to use when the HTML Panel encounters an error while loading data. |
<script type="text/javascript">
var widgetname = new Spry.Widget.HTMLPanel("id of widget container",{evalScripts:false, errorContentClass:"myerror"});
</script>
Recall that javascript is case sensitive.
Notification | Description |
---|---|
onPreLoad | The HTML Panel is about to load a new HTML Fragment. An object that describes the load request will be passed to all observers. This object will have the following properties:
This object may also contain other optional properties specified by the user during the call to loadContent(), which may include:
It should be noted that observers are allowed to modify this object to alter the loading behavior. For example, observers can use this notification to tack on extra query parameters to the URL or postData, or even add username/password info. |
onPostLoad | The HTML Panel has successfully loaded the new HTML Fragment. An object that describes the load request will be passed to all observers. This object will contain the same properties as those listed above for the onPreLoad notification, but will also contain the following properties:
|
onPreUpdate | The content within the region container is about to be updated/replaced. An object with the following properties will be passed to all observers:
It should be noted that observers are allowed to modify the data in this object to alter the actual content that is inserted into the region container. |
onPostUpdate | The content within the region container has been updated. The same object passed during the onPreUpdate notification is passed to the observers for this notification. |
onLoadError | The request for the HTML Fragment failed. An object that describes the load request will be passed to all observers. This object contains the same properties as those listed for the onPreLoad notification, but will also contain the following properties:
|
onLoadCancelled | The request for the HTML Fragment was canceled. An object that describes the load request will be passed to all observers. This object contains the same properties as those listed for the onPreLoad notification, but will also contain the following properties:
|
Adds an observer to the region. As with other components within Spry, the observer can be either an object or a function callback.
widgetName.addObserver(observer);
<script language="JavaScript" type="text/javascript"> // Create an HTMLPanel widget and bind it to the element with // the id of "samplePanel". var hpanel = new Spry.Widget.HTMLPanel("samplePanel"); // Add a function as an observer of the panel. function myObserverFunc(notificationType, notifier, data) { if (notificationType == "onPostUpdate") alert("onPostUpdate fired!"); } hpanel.addObserver(myObserverFunc); // Add an object as an observer of the panel. var obs = new Object; obs.onPostUpdate = function(notifier, data) { alert("onPostUpdate was fired!"); }; hpanel.addObserver(obs); </script>
Cancels the currently loading content
widgetName.cancelLoad();
If a pending request is cancelled, this method will result in the following notifications:
<a href="#" onclick="hpanel.cancelLoad(); return false;">Stop Loading</a>
Disables the notification of observers.
widgetName.disableNotifications();
<a href="#" onclick="hpanel.disableNotifications(); return false;">Disable Notifications</a>
Enables observer notifications.
Notifications are enabled by default within an HTML Panel.
widgetName.enableNotifications();
<a href="#" onclick="hpanel.enableNotifications(); return false;">Enable Notifications</a>
Spry.Widget.HTMLPanel.evalScripts is a global variable that lets the developer decide whether all HTML Panel widgets will be able to execute script, embedded within HTML fragments, they load or not. The default value is false. This setting can be overridden for a specific HTML Panel by specifying the evalScripts constructor option when its constructor is invoked.
Spry.Widget.HTMLPanel.evalScripts
<script language="JavaScript" type="text/javascript"> // Enable the ability to execute script for *every* // HTMLPanel that is created. Spry.Widget.HTMLPanel.evalScripts = true; // The following panel will have the ability to // execute script. var hpanel = new Spry.Widget.HTMLPanel("samplePanel"); // The following panel will *NOT* have the ability to // execute script because it overrides the global setting. var hpanel2 = new Spry.Widget.HTMLPanel("samplePanel2", { evalScripts: false }); </script>
Loads a frag or part of a page into the widget.
widgetName.loadContent(url, options);
url: the path to the fragment or page to be loaded.
// Example of creating a header object the literal way: var header = { "Content-Type": "application/x-www-form-urlencoded; charset=UTF-8" }; // Example of creating a header object manually: var header = new Object; header["Content-Type"] = "application/x-www-form-urlencoded; charset=UTF-8";
Calling this method will result in the following notifications:
The notifications above are listed in the order that they should fire. Should the load fail, an onLoadError notification will be fired in place of an onPostLoad notification.
If the HTML Panel is in the midst of loading content when this method is called. The previous load request is cancelled prior to making the new request.
<a href="#" onclick="hpanel.loadContent("frag01.htm"); return false;">Load Frag 1</a> <a href="frag02.htm" onclick="hpanel.loadContent(this.href); return false;">Load Frag 2</a> <a href="page3.htm" onclick="hpanel.loadContent(this.href,{id:"products"});">Load Products</a>
Removes the specified observer from the widget's list of observers. The same observer function or object that was used for the addObserver() call must be used in a call to removeObserver().
widgetName.removeObserver(observer);
<script language="JavaScript" type="text/javascript"> // Create an HTMLPanel widget and bind it to the element with // the id of "samplePanel". var hpanel = new Spry.Widget.HTMLPanel("samplePanel"); // Add a function as an observer of the panel. function myObserverFunc(notificationType, notifier, data) { if (notificationType == "onPostUpdate") alert("onPostUpdate fired!"); } hpanel.addObserver(myObserverFunc); // Add an object as an observer of the panel. var obs = new Object; obs.onPostUpdate = function(notifier, data) { alert("onPostUpdate was fired!"); }; hpanel.addObserver(obs); ... // Remove the observers that were added. hpanel.removeObserver(myObserverFunc); hpanel.removeObserver(obs); </script>
Removes any CSS Behavior class names from the region container element.
widgetName.removeStateClasses();
<a href="#" onclick="hpanel.removeStateClasses(); return false;">Reset Classes</a>
Replaces the contents of the region container with the content in the specified html fragment string.
widgetName.setContent(htmlString, id);
Calling this method will result in the following notifications:
<input type="button" onclick="panelWidget.setContent('<strong>This is strong text</strong>');">
Copyright 2007, Adobe Systems Inc.