fleXcroll V2.1.1 Programming Guide -updated:02.02.2013

This guide is for advanced users who needs extra functions for their javascript applications, if you only need scrollbars, please see the Basic usage guide.

fleXcroll and AJAX applications

fleXcroll supports dynamic content, either through AJAX applications, or any content that may be generated within javascript. For fleXcroll to work properly with dynamic content you need to consider the following:

  1. You should avoid applying AJAX directly on the fleXcroll div, as this will clear the scrollbars, which are children of the fleXcroll applied div.
  2. For AJAX content, create another div inside the fleXcroll div.
  3. After your AJAX script injects the new content, you should tell fleXcroll to update the scrollbars.
    • Some AJAX libraries may provide an on-content-load event, you can use this to call fleXcroll update. This method ensures you don't have to modify your AJAX library.
    • If the on-content-load event is not provided, you will have to edit your AJAX libary to call fleXcroll update right after it injects new content (these libaries use .innerHTML for pushing the new content, so you can find this line and add fleXcroll update call below it.)

Graceful degradation / progressive enhancement

fleXcroll may not always work in a browser, there may be times it will not initialize. Therefore, you should test for fleXcroll object tied to your element before doing anything fleXcroll related, or try to test if the fleXcroll method exists before applying the method.

This is actually a good coding practice, and should be employed not only for fleXcroll commands, but to other parts of your scripts. Your scripts should go on operating without having to depend on the performance of a particular script or browser.

fleXcroll and hidden divs, and fleXcroll usage with tab / accordeon scripts

  • Older versions of fleXcroll used to break when user attempted auto-initializing, but this is fixed as of version 2.0. Still, fleXcroll will not update any scrollbars on hidden divs, because it cannot calculate content and container sizes.
  • If you are hiding the fleXcroll div first, you need fleXcroll to update itself whenever the div gets shown (recommended). You can also manually initialize fleXcroll on the hidden div, after it gets shown.
  • Since most tab scripts hide the contained divs, you need to modify your tab / accordeon scripts to update fleXcroll scrollbars after the tab / accordeon piece gets shown.
  • Basic fleXcroll scrollbar update

    Manually Applying fleXcroll to your div

    Reading scroll values

    You can read the current scroll values through yourDivElement.fleXdata.scrollPosition, where yourDivElement refers to the fleXcrolled element in your Javascript.

    The scroll value information is stored in pixel units as an array in the following format: [[currentXscrollPos,maxXscrollPos],[currentYscrollPos,maxYscrollPos]], which translates as:

    yourDivElement.fleXdata.scrollPosition[0][0]
    Contains the current horizontal scroll amount in pixels, false if there's no horizontal scrollbar.
    yourDivElement.fleXdata.scrollPosition[0][1]
    Contains the current maximum scroll amount in pixels, false if there's no horizontal scrollbar.
    yourDivElement.fleXdata.scrollPosition[1][0]
    Contains the current vertical scroll amount in pixels, false if there's no vertical scrollbar.
    yourDivElement.fleXdata.scrollPosition[1][1]
    Contains the current maximum scroll amount in pixels, false if there's no vertical scrollbar.

    Setting scroll positions

    You may set a scroll position using yourDivElement.fleXcroll.setScrollPos(horizontal_scroll_position, vertical_scroll_position)

    This sets the vertical scroll positon, 200 pixels down. The function also returns the scroll positions in the same format as yourDivElement.fleXdata.scrollPosition.

    Scrolling relatively

    To scroll by a given amount, you can use yourDivElement.fleXcroll.scrollContent(horizontal_scroll_amount, vertical_scroll_amount):

    The function also returns the scroll positions in the same format as yourDivElement.fleXdata.scrollPosition.

    Running code after fleXcroll initializes

    When you require a piece of your code to activate after fleXcroll initializes (e.g. please see the fleXnewsticker example in the example archive) you have to define a function named window.onfleXcrollRun

    Pseudo-event: onfleXcroll

    When a scroll is done either by javascript or by the user, the function onfleXcroll is run. It doesn't work like usual events, it supports none of the DOM event properties. It just allows you to know that a scroll is done and execute a piece of code.

    List of fleXcroll functions in the window scope

    fleXenv.updateScrollBars()
    This function updates all of the fleXcroll applied elements. You use this whenever you have added / removed new content or changed the size of or contents in a fleXcroll div. For asynchronous AJAX updates or animations, you should call this right after the content / size changes are made. Decent AJAX and animation libraries provide call-backs that let you execute functions after content changes are complete.
    fleXenv.fleXcrollMain(element)
    element -> {HTMLElement|"id-string"} : Use this to manually apply fleXcroll to given element. The function accepts elements or id strings. If fleXcroll is already applied, this will call a scrollbar update. So you can use this to manually apply fleXcroll to initially-hidden divs, when the div gets shown.
    fleXenv.initByClass("classname")
    "classname" : apply fleXcroll to all div elements with given classname, use this to apply fleXcroll manually to divs with given class, when you don't want to use automatic starting of fleXcroll with "flexcroll" class.
    fleXenv.scrollTo(element)
    element -> {HTMLElement|"id-string"} : Use this to scroll to an element inside a fleXcroll div, you don't have to specify the fleXcroll div. The function accepts elements or id strings.

    List of fleXcroll functions tied to the fleXcroll div

    yourDivElement.fleXcroll.updateScrollBars()
    Use this if you want a div to be specifically updated, without touching other fleXcroll divs. May be useful if you have lots of fleXcroll divs and update only the necessary fleXcroll div.
    yourDivElement.fleXcroll.setScrollPos(horizontal_scroll_position, vertical_scroll_position, relative, prevent_event)
    horizontal_scroll_position -> {integer} : sets the horizontal scroll position, in pixels.
    vertical_scroll_position -> {integer} : sets the vertical scroll position, in pixels.
    relative -> {false|true} : If set to true, the function acts like yourDivElement.fleXcroll.scrollContent()
    prevent_event -> {false|true} : If set to true, yourDivElement.onfleXcroll() is not run after scroll position is set. You can use this to avoid infinite loops on certain occasions.
    yourDivElement.fleXcroll.scrollContent(horizontal_scroll_amount, vertical_scroll_amount)
    horizontal_scroll_amount -> {integer||"string"} : scrolls in given pixels in horizontal direction. If given in integers, the scroll is done in pixels. If given in string format "1p", scrolls 1 page. "0.5p" scrolls half a page. Accepts negative values.
    vertical_scroll_amount -> {integer||"string"} : scrolls in given pixels in vertical direction. If given in integers, the scroll is done in pixels. If given in string format "1p", scrolls 1 page. "0.5p" scrolls half a page. Accepts negative values.

    Please see the Basic usage guide if these don't mean anything to you!

    Back to fleXcroll page