ScrollPosition 2.x

TOCSTART

<div>
    <ul>
        <li><a href="#ScrollPosition2.x-SpecifyingScrollPositionComponent">Specifying Scroll Position Component</a>
        </li>
        <li><a href="#ScrollPosition2.x-SpecifyingScrollPositiononPageLoad">Specifying Scroll Position on Page
            Load</a></li>
        <li><a href="#ScrollPosition2.x-SpecifyingScrollPositionFortheScrollableComponent">Specifying Scroll
            Position For the Scrollable Component</a></li>
        <li><a href="#ScrollPosition2.x-TrackingScrollPositionFortheEntireApplication">Tracking Scroll Position For
            the Entire Application</a></li>
    </ul>
</div>
<p>TOCEND</p>


<p>The <cite>ScrollPosition</cite> component is a non-visual component that controls the scroll position
    of the page. By using it, you can specify the position of the scroll when the page is loaded and
    save the scroll position between page submissions. Note that there can be more than one
    <cite>ScrollPosition</cite>
    component on the page to save the scroll positions of various scrollable components, but there
    should be only one <cite>ScrollPosition</cite> component specified to save scroll position of the
    page.</p>


<h4><a name="ScrollPosition2.x-SpecifyingScrollPositionComponent"></a>Specifying Scroll Position Component</h4>

<p>To add the <cite>ScrollPosition</cite> component on the page, use the <u>&lt;o:scrollPosition&gt;</u> tag. When
    this component is added, the scroll position is saved automatically.</p>

<p>The <cite>ScrollPosition</cite> component has a boolean <b>autoSaveScrollPos</b> attribute. By default, it is set
    to <i>"true"</i>, which means that the scroll position is saved between page submissions.</p>

<div class="code panel" style="border-width: 1px;">
    <div class="codeContent panelContent">

<h:form>
  <o:scrollPosition autoSaveScrollPos="true"/>
</h:form>

    </div>
</div>

<h4><a name="ScrollPosition2.x-SpecifyingScrollPositiononPageLoad"></a>Specifying Scroll Position on Page Load</h4>

<p>You can specify the page's scroll position using the <b>value</b> attribute that should be bound to a variable of
    type <tt>java.awt.Point</tt>. The value referred to by this attribute should should specify coordinates of the
    top left corner of a page's visible area.</p>

<div class="code panel" style="border-width: 1px;">
    <div class="codeContent panelContent">

<h:form>
  <o:scrollPosition value="#{ScrollingBean.scrollPos}"/>
</h:form>

    </div>
</div>
<p>If the <b>autoSaveScrollPos</b> attribute is set to <i>"true"</i> (the default value), the scroll position is
    saved into the <b>value</b> attribute binding between page submissions.</p>

<h4><a name="ScrollPosition2.x-SpecifyingScrollPositionFortheScrollableComponent"></a>Specifying Scroll Position For
    the Scrollable Component</h4>

<p>You can specify the identifier of the scrollable component by using the <b>for</b> attribute, the scroll position
    of the scrollable component will be saved between page submissions. If the <b>for</b> attribute is not specified
    – the scroll position of the page will be saved between page submissions.</p>

<p>The <b>for</b> attribute should be assigned with the <b>id</b> of a JSF component or <font
        color="orange">id</font> of any HTML element, whose scroll position should be controlled:</p>
<ul>
    <li>The first way of specifying this attribute is for referencing JSF components and it is similar to the way of
        specifying the <b>for</b> attribute of the standard <u>&lt;h:outputLabel&gt;</u> and <u>
            &lt;h:message&gt;</u> tags. It can either be an "absolute" identifier that begins with a colon and
        includes ids of all naming container parents, such as <i>":form:button1"</i>, or it can be a relative
        identifier that refers to another child in the same naming container, for example <i>"button2"</i>. The
        formal rules of finding the component by identifier are described in API reference for the <a
                href="http://java.sun.com/javaee/5/docs/api/javax/faces/component/UIComponent.html#findComponent(java.lang.String)"
                class="external-link" rel="nofollow">UIComponent.findComponent()</a> method.
    </li>
    <li>The second way of specifying this attribute is for referring HTML elements rather than JSF components.
        Referring to HTML elements is similar to referring JSF components with an absolute identifier – you just
        need to prepend actual element id with a colon symbol. For example in order to refer a an HTML button tag
        declared as <tt>&lt;input id="myHtmlButton" type="button" value="Test"/&gt;</tt> you should use the <i>":myHtmlButton"</i>
        value of the <b>for</b> attribute.
    </li>
</ul>


<p>Here is an example of tracking scroll position for an HTML element by its identifier:</p>

<div class="code panel" style="border-width: 1px;">
    <div class="codeContent panelContent">

<h:form>
  <o:scrollPosition for=":scrollable_div"/>
  <div id="scrollable_div">

  </div>
</h:form>

    </div>
</div>
<p>Note that if the <b>value</b> attributes is used with the <b>for</b> attribute then the appropriate coordinates
    will be applied to the specified scrollable component.</p>

<h4><a name="ScrollPosition2.x-TrackingScrollPositionFortheEntireApplication"></a>Tracking Scroll Position For the
    Entire Application</h4>

<p>You can also set the <tt>org.openfaces.autoSaveScrollPos</tt> context attribute in web.xml to <i>"true"</i> (the
    default is <i>"false"</i>) to track the scroll position for all application pages.</p>

<div class="code panel" style="border-width: 1px;">
    <div class="codeContent panelContent">

<context-param>
  <param-name>org.openfaces.autoSaveScrollPos</param-name>
  <param-value>true</param-value>
</context-param>

    </div>
</div>