scroll.js revision be9626f6dd0214b95bf03baeb5d0202850ec5b4d
/**
Adds the ability to make the table rows scrollable while preserving the header
placement.
There are two types of scrolling, horizontal (x) and vertical (y). Horizontal
scrolling is achieved by wrapping the entire table in a scrollable container.
Vertical scrolling is achieved by splitting the table headers and data into two
separate tables, the latter of which is wrapped in a vertically scrolling
container. In this case, column widths of header cells and data cells are kept
in sync programmatically.
Since the split table synchronization can be costly at runtime, the split is only done if the data in the table stretches beyond the configured `height` value.
To activate or deactivate scrolling, set the `scrollable` attribute to one of
the following values:
* `false` - (default) Scrolling is disabled.
* `true` or 'xy' - If `height` is set, vertical scrolling will be activated, if
`width` is set, horizontal scrolling will be activated.
* 'x' - Activate horizontal scrolling only. Requires the `width` attribute is
also set.
* 'y' - Activate vertical scrolling only. Requires the `height` attribute is
also set.
@module datatable-scroll
@class DataTable.Scrollable
@for DataTable
**/
Scrollable.ATTRS = {
/**
Activates or deactivates scrolling in the table. Acceptable values are:
* `false` - (default) Scrolling is disabled.
* `true` or 'xy' - If `height` is set, vertical scrolling will be activated, if
`width` is set, horizontal scrolling will be activated.
* 'x' - Activate horizontal scrolling only. Requires the `width` attribute is
also set.
* 'y' - Activate vertical scrolling only. Requires the `height` attribute is
also set.
@attribute scrollable
@type {String|Boolean}
@value false
**/
scrollable: {
value: false,
setter: '_setScrollable'
}
};
/**
Scrolls a given row or cell into view if the table is scrolling. Pass the
`clientId` of a Model from the DataTable's `data` ModelList or its row
index to scroll to a row or a [row index, column index] array to scroll to
a cell. Alternately, to scroll to any element contained within the table's
scrolling areas, pass its ID, or the Node itself (though you could just as
well call `node.scrollIntoView()` yourself, but hey, whatever).
@method scrollTo
@param {String|Number|Number[]|Node} id A row clientId, row index, cell
coordinate array, id string, or Node
@return {DataTable}
@chainable
**/
var target;
// TODO: ancestor(yScrollNode, xScrollNode)
}
}
return this;
},
//--------------------------------------------------------------------------
// Protected properties and methods
//--------------------------------------------------------------------------
/**
Template for the `<table>` that is used to fix the caption in place when
the table is horizontally scrolling.
@property _CAPTION_TABLE_TEMPLATE
@type {HTML}
@value '<table class="{className}" role="presentation"></table>'
@protected
**/
_CAPTION_TABLE_TEMPLATE: '<table class="{className}" role="presentation"></table>',
/**
Template used to create sizable element liners around header content to
synchronize fixed header column widths.
@property _SCROLL_LINER_TEMPLATE
@type {HTML}
@value '<div class="{className}"></div>'
@protected
**/
_SCROLL_LINER_TEMPLATE: '<div class="{className}"></div>',
/**
Template for the virtual scrollbar needed in "y" and "xy" scrolling setups.
@property _SCROLLBAR_TEMPLATE
@type {HTML}
@value '<div class="{className}"><div></div></div>'
@protected
**/
_SCROLLBAR_TEMPLATE: '<div class="{className}"><div></div></div>',
/**
Template for the `<div>` that is used to contain the table when the table is
horizontally scrolling.
@property _X_SCROLLER_TEMPLATE
@type {HTML}
@value '<div class="{className}"></div>'
@protected
**/
_X_SCROLLER_TEMPLATE: '<div class="{className}"></div>',
/**
Template for the `<table>` used to contain the fixed column headers for
vertically scrolling tables.
@property _Y_SCROLL_HEADER_TEMPLATE
@type {HTML}
@value '<table role="presentation" aria-hidden="true" class="{className}"></table>'
@protected
**/
_Y_SCROLL_HEADER_TEMPLATE: '<table role="presentation" aria-hidden="true" class="{className}"></table>',
/**
Template for the `<div>` that is used to contain the rows when the table is
vertically scrolling.
@property _Y_SCROLLER_TEMPLATE
@type {HTML}
@value '<div class="{className}"></div>'
@protected
**/
_Y_SCROLLER_TEMPLATE: '<div class="{className}"></div>',
/**
Adds padding to the last cells in the fixed header for vertically scrolling
tables. This padding is equal in width to the scrollbar, so can't be
relegated to a stylesheet.
@method _addScrollbarPadding
@protected
**/
_addScrollbarPadding: function () {
var fixedHeader = this._yScrollHeader,
if (fixedHeader) {
}
}
},
/**
Reacts to changes in the `scrollable` attribute by updating the `_xScroll`
and `_yScroll` properties and syncing the scrolling structure accordingly.
@method _afterScrollableChange
@param {EventFacade} e The relevant change event (ignored)
@protected
**/
_afterScrollableChange: function (e) {
this._syncScrollUI();
},
/**
Reacts to changes in the `caption` attribute by adding, removing, or
syncing the caption table when the table is set to scroll.
@method _afterScrollCaptionChange
@param {EventFacade} e The relevant change event (ignored)
@protected
**/
_afterScrollCaptionChange: function (e) {
this._syncScrollUI();
}
},
/**
Reacts to changes in the `columns` attribute of vertically scrolling tables
by refreshing the fixed headers, scroll container, and virtual scrollbar
position.
@method _afterScrollColumnsChange
@param {EventFacade} e The relevant change event (ignored)
@protected
**/
_afterScrollColumnsChange: function (e) {
if (this._yScroll && this._yScrollHeader) {
this._syncScrollHeaders();
}
this._syncScrollUI();
}
},
/**
Reacts to changes in vertically scrolling table's `data` ModelList by
synchronizing the fixed column header widths and virtual scrollbar height.
@method _afterScrollDataChange
@param {EventFacade} e The relevant change event (ignored)
@protected
**/
_afterScrollDataChange: function (e) {
this._syncScrollUI();
}
},
/**
Reacts to changes in the `height` attribute of vertically scrolling tables
by updating the height of the `<div>` wrapping the data table and the
virtual scrollbar. If `scrollable` was set to "y" or "xy" but lacking a
declared `height` until the received change, `_syncScrollUI` is called to
create the fixed headers etc.
@method _afterScrollHeightChange
@param {EventFacade} e The relevant change event (ignored)
@protected
**/
_afterScrollHeightChange: function (e) {
if (this._yScroll) {
this._syncScrollUI();
}
},
/**
Reacts to changes in the width of scrolling tables by expanding the width of
the `<div>` wrapping the data table for horizontally scrolling tables or
upding the position of the virtual scrollbar for vertically scrolling
tables.
@method _afterScrollWidthChange
@param {EventFacade} e The relevant change event (ignored)
@protected
**/
_afterScrollWidthChange: function (e) {
this._syncScrollUI();
}
},
/**
Binds virtual scrollbar interaction to the `_yScrollNode`'s `scrollTop` and
vice versa.
@method _bindScrollbar
@protected
**/
_bindScrollbar: function () {
var scrollbar = this._scrollbarNode,
scroller = this._yScrollNode;
]);
}
},
/**
Binds to the window resize event to update the vertical scrolling table
headers and wrapper `<div>` dimensions.
@method _bindScrollResize
@protected
**/
_bindScrollResize: function () {
if (!this._scrollResizeHandle) {
// TODO: sync header widths and scrollbar position. If the height
// of the headers has changed, update the scrollbar dims as well.
this._syncScrollUI, null, this);
}
},
/**
Attaches internal subscriptions to keep the scrolling structure up to date
with changes in the table's `data`, `columns`, `caption`, or `height`. The
`width` is taken care of already.
This executes after the table's native `bindUI` method.
@method _bindScrollUI
@protected
**/
_bindScrollUI: function () {
this.after({
});
Y.bind('_afterScrollDataChange', this));
},
/**
Clears the lock and timer used to manage synchronizing the scroll position
between the vertical scroll container and the virtual scrollbar.
@method _clearScrollLock
@protected
**/
_clearScrollLock: function () {
if (this._scrollLock) {
this._scrollLock.cancel();
delete this._scrollLock;
}
},
/**
Creates a virtual scrollbar from the `_SCROLLBAR_TEMPLATE`, assigning it to
the `_scrollbarNode` property.
@method _createScrollbar
@return {Node} The created Node
@protected
**/
_createScrollbar: function () {
var scrollbar = this._scrollbarNode;
if (!scrollbar) {
}));
}
return scrollbar;
},
/**
Creates a separate table to contain the caption when the table is
configured to scroll vertically or horizontally.
@method _createScrollCaptionTable
@return {Node} The created Node
@protected
**/
_createScrollCaptionTable: function () {
if (!this._captionTable) {
}));
}
return this._captionTable;
},
/**
Populates the `_xScrollNode` property by creating the `<div>` Node described
by the `_X_SCROLLER_TEMPLATE`.
@method _createXScrollNode
@return {Node} The created Node
@protected
**/
_createXScrollNode: function () {
if (!this._xScrollNode) {
}));
}
return this._xScrollNode;
},
/**
Populates the `_yScrollHeader` property by creating the `<table>` Node
described by the `_Y_SCROLL_HEADER_TEMPLATE`.
@method _createYScrollHeader
@return {Node} The created Node
@protected
**/
_createYScrollHeader: function () {
var fixedHeader = this._yScrollHeader;
if (!fixedHeader) {
}));
// Needed for IE which creates an empty <tbody> in the table
fixedHeader.empty();
}
return fixedHeader;
},
/**
Populates the `_yScrollNode` property by creating the `<div>` Node described
by the `_Y_SCROLLER_TEMPLATE`.
@method _createYScrollNode
@return {Node} The created Node
@protected
**/
_createYScrollNode: function () {
if (!this._yScrollNode) {
}));
}
return this._yScrollNode;
},
/**
Removes the nodes used to create horizontal and vertical scrolling and
rejoins the caption to the main table if needed.
@method _disableScrolling
@protected
**/
_disableScrolling: function () {
this._removeScrollCaptionTable();
this._disableXScrolling();
this._disableYScrolling();
this._unbindScrollResize();
},
/**
Removes the nodes used to allow horizontal scrolling.
@method _disableXScrolling
@protected
**/
_disableXScrolling: function () {
this._removeXScrollNode();
},
/**
Removes the nodes used to allow vertical scrolling.
@method _disableYScrolling
@protected
**/
_disableYScrolling: function () {
this._removeYScrollHeader();
this._removeYScrollNode();
this._removeScrollbar();
},
/**
Cleans up external event subscriptions.
@method destructor
@protected
**/
destructor: function () {
this._unbindScrollbar();
this._unbindScrollResize();
this._clearScrollLock();
},
/**
Sets up event handlers and AOP advice methods to bind the DataTable's natural
behaviors with the scrolling APIs and state.
@method initializer
@param {Object} config The config object passed to the constructor (ignored)
@protected
**/
initializer: function () {
this._setScrollProperties();
this._setScrollProperties);
},
/**
Removes the table used to house the caption when the table is scrolling.
@method _removeScrollCaptionTable
@protected
**/
_removeScrollCaptionTable: function () {
if (this._captionTable) {
if (this._captionNode) {
}
delete this._captionTable;
}
},
/**
Removes the `<div>` wrapper used to contain the data table when the table
is horizontally scrolling.
@method _removeXScrollNode
@protected
**/
_removeXScrollNode: function () {
var scroller = this._xScrollNode;
if (scroller) {
delete this._yScrollNode;
}
},
/**
Removes the `<table>` used to contain the fixed column headers when the
table is vertically scrolling.
@method _removeYScrollHeader
@protected
**/
_removeYScrollHeader: function () {
if (this._yScrollHeader) {
delete this._yScrollHeader;
}
},
/**
Removes the `<div>` wrapper used to contain the data table when the table
is vertically scrolling.
@method _removeYScrollNode
@protected
**/
_removeYScrollNode: function () {
if (this._yScrollNode) {
delete this._yScrollNode;
}
},
/**
Removes the virtual scrollbar used by scrolling tables.
@method _removeScrollbar
@protected
**/
_removeScrollbar: function () {
if (this._scrollbarNode) {
delete this._scrollBarNode;
}
},
/**
Accepts (case insensitive) values "x", "y", "xy", `true`, and `false`.
`true` is translated to "xy" and upper case values are converted to lower
case. All other values are invalid.
@method _setScrollable
@param {String|Boolea} val Incoming value for the `scrollable` attribute
@return {String}
@protected
**/
_setScrollable: function (val) {
if (val === true) {
val = 'xy';
}
}
val :
},
/**
Assigns the `_xScroll` and `_yScroll` properties to true if an
appropriate value is set in the `scrollable` attribute and the `height`
@method _setScrollProperties
@protected
**/
_setScrollProperties: function () {
},
/**
Keeps the virtual scrollbar and the scrolling `<div>` wrapper around the
data table in vertically scrolling tables in sync.
@method _syncScrollPosition
@param {DOMEventFacade} e The scroll event
@param {String} [source] The string "virtual" if the event originated from
the virtual scrollbar
@protected
**/
_syncScrollPosition: function (e, source) {
var scrollbar = this._scrollbarNode,
scroller = this._yScrollNode;
return;
}
this._clearScrollLock();
if (source === 'virtual') {
} else {
}
}
},
/**
Splits or merges the table for X and Y scrolling depending on the current
widget state. If the table needs to be split, but is already, does nothing.
@method _syncScrollUI
@protected
**/
_syncScrollUI: function () {
this._uiSetScrollable();
this._syncScrollCaptionUI();
this._syncXYScrollUI();
} else if (this._xScroll) {
this._disableYScrolling();
this._syncScrollCaptionUI();
this._syncXScrollUI();
} else if (this._yScroll) {
this._disableXScrolling();
this._syncScrollCaptionUI();
this._syncYScrollUI();
} else {
this._disableScrolling();
}
},
/*
if (
if (this._yScroll || this._xScroll) {
this._uiSetDim('width', '');
}
this._syncScrollCaptionUI();
this._syncXScrollUI();
this._syncYScrollUI();
if (this._yScroll || this._xScroll) {
if (this._captionTable) {
width = (this._xScrollNode || this._tableNode)
.get('offsetWidth') + 'px';
this._captionTable.setStyle('width', width);
}
this._uiSetDim('width', this.get('width'));
if (this._scrollbarNode) {
this._syncScrollbarHeight();
this._syncScrollbarPosition();
}
}
},
*/
/**
Splits the caption from the data `<table>` if the table is configured to
scroll. If not, rejoins the caption to the data `<table>` if it needs to
be.
@method _syncScrollCaptionUI
@protected
**/
_syncScrollCaptionUI: function () {
var caption = this._captionNode,
table = this._tableNode,
captionTable = this._captionTable,
id;
if (caption) {
if (!captionTable) {
captionTable = this._createScrollCaptionTable();
}
if (!id) {
}
}
} else if (captionTable) {
this._removeScrollCaptionTable();
}
},
/**
Assigns widths to the fixed header columns to match the columns in the data
table.
@method _syncScrollColumnWidths
@protected
**/
_syncScrollColumnWidths: function () {
var headers;
if (this._theadNode && this._yScrollHeader) {
padding = [
];
// Can't use getComputedStyle('width') because IE 7- return
// the <col>'s width even though it's not honoring it.
});
}
},
/**
Creates matching headers in the fixed header table for vertically scrolling
tables and synchronizes the column widths.
@method _syncScrollHeaders
@protected
**/
_syncScrollHeaders: function () {
var fixedHeader = this._yScrollHeader,
linerTemplate = this._SCROLL_LINER_TEMPLATE,
if (this._theadNode && fixedHeader) {
this._theadNode.cloneNode(true));
// Prevent duplicate IDs and assign ARIA attributes to hide
// from screen readers
.removeAttribute('id')
.setAttribute('aria-hidden', true);
}));
}, this);
this._syncScrollColumnWidths();
this._addScrollbarPadding();
}
},
/**
Wraps the table in a scrolling `<div>` of the configured width for "x"
scrolling.
@method _syncXScrollUI
@protected
**/
_syncXScrollUI: function () {
scroller = this._xScrollNode,
table = this._tableNode,
captionTable = this._captionTable,
this._bindScrollResize();
} else {
this._unbindScrollResize();
}
if (captionTable) {
}
if (!scroller) {
scroller = this._createXScrollNode();
}
// Can't use offsetHeight - clientHeight because IE6 returns
// clientHeight of 0 intially.
// Lock the table width to avoid configured column widths being ignored
// Can't use 100% width because the borders add additional width
// TODO: Cache the border widths, though it won't prevent a reflow
// expand the table to fill the assigned width if it doesn't
// already overflow the configured width
// Assumes the wrapped table doesn't have borders
}
},
/**
Wraps the table in vertically and horizontally scrolling `<div>`s for "xy"
scrolling.
@method _syncXYScrollUI
@protected
**/
_syncXYScrollUI: function () {
/*
var boundingBox = this.get('boundingBox'),
xScroller = this._xScrollNode,
yScroller = this._yScrollNode,
fixedHeader = this._yScrollHeader,
scrollbar = this._scrollbarNode,
table = this._tableNode,
width = this.get('width'),
borderWidth;
*/
},
/**
Wraps the table in a scrolling `<div>` of the configured height (accounting
for the caption if there is one) if "y" scrolling is enabled. Otherwise,
unwraps the table if necessary.
@method _syncYScrollUI
@protected
**/
_syncYScrollUI: function () {
var scroller = this._yScrollNode,
fixedHeader = this._yScrollHeader,
scrollbar = this._scrollbarNode,
table = this._tableNode,
thead = this._theadNode,
captionTable = this._captionTable,
if (captionTable) {
}
if (!scroller) {
scroller = this._createYScrollNode();
}
this._uiSetYScrollWidth(width);
if (captionTable) {
}
// Allow headerless scrolling
if (thead && !fixedHeader) {
fixedHeader = this._createYScrollHeader();
this._syncScrollHeaders();
}
if (fixedHeader) {
if (!scrollbar) {
scrollbar = this._createScrollbar();
this._bindScrollbar();
}
this._syncScrollColumnWidths();
this._uiSetScrollbarHeight();
this._uiSetScrollbarPosition();
}
},
/**
Assigns the appropriate class to the `boundingBox` to identify the DataTable
as horizontally scrolling, vertically scrolling, or both (adds both classes).
Classes added are "yui3-datatable-scrollable-x" or "...-y"
@method _uiSetScrollable
@protected
**/
_uiSetScrollable: function () {
this.get('boundingBox')
},
/**
Updates the virtual scrollbar's height to avoid overlapping with the fixed
headers.
@method _uiSetScrollbarHeight
@protected
**/
_uiSetScrollbarHeight: function () {
var scrollbar = this._scrollbarNode,
scroller = this._yScrollNode,
fixedHeader = this._yScrollHeader;
}
},
/**
Updates the virtual scrollbar's placement to avoid overlapping the fixed
headers or the data table.
@method _uiSetScrollbarPosition
@protected
**/
_uiSetScrollbarPosition: function () {
var scrollbar = this._scrollbarNode,
fixedHeader = this._yScrollHeader,
top;
if (fixedHeader) {
} else {
'px';
}
});
}
},
/**
Assigns the height to the `<div>` wrapper around the data table for
vertically scrolling tables.
@method _uiSetYScrollHeight
@param {Number} height The pixel height of the container
@protected
**/
_uiSetYScrollHeight: function (height) {
var scroller = this._yScrollNode,
// because IE6 is returning clientHeight 0 initially *grumble*
},
/**
Assigns the width of the `<div>` wrapping the data table in vertically
scrolling tables.
If the table can't compress to the specified width, the container is
expanded accordingly.
@method _uiSetYScrollWidth
@param {String} width The CSS width to attempt to set
@protected
**/
_uiSetYScrollWidth: function (width) {
var scroller = this._yScrollNode,
table = this._tableNode,
if (width) {
this._bindScrollResize();
} else {
this._unbindScrollResize();
}
// Assumes no table border
// The table's rendered width might be greater than the
// configured width
// Have to subtract the border width from the configured width
// because the scroller's width will need to be reduced by the
// border width as well during the width reassignment below.
// Assumes no table borders
// Expand the scroll node width if the table can't fit.
// Otherwise, reassign the scroller a pixel width that
// accounts for the borders.
//this._uiSetDim('width', width);
} else {
this._unbindScrollResize();
// Allow the table to expand naturally
}
}
},
/**
Detaches the scroll event subscriptions used to maintain scroll position
parity between the scrollable `<div>` wrapper around the data table and the
virtual scrollbar for vertically scrolling tables.
@method _unbindScrollbar
@protected
**/
_unbindScrollbar: function () {
if (this._scrollbarEventHandle) {
this._scrollbarEventHandle.detach();
}
},
/**
Detaches the resize event subscription used to maintain column parity for
vertically scrolling tables with percentage widths.
@method _unbindScrollResize
@protected
**/
_unbindScrollResize: function () {
if (this._scrollResizeHandle) {
this._scrollResizeHandle.detach();
delete this._scrollResizeHandle;
}
}
/**
Indicates horizontal table scrolling is enabled.
@property _xScroll
@type {Boolean}
@default undefined (not initially set)
@private
**/
//_xScroll: null,
/**
Indicates vertical table scrolling is enabled.
@property _yScroll
@type {Boolean}
@default undefined (not initially set)
@private
**/
//_yScroll: null,
/**
Fixed column header `<table>` Node for vertical scrolling tables.
@property _yScrollHeader
@type {Node}
@default undefined (not initially set)
@protected
**/
//_yScrollHeader: null,
/**
Overflow Node used to contain the data rows in a vertically scrolling table.
@property _yScrollNode
@type {Node}
@default undefined (not initially set)
@protected
**/
//_yScrollNode: null,
/**
Overflow Node used to contain the table headers and data in a horizontally
scrolling table.
@property _xScrollNode
@type {Node}
@default undefined (not initially set)
@protected
**/
//_xScrollNode: null
}, true);