### HTML Panel Widget

#### Description

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.

#### Required Files

> SpryHTMPanel.js

> SpryHTMPanel.css

#### Reference File

> SpryHTMPanel.html

#### Sample Files

> HTMPanelSample.html

### Structure

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:

- col
- colgroup
- frameset
- html
- iframe
- select
- style
- table
- tbody
- tfoot
- thead
- title
- tr

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".

### Constructor

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>

#### Basic Constructor

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

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. This class is placed on the container if the region fails to load the 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.

## Notifications

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:

- async
  - If true, the data will be loaded asynchronously, otherwise, the data will be loaded synchronously.
- id
  - The id of an element within the data being fetched. The content underneath this element will be inserted into the region container.
- method
  - A string with the value of "GET" or "POST"
  url
  - The URL that will be used to load the data.

This object may also contain other optional properties specified by the user during the call to loadContent(), which may include:

- headers
  - An object with properties that specify the HTTP headers to send with the request. For an example, click here
- password
  - A string that specifies the password to send along with the username when the request is made
- postData
  - The format of this property is up to the developer so this must be used in conjunction with the "headers" option, mentioned above, to specify the "Content-type" so the server knows how to deal with it.
- username
  - A string that specifies the username to send along with the data request.

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:

- xhRequest
  - The native XMLHttpRequest object used to load the data.

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:

- content
  - The HTML Fragment to be inserted into the region container.
- id
  - The id of an element within the data being fetched. The content underneath this element will be inserted into the region container.

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:

- xhRequest
  - The native XMLHttpRequest object used to load the data.

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:

- xhRequest
  - The native XMLHttpRequest object used to load the data.

## HTML Panel Widget Methods

### addObserver

Adds an observer to the region. As with other components within Spry, the observer can be either an object or a function callback.

#### Format

widgetName.addObserver(observer);

#### Example

    <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>

### cancelLoad

Cancels the currently loading content

#### Format

widgetName.cancelLoad();

#### Notifications

If a pending request is cancelled, this method will result in the following notifications:

- onLoadCancelled

#### Example

    <a href="#" onclick="hpanel.cancelLoad(); return false;">Stop Loading</a>

### disableNotifications

Disables the notification of observers.

#### Format

widgetName.disableNotifications();

#### Example

    <a href="#" onclick="hpanel.disableNotifications(); return false;">Disable Notifications</a>

### enableNotifications

Enables observer notifications.

Notifications are enabled by default within an HTML Panel.

#### Format

widgetName.enableNotifications();

#### Example

    <a href="#" onclick="hpanel.enableNotifications(); return false;">Enable Notifications</a>

### evalScripts

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.

#### Format

Spry.Widget.HTMLPanel.evalScripts

#### Example

    <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>

### loadContent

Loads a frag or part of a page into the widget.

#### Format

widgetName.loadContent(url, options);

#### Arguments

url: the path to the fragment or page to be loaded.

#### Options

- async
  - Boolean.
  - If true, the request for the HTML Fragment will be processed asynchronously, which means that the request will be made, but the response may come back some time *after* the call to updateContent() has finished. If false, the request will block until a response has been received from the server, or the request has timed out.
- headers
  - Object.
  - Specifies additional HTTP Request header fields that should be sent along with the request. Each property in this object is the name of an HTTP header field to send. The value of the property, is the value of that field. Example:

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

- id
  - If defined, the HTML Panel will search for an element with the given id inside the HTML fragment that was just loaded. If it finds it, it inserts the content *within* this node into the element on the page that the region is bound to. If not defined, the region inserts the entire HTML Fragment into the element on the page that it is bound to.
- method
  - String.
  - Must be "GET", "POST" or "HEAD".
  - The default if unspecified is "GET".
- password
  - String.
  - The password to send to the server along with the request.
- postData
  - String.
  - The format of the data in the string is up to the developer so this must be used in conjunction with the "headers" option, mentioned above, to specify the "Content-type" so the server knows how to deal with it.
- username
  - String.
  - The username to send to the server along with the request.

#### Notifications

Calling this method will result in the following notifications:

- onPreLoad
- onPostLoad
- onPreUpdate
- onPostUpdate

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.

#### Example

    <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>

### removeObserver

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().

#### Format

widgetName.removeObserver(observer);

#### Example

    <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>

### removeStateClasses

Removes any CSS Behavior class names from the region container element.

#### Format

widgetName.removeStateClasses();

#### Example

    <a href="#" onclick="hpanel.removeStateClasses(); return false;">Reset Classes</a>

### setContent

Replaces the contents of the region container with the content in the specified html fragment string.

#### Format

widgetName.setContent(htmlString, id);

#### Arguments

- htmlFrag
  - String.
  - A string containing HTML markup.
- id
  - String. (Optional)
  - The id of an element inside the specified HTML fragment. If defined, the content underneath the specified element will be inserted into the region container instead of the entire fragment.

#### Notificiations

Calling this method will result in the following notifications:

- onPreUpdate
- onPostUpdate

#### Example

    <input type="button" onclick="panelWidget.setContent('<strong>This is strong text</strong>');">

Copyright 2007, Adobe Systems Inc.