Tutorial: How to Scroll HTML Widget Content (Updated 28 Mar)

updated 28 March 2013, see below
Tutorial: How to Scroll an HTML Widget

Introduction
The HTML Widget is relatively new and still evolving. As such, it does not “yet” provide a scroller mechnanism for its content. This discussion assumes you are familiar with the Panel widget and the HTML widget.

Technique-1: Wrap HTML Widget in a Scrolling Panel
1) The simplest approach for scrolling an html widget content is to embed the widget in a scrolling Panel with auto-resize set to fully fill the panel as it changes size, e.g., rotate the device.

2) Select the panel and in the Properties enable the scrollbar and set the vertical height to the maximum size that you expect for html widget’s content.

Limitations:
1) The max height of a HTML Widget is 1000 px
2) If you set the containing panel’s content height to be too tall or too short the UX can be feel awkward. This technique is even more limited if you need to dynamically load or update the html widget’s content at runtime.
See attachment tech1-screen1-and-2.png

Technique-2: Programmatically attach an iScroll(er) to an HTML Widget’s content
A more natural approach is for the html widget’s contents to be scrolled directly rather than scrolling the entire html widget as in technique-1 above.

The MobiOne Panel widget uses the iScroll4 javascript component to implement its vertical scroller. Thus, you can use an iScroll component for your own purposes. In this technique we wrap your custom html widget’s custom content in an iScroll.

<div id="wrapper" style="width:100;height:100"> <!-- add a percent sign to both 100 values - -->
   <div id="scroller">                                       <!-- not shown due to portal's hatred for percent chars --> 
   <!-- custom content goes here -->
   </div>
</div>

<script type="text/javascript">
$(document).ready(function() {
    // Fill HTML content
    for (var i=0; i<1000; ++i) {
        $("#scroller").append("<div>" + i + "</div>");
    }

    //create a vertical scroller with bounce effect
    var myScroll = new iScroll('wrapper', {        
        vScroll : true,
        vScrollbar: true,
        hScroll : false,
        hScrollbar: false,
        bounce: true,
    });
});
</script>

If you dynamically update the html widget’s content you will need to call the javascript refresh() function on the scroller. See iScroller4 developer notes.

See attachment tech2-screen1-and-2.png

<Update – added Multipage example here>
Technique-2A For HTML widget on a Multipage Widget
If you plan to use an HTML widget with a custom scroller embedded on a multipage widget there is an additional configuration step. Begin as described in Technique-2 but add the add the HTML widget on page of a multipage widget instead of a panel widget. Use the same custom HTML code. Then add the following line of code as an On Page Change > Run as JavaScript action of the multipage widget. When the multipage widget is initialized the code will be executed to refresh() the iScroll component of the HTML widget. Prior to this the HTML widget is not fully initialized and its content’s size is unknown. The refresh() instructs the iScroller to recompute its size based on the “now” initialized HTML widget’s content.

  //call refresh() on the iScroll component attached to the <div id="scroller"> that is created in the HTML widget's code. 
  $("#scroller")[0].myScroll.refresh();

See attachment tech2-multipagewidget-screen1a.png

Conclusion
We are planning to upgrade the HTML widget with a scroller properties and a small api in the near future.

Download examples:
See attachment ScrollHTMLWidget-Technique1.mobi See attachment ScrollHTMLWidget-Technique2.mobi See attachment ScrollHTMLWidget-Technique2-multipage.mobi

Special thanks to Vadim Ridosh for his assistance in Technique-2 example and overall guidance.