angular-ui-scroll
Advanced tools
The common way to present to the user a list of data elements of undefined length is to start with a small portion at the top of the list - just enough to fill the space on the page. Additional rows are appended to the bottom of the list as the user scrolls down the list.
The problem with this approach is that even though rows at the top of the list become invisible as they scroll out of the view, they are still a part of the page and still consume resources. As the user scrolls down the list grows and the web app slows down.
This becomes a real problem if the html representing a row has event handlers and/or angular watchers attached. A web app of an average complexity can easily introduce 20 watchers per row. Which for a list of 100 rows gives you total of 2000 watchers and a sluggish app.
The uiScroll directive solves the problem just described by dynamically destroying elements as they become invisible and recreating them if they become visible again.
The uiScroll directive is similar to the ngRepeat. Like the ngRepeat, uiScroll directive instantiates a template once per item from a collection. Each template instance gets its own scope, where the given loop variable is set to the current collection item. The collection content is provided by the datasource.
The directive is asking the datasource for data to build and render elements until it has enough elements to fill out the viewport. It will start retrieving new data for new elements again if the user scrolls up/down to the edge of visible element list.
<ANY ui-scroll="{scroll_expression}" buffer-size="value" ... >
...
</ANY>
Listing ANY for the tag, the directive can be applied to, stretches the truth - a little bit. The directive works well with majority
of the 'usual' tags - divs, spans, a, inputs, etc. For all of them the viewport should be a div (unless it is the window). Some other
tags require special treatment. If the repeated tag is a li, it is best to use ul or ol as a viewport. For a tr as a repeated tag the
viewport has to be the table or tbody. dl as a repeated tag is not supported.
The viewport is an element representing the space where the items from the collection are to be shown. Unless specified explicitly with the uiScrollViewport directive, browser window will be used as the viewport.
Important! The viewport height must be constrained. If the height of the viewport is not constrained (style="height:auto") it will pull the entire content of the datasource and may throw an Error depending on the number of items in the datasource. Even if it does not, using the directive this way does not provide any advantages over using ng-repeat, because item template will be always instantiated for every item in the datasource.
We have built pull of examples covering a number of use-cases, showing various ways to use the ui-scroll directive. Each demo is absolutely independent and has its own html-page and the javascript file with the same name and .js extension.
To run the examples use this link.
To install the package via npm use
npm install --save angular-ui-scroll
After installation, the ui-scroll distributive files will be available as
<script src="node_modules/angular-ui-scroll/dist/ui-scroll.min.js">
<script src="node_modules/angular-ui-scroll/dist/ui-scroll-grid.min.js">
There are also uncompressed versions (ui-scroll.js, ui-scroll-grid.js) and sourcemaps for all of js-files.
To use it in your angular-app you should add the module (modules)
angular.module('application', ['ui.scroll', 'ui.scroll.grid'])
Currently we have 2 regular modules which can be added to the angular-app you are developing.
Also there is one more additional module in a separate file
ui.scroll.jqlite module It is empty since it was deprecated in v1.6.0.
<div ui-scroll="item in myDatasource"
buffer-size="5"
padding="1"
start-index="100"
adapter="myAdapter"
>{{item}}</div>
variable in datasource – where variable is the user defined loop variable and datasource is the name of the data source to enumerate.Some of the properties offered by the adapter can also be accessed directly from the directive by using matching attributes. In the same way as for the adapter attribute, syntax for such attributes allows for providing a reference expression to be used to access the corresponding value. Below is a list of such attributes:
isLoading adapter property.topVisible adapter property.topVisibleElement adapter property.topVisibleScope adapter property.The expression can be any angular expression (assignable expression where so specified). All expressions are evaluated once at the time when the scroller is initialized. Changes in the expression value after scroller initialization will have no impact on the scroller behavior.
The assignable expressions will be used by scroller to inject the requested value into the target scope. The scope associated with the viewport (the element marked with the uiScrollViewport directive) will be used as the target scope. If the viewport is not defined (window viewport), the $rootScope will be used as the target scope. Note that the nearest additional scope-wrapper (like ng-if directive set right on the viewport) makes this mechanism unusable. There are two options which help in this case:
The second format expression on controller can be used to explicitly target the scope associated with the specified controller as the target scope for the injection. In this format expression is any angular assignable expression, and controller is the name of controller constructor function as specified in the ng-controller directive. The scroller will traverse its parents to locate the target scope associated with the specified controller.
Also Controller As syntax could be used as an alternative way to specify target controller in assignable expressions.
Data source is an object to be used by the uiScroll directive to access the data.
The directive will locate the object using the provided data source name. It will first look for a property with the given name on its $scope (here is the example of scope-based datasource usage). If none found it will try to get an angular service with the provided name (here is the example of service-based datasource usage).
The data source object implements methods and properties to be used by the directive to access the data.
Method get
get(descriptor, success)
or
get(index, count, success)
This is a mandatory method used by the directive to retrieve the data.
* **descriptor** is an object defining the portion of the dataset requested. The object will have 3 properties. Two of them named `index` and `count`. They have the same meaning as in the alternative signature when the parameters passed explicitly (see below). The third one will be named either `append` if the items will be appended to the last item in the buffer, or `prepend` if they are to be prepended to the first item in the buffer. The value of the property in either case will be the item the new items will be appended/prepended to. This is useful if it is easier to identify the items to be added based on the previously requested items rather than on the index. Keep in mind that in certain use cases (i.e. on initial load) the value of the append/prepend property can be undefined.
* **index** indicates the first data row requested
* **count** indicates number of data rows requested
* **success** function to call when the data are retrieved. The implementation of the data source has to call this function when the data are retrieved and pass it an array of the items retrieved. If no items are retrieved, an empty array has to be passed.
Important! Make sure to respect the index and count parameters of the request. The array passed to the success method should have
exactly count elements unless it hit eof/bof.
Properties minIndex and maxIndex
As the scroller receives the items requested by the get method, the value of minimum and maximum values of the item index are placed in the minIndex and maxIndex properties respectively. The values of the properties are cumulative - the value of the minIndex will never increase, and the value of the maxIndex will never decrease - except the values are reset in response to a call to the adapter reload method. The values of the properties are used to maintain the appearance of the scroller scrollBar.
Values of the properties can be assigned programmatically. If the range of the index values is known in advance, assigning them programmatically would improve the usability of the scrollBar.
###Adapter
The adapter object is an internal object created for every instance of the scroller. Properties and methods of the adapter can be used to manipulate and assess the scroller the adapter was created for. Adapter based API replaces old (undocumented) event based API introduced earlier for this purpose. The event based API is now deprecated and no longer supported.
Adapter object implements the following properties:
isLoading - a boolean value (read only) indicating whether there are any pending load requests.topVisible - a read only reference to the item currently in the topmost visible position.topVisibleElement - a read only reference to the DOM element currently in the topmost visible position.topVisibleScope - a read only reference to the scope created for the item currently in the topmost visible position.disabled - setting disabled to true disables scroller's scroll/resize events handlers. This can be useful if you have multiple scrollers within the same scrollViewport and you want to prevent some of them from responding to the events.Adapter object implements the following methods
Method isBOF
isBOF()
Returns true if the first item of the dataset is already in the buffer. No further requests for preceding items will be issued, returns false otherwise.
Method isEOF
isEOF()
Returns true if the last item of the dataset is already in the buffer. No further requests for tailing items will be issued, returns false otherwise.
Method isEmpty
isEmpty()
Returns true if the dataset is empty and the internal buffer length = 0. Returns false otherwise. Mind that isEmpty() will return true during the first request is pending, so maybe it should be used together with isLoading property.
Method reload
reload()
or
reload(startIndex)
Calling this method reinitializes and reloads the scroller content. startIndex is an integer indicating what item index the scroller will use to start the load process. The value of the argument replaces the value provided with the start-index attribute. Calling reload() is equivalent to calling reload method with current value of the start-index attribute.
Important! startIndex should fall within underlying datset boundaries. The scroller will request two batches of items one starting from the startIndex and another one preceding the first one (starting from startIndex - bufferSize). If both requests come back empty, the scroller will consider the dataset to be empty and will place no further data requests.
Method applyUpdates
applyUpdates(index, newItems)
Replaces the item in the buffer at the given index with the new items.
* **index** provides position of the item to be affected in the dataset (not in the buffer). If the item with the given index currently is not in the buffer no updates will be applied. `$index` property of the item $scope can be used to access the index value for a given item
* **newItems** is an array of items to replace the affected item. If the array is empty (`[]`) the item will be deleted, otherwise the items in the array replace the item. If the newItem array contains the old item, the old item stays in place.
applyUpdates(updater)
Updates scroller content as determined by the updater function
* **updater** is a function to be applied to every item currently in the buffer. The function will receive 3 parameters: `item`, `scope`, and `element`. Here `item` is the item to be affected, `scope` is the item $scope, and `element` is the html element for the item. The return value of the function should be an array of items. Similarly to the `newItem` parameter (see above), if the array is empty(`[]`), the item is deleted, otherwise the item is replaced by the items in the array. If the return value is not an array, the item remains unaffected, unless some updates were made to the item in the updater function. This can be thought of as in place update.
Method append
append(newItems)
Adds new items after the last item in the buffer.
* **newItems** provides an array of items to be appended.
Method prepend
prepend(newItems)
Adds new items before the first item in the buffer.
* **newItems** provides an array of items to be prepended.
Adapter methods applyUpdates, append and prepend provide a way to update the scroller content without full reload of the content from the datasource. The updates are performed by changing the items in the scroller internal buffer after they are loaded from the datasource. Items in the buffer can be deleted or replaced with one or more items.
Important! Update datasource to match the scroller buffer content. Keep in mind that the modifications made by the adapter methods are only applied to the content of the buffer. As the items in response to scrolling are pushed out of the buffer, the modifications are lost. It is your responsibility to ensure that as the scroller is scrolled back and a modified item is requested from the datasource again the values returned by the datasource would reflect the updated state. In other words you have to make sure that in addition to manipulating the scroller content you also apply the modifications to the dataset underlying the datasource. Here is the example of such implementation.
In the fashion similar to ngRepeat the following animations are supported:
Animations are only supported for the updates made via applyUpdates method. Updates caused by scrolling are not going through animation transitions. Usual rules of working with Angular animations apply. Look here for an example of animations in the scroller
The uiScrollViewport directive marks a particular element as viewport for the uiScroll directive. If no parent of the uiScroll directive is marked with uiScrollViewport directive, the browser window object will be used as viewport.
###Usage
<ANY ui-scroll-viewport>
...
</ANY>
This service implements some DOM element methods of jQuery which are currently not implemented in jqLite, namely
These methods are being registered on angular.element during 'ui.scroll' module run automatically only if jQuery is not loaded. It is so since ui-scroll v1.6.0. In previous versions there was a separate module 'ui.scroll.jqlite' which should have been included in the dependency list of the main app module. So currently we leave 'ui.scroll.jqlite' module stub with no content to provide full backward compatibility.
The uiScrollTh and uiScrollTd directives provide a way to build flexible dynamic grids. Handling of grid rows is done by the uiScroll directive itself. In addition to this uiScrollTh and uiScrollTd directive provide tools to programmatically change grid layout, including applying styles to columns, changing column size and order, as well as saving the modifications to the layout and applying previously saved layouts. At this point the above functionality is supported only for table based scrollable grids.
Here is the basic html template for scrollable grid using the uiScrollTh and uiScrollTd directives. Keep in mind that the height of the scroll viewport (in this case the <TABLE> tag) should be constrained. Also, make sure that the initial column widths are applied uniformly to both headers (<TH>) and cells (<TD>)
<TABLE ui-scroll-viewport class="grid">
<THEAD style="display:block">
<TR>
<TH ui-scroll-th class="col1">header 1...</TH>
<TH ui-scroll-th class="col2">header 2...</TH>
...
</TR>
</THEAD>
<TBODY>
<TR ui-scroll="item in datasource" adapter="adapter">
<TD ui-scroll-td class="col1">...</TD>
<TD ui-scroll-td class="col2">...</TD>
...
</TR>
</TBODY>
</TABLE>
The grid directives have the same dependency requirements as the uiScroll directive itself. To use the directives make sure the ui.scroll.grid module is on the list of the module dependencies. Also you have to load the dist/ui-scroll-grid.js file in your page.
GridAdapter object (along with ColumnAdapter objects) provides methods and properties to be used to change the scrollable grid layout.
A reference to this object is injected as a property named gridAdapterin the scroller adapter.
GridAdapter object implements the following properties:
columns - returns an array of ColumnAdapter objects to be used to control the scrollable grid layout. The columns are listed in the same order as they appear in the browser.GridAdapter object implements the following methods:
getLayout() - returns an object describing current scrollable grid layout.applyLayout(layout) - restores scrollabel grid layout to the state as defined by the object passed as the parametercolumnFromPoint(x,y) - if the coordinates belong to a scrollable grid column returns the appropriate ColumnAdapter object. Otherwise, returns undefined.ColumnAdapter object implements the following methods:
css(name, value) - sets the css property name to value for the column header as well as for the column cells.moveBefore(column) - moves the column in front of the column referenced by the parameter. If the parameter is null, the column will become the rightmost column.Please feel free to make Pull Requests. Below is the information which could be useful for local developing and contributing.
The ui-scroll sources are in ./src folder. They could not be run as is because of ES6 modules (since v1.6.0), they should be built. Build process includes jshint sources verification, webpack-based distributive files forming and tests running.
Three npm scripts are available for developing.
1. To run dev-server use
npm start
This should start development server on 5005 port over the ./demo folder. The middleware is configured to provide work with temporary distributive files (./temp) despite the direct links to public distributive files (./dist). So the dist-folder should stay clear until the development is finished. Dev-server watches for the source codes (./src) and automatically re-build temporary distributive files.
2. To run tests in keep-alive mode use
npm run test
This runs karma testing against temporary distributive files (./temp). We created a number of specifications which consist of more than 160 tests. They are living at ./test folder. Karma watches for temp and test folders changes and automatically re-run tests.
3. To run full build use
npm run build
After developing and testing complete the build process should be run to a) pass through jshint, b) generate minified versions of distributive, c) run tests with minified distributive files, d) obtain all necessary files in ./dist folder.
PR should include source code (./scr) and tests (./test) changes and may not include public distributive (./dist) changes.
###v1.6.0
###v1.5.2
###v1.5.1
###v1.5.0
###v1.4.1
###v1.4.0
###v1.3.3
###v1.3.2
###v1.3.1
###v1.3.0
####v1.2.1
####v1.2.0
####v1.1.2
####v1.1.1
####v1.1.0
FAQs
AngularJS virtual scrolling module
The npm package angular-ui-scroll receives a total of 1,200 weekly downloads. As such, angular-ui-scroll popularity was classified as popular.
We found that angular-ui-scroll demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket researchers have discovered multiple malicious npm packages targeting Solana private keys, abusing Gmail to exfiltrate the data and drain Solana wallets.
Security News
PEP 770 proposes adding SBOM support to Python packages to improve transparency and catch hidden non-Python dependencies that security tools often miss.
Security News
Socket CEO Feross Aboukhadijeh discusses open source security challenges, including zero-day attacks and supply chain risks, on the Cyber Security Council podcast.