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:

You should avoid applying AJAX directly on the fleXcroll div, as this will clear the scrollbars, which are children of the fleXcroll applied div.
For AJAX content, create another div inside the fleXcroll div.
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.

Example - Testing of fleXcroll methods - Javascript

if (yourDivElement.fleXcroll) yourDivElement.fleXcroll.setScrollPos(false,100);

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

Following method updates all fleXcroll scrollbars in the document.
- Application of fleXcroll using id - Javascript
```
fleXenv.updateScrollBars();
```

Manually Applying fleXcroll to your div

For various reasons, you may need to run fleXcroll at a specific point in your javascript, for example, you may use your own DomContentLoaded code, or you may apply fleXcroll to a div that is not present on page load. Make sure the DOM contents are fully loaded, or otherwise fleXcroll may not initialize properly or initialize at all.
- Application of fleXcroll using id - Javascript
```
fleXenv.fleXcrollMain("your-div-id");
```
- Application of fleXcroll using javascript element - Javascript
```
fleXenv.fleXcrollMain(yourDivElement);
```
- Application of fleXcroll using a custom class - Javascript
```
fleXenv.initByClass("a-class-name-of-your-choice");
```

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)

Example - Setting scroll position - Javascript

yourDivElement.fleXcroll.setScrollPos(false,200);

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

Scroll 150 pixels to the right, and 50 pixels upwards ->
- Example - doing relative scrolls in pixels - Javascript
```
yourDivElement.fleXcroll.scrollContent(150,-50);
```
Scroll 1.5 pages down ->
- Example - doing relative scrolls in pixels - Javascript
```
yourDivElement.fleXcroll.scrollContent(false,"1.5p");
```

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

Running code after fleXcroll initializes- Javascript

window.onfleXcrollRun=function(){ 
//your code that will be run after fleXcroll goes here. 

}

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.

Running code after fleXcroll initializes- Javascript

yourDivElement.onfleXcroll=function(){ 
//your code that will be run after user scrolls goes here. 

}

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!