jScrollPane - API documentation

This page shows how you can use the jScrollPane API (in addition to the settings object and the events which are dispatched) to update your jScrollPane after it's has been initially created.

To get a reference to the API for a particular scrollpane you will need to access the 'jsp' variable in the data of the element you applied jScrollPane to. e.g.

var element = $('#my-element').jScrollPane({/* ...settings... */});
var api = element.data('jsp');

Once you have a reference to the API you can call any of the following methods on it:

reinitialise(s)

Reinitialises the scroll pane (if it's internal dimensions have changed since the last time it was initialised). The settings object which is passed in will override any settings from the previous time it was initialised - if you don't pass any settings then the ones from the previous initialisation will be used.

scrollToElement(ele, stickToTop, animate)

Scrolls the specified element (a jQuery object, DOM node or jQuery selector string) into view so that it can be seen within the viewport. If stickToTop is true then the element will appear at the top of the viewport, if it is false then the viewport will scroll as little as possible to show the element. You can also specify if you want animation to occur. If you don't provide this argument then the animateScroll value from the settings object is used instead.

scrollTo(destX, destY, animate)

Scrolls the pane so that the specified co-ordinates within the content are at the top left of the viewport. animate is optional and if not passed then the value of animateScroll from the settings object this jScrollPane was initialised with is used.

scrollToX(destX, animate)

Scrolls the pane so that the specified co-ordinate within the content is at the left of the viewport. animate is optional and if not passed then the value of animateScroll from the settings object this jScrollPane was initialised with is used.

scrollToY(destY, animate)

Scrolls the pane so that the specified co-ordinate within the content is at the top of the viewport. animate is optional and if not passed then the value of animateScroll from the settings object this jScrollPane was initialised with is used.

scrollToPercentX(destPercentX, animate)

Scrolls the pane to the specified percentage of its maximum horizontal scroll position. animate is optional and if not passed then the value of animateScroll from the settings object this jScrollPane was initialised with is used.

scrollToPercentY(destPercentY, animate)

Scrolls the pane to the specified percentage of its maximum vertical scroll position. animate is optional and if not passed then the value of animateScroll from the settings object this jScrollPane was initialised with is used.

scrollBy(deltaX, deltaY, animate)

Scrolls the pane by the specified amount of pixels. animate is optional and if not passed then the value of animateScroll from the settings object this jScrollPane was initialised with is used.

scrollByX(deltaX, animate)

Scrolls the pane by the specified amount of pixels. animate is optional and if not passed then the value of animateScroll from the settings object this jScrollPane was initialised with is used.

scrollByY(deltaY, animate)

Scrolls the pane by the specified amount of pixels. animate is optional and if not passed then the value of animateScroll from the settings object this jScrollPane was initialised with is used.

positionDragX(x, animate)

Positions the horizontal drag at the specified x position (and updates the viewport to reflect this). animate is optional and if not passed then the value of animateScroll from the settings object this jScrollPane was initialised with is used.

positionDragY(y, animate)

Positions the vertical drag at the specified y position (and updates the viewport to reflect this). animate is optional and if not passed then the value of animateScroll from the settings object this jScrollPane was initialised with is used.

animate(ele, prop, value, stepCallback, completeCallback)

This method is called when jScrollPane is trying to animate to a new position. You can override it if you want to provide advanced animation functionality. It is passed the following arguments:

ele - the element whose position is being animated
prop - the property that is being animated
value - the value it's being animated to
stepCallback - a function that you must execute each time you update the value of the property
completeCallback - a function that will be executed after the animation had finished

You can use the default implementation (see sourcecode) as a starting point for your own implementation.

getContentPositionX()

Returns the current x position of the viewport with regards to the content pane.

getContentPositionY()

Returns the current y position of the viewport with regards to the content pane.

getContentWidth()

Returns the width of the content within the scroll pane.

getContentHeight()

Returns the height of the content within the scroll pane.

getIsScrollableH()

Returns whether or not this scrollpane has a horizontal scrollbar.

getPercentScrolledX()

Returns the horizontal position of the viewport within the pane content.

getPercentScrolledY()

Returns the vertical position of the viewport within the pane content.

getIsScrollableV()

Returns whether or not this scrollpane has a vertical scrollbar.

getContentPane()

Gets a reference to the content pane. It is important that you use this method if you want to edit the content of your jScrollPane as if you access the element directly then you may have some problems (as your original element has had additional elements for the scrollbars etc added into it).

scrollToBottom(animate)

Scrolls this jScrollPane down as far as it can currently scroll. If animate isn't passed then the animateScroll value from settings is used instead.

hijackInternalLinks()

Hijacks the links on the page which link to content inside the scrollpane. If you have changed the content of your page (e.g. via AJAX) and want to make sure any new anchor links to the contents of your scroll pane will work then call this function.

destroy()

Destroys the jScrollPane on the instance matching this API object and restores the browser's default behaviour. Example.