ScrollPosition

The ScrollPosition 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 ScrollPosition component on the page to save the scroll positions of various scrollable components, but there should be only one ScrollPosition component specified to save scroll position of the page.

API Reference | Tag Reference

Specifying Scroll Position Component

To add the ScrollPosition component on the page, use the <o:scrollPosition> tag. When this component is added, the scroll position is saved automatically.

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

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

Specifying Scroll Position on Page Load

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

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

If the autoSaveScrollPos attribute is set to "true" (the default value), the scroll position is saved into the value attribute binding between page submissions.

Specifying Scroll Position For the Scrollable Component

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

The for attribute should be assigned with the id of a JSF component or id of any HTML element, whose scroll position should be controlled:

  • The first way of specifying this attribute is for referencing JSF components and it is similar to the way of specifying the for attribute of the standard <h:outputLabel> and <h:message> tags. It can either be an "absolute" identifier that begins with a colon and includes ids of all naming container parents, such as ":form:button1", or it can be a relative identifier that refers to another child in the same naming container, for example "button2". The formal rules of finding the component by identifier are described in API reference for the UIComponent.findComponent() method.
  • 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 <input id="myHtmlButton" type="button" value="Test"/> you should use the ":myHtmlButton" value of the for attribute.

Here is an example of tracking scroll position for an HTML element by its identifier:

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

  </div>
</h:form>

Note that if the value attributes is used with the for attribute then the appropriate coordinates will be applied to the specified scrollable component.

Tracking Scroll Position For the Entire Application

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

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