Merge pull request #809 from webcreate/3.1

3.1.0 Upwards scroll support

CHANGELOG.md

@@ -6,6 +6,25 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.1.0]
+
+This version introduces upwards scroll support (fixes [#466](https://github.com/webcreate/infinite-ajax-scroll/issues/466)). See [`upwards scroll`](docs/advanced/upwards.md) documentation on how to use this feature.
+
+* Adds all features from 3.1.0-beta.1
+* Added [`upwards`](docs/advanced/upwards.md) documentation
+
+## [3.1.0-beta.1]
+
+This version introduces upwards scroll support (fixes [#466](https://github.com/webcreate/infinite-ajax-scroll/issues/466)). See documentation on the [`prev`](docs/options.md#prev) option on how to enable this feature.
+
+* Added [`prev`](docs/options.md#prev) option
+* Added [`prev`](docs/events.md#prev) event
+* Added [`preved`](docs/events.md#preved) event
+* Added [`top`](docs/events.md#top) event
+* Added [`first`](docs/events.md#first) event
+* Added [`prepend`](docs/events.md#prepend) event
+* Added [`prepended`](docs/events.md#prepended) event
+
 ## [3.0.1]
 
 * Fixed prefill not filling past the scroll threshold
@@ -111,6 +130,8 @@ See [LICENSE](LICENSE) for more details.
 * Extensible through events
 * Added an extensive test suite
 
+[3.1.0]: https://github.com/webcreate/infinite-ajax-scroll/compare/3.0.1...3.1.0
+[3.1.0-beta.1]: https://github.com/webcreate/infinite-ajax-scroll/compare/3.0.1...3.1.0-beta.1
 [3.0.1]: https://github.com/webcreate/infinite-ajax-scroll/compare/3.0.0...3.0.1
 [3.0.0]: https://github.com/webcreate/infinite-ajax-scroll/compare/3.0.0-rc.1...3.0.0
 [3.0.0-rc.1]: https://github.com/webcreate/infinite-ajax-scroll/compare/v2.3.1...3.0.0-rc.1

Makefile

@@ -13,7 +13,7 @@ install:
 update:
 	npm ci
 	npm run build
-	$(foreach ex,$(EXAMPLES),(cd $(ex) && npm ci) || exit $$?;)
+	$(foreach ex,$(EXAMPLES),(cd $(ex) && npm install) || exit $$?;)
 .PHONY: update
 
 up:

README.md

@@ -49,7 +49,9 @@ Infinite Ajax Scroll works on a container with item elements which get appended.
 </div>
 
 <div class="pagination">
-    <a href="page2.html" class="next">Next</a>
+    <a href="page1.html" class="prev">Prev</a>
+    <span class="current">2</span>
+    <a href="page3.html" class="next">Next</a>
 </div>
 ```
 
@@ -62,6 +64,7 @@ import InfiniteAjaxScroll from '@webcreate/infinite-ajax-scroll';
 let ias = new InfiniteAjaxScroll('.container', {
   item: '.item',
   next: '.next',
+  prev: '.prev',
   pagination: '.pagination'
 });
 ```

UPGRADE.md

@@ -1,3 +1,8 @@
+Upgrade from 3.0.x to 3.1.0
+===========================
+
+Version 3.1.0 is backwards-compatible with 3.0.x.
+
 Upgrade from 2.3.x to 3.0
 =========================
 

docs/README.md

@@ -18,3 +18,4 @@
 * [Last page message](advanced/last-page-message.md)
 * [History](advanced/history.md)
 * [Overflow](advanced/overflow.md)
+* [Upward scroll](advanced/upwards.md)

docs/advanced/history.md

@@ -23,6 +23,7 @@ ias.on('page', (event) => {
 
 ## Loading previous pages
 
-{% hint style='working' %}
-This feature is still work in progress
-{% endhint %}
+Infinite Ajax Scroll can also be used to load items above the current scroll position. This is useful when you want to load older items first.
+
+[View upwards infinite scroll documentation](upwards.md)
+

docs/advanced/upwards.md

@@ -0,0 +1,61 @@
+# Upward Infinite Scroll
+
+Infinite Ajax Scroll can also be used to load items above the current scroll position. This is useful when you want to load older items first.
+
+*Introduced in Infinite Ajax Scroll 3.1.0*
+
+## Caveats
+
+### Fixed height images
+
+Upward scroll works by calculation screen height and content height. Due to they way browser load content, especially images, this could cause incorrect measurements. This can be solved by using fixed height images.
+
+## Setup
+
+1. Add a previous page link to your pagination.
+
+    ```html
+     <div class="pagination">
+        <a href="page1.html" class="prev">Prev</a>
+        <span class="current">2</span>
+        <a href="page3.html" class="next">Next</a>
+    </div>
+    ```
+
+2. Configure the [`prev`](../options.md#prev) option.
+
+    ```javascript
+    // import if you use the NPM package
+    import InfiniteAjaxScroll from '@webcreate/infinite-ajax-scroll';
+
+    let ias = new InfiniteAjaxScroll('.container', {
+      item: '.item',
+      next: '.next',
+      prev: '.prev',
+      pagination: '.pagination'
+    });
+    ```
+
+## Hook into upward scroll with events
+
+In this example we notify the user about loading the previous page.
+
+```js
+ias.on('prev', function(event) {
+  // pageIndex is 0-indexed, so we add 1
+  alert(`Page ${event.pageIndex+1} is loading...`);
+});
+ias.on('preved', function(event) {
+    alert(`Page ${event.pageIndex+1} is loaded and prepended to the page.`);
+});
+```
+
+## Inform user about first page reached
+
+In this example we notify the user when the first page is reached.
+
+```javascript
+ias.on('first', () => {
+  console.log('User has reached the first page');
+})
+```

docs/events.md

@@ -63,6 +63,16 @@ Triggered when the user has hit the scroll threshold for the next page due to sc
 | :--- | :--- | :--- |
 | distance | int | The distance to the scroll threshold in pixels |
 
+### top
+
+*Introduced in Infinite Ajax Scroll 3.1.0*
+
+Triggered when the user has hit the top of the scroll area for the previous page due to scrolling or resizing.
+
+| property | type | description                            |
+| :--- | :--- |:---------------------------------------|
+| distance | int | The distance to the scroll top in pixels |
+
 ### next
 
 Triggered right after the `hit` event. Indicating that the next page will be loaded.
@@ -93,6 +103,40 @@ Trigger when loading and appending the next page is completed.
 | :--- | :--- | :--- |
 | pageIndex | int | The page index of the next page (the page that is finished loading) |
 
+### prev
+
+*Introduced in Infinite Ajax Scroll 3.1.0*
+
+Triggered right after the `top` event. Indicating that the previous page will be loaded.
+
+| property | type | description                                                           |
+| :--- | :--- |:----------------------------------------------------------------------|
+| pageIndex | int | The page index of the prev page (the page that is about to be loaded) |
+
+> pageIndex is zero indexed. This means the index starts at 0 on the first page.
+
+For example to notify the user about loading the previous page, you can do:
+
+```js
+ias.on('prev', function(event) {
+  // pageIndex is 0-indexed, so we add 1
+  alert(`Page ${event.pageIndex+1} is loading...`);
+});
+ias.on('preved', function(event) {
+    alert(`Page ${event.pageIndex+1} is loaded and prepended to the page.`);
+});
+```
+
+### preved
+
+*Introduced in Infinite Ajax Scroll 3.1.0*
+
+Trigger when loading and prepending the previous page is completed.
+
+| property | type | description |
+| :--- | :--- | :--- |
+| pageIndex | int | The page index of the next page (the page that is finished loading) |
+
 ### load
 
 This event is triggered before the next page is requested from the server.
@@ -158,18 +202,55 @@ This event is triggered after the items have been appended.
 | items | array | Array of items that have been appended |
 | parent | Element | The element to which the items have been appended |
 
+### prepend
+
+*Introduced in Infinite Ajax Scroll 3.1.0*
+
+This event is triggered before the items are about to be prepended.
+
+| property | type | description                                      |
+| :--- | :--- |:-------------------------------------------------|
+| items | array | Array of items that will be prepended            |
+| parent | Element | The element to which the items will be prepended |
+| prependFn | function | Function used to prepend items to the container  |
+
+See [src/prepend.js](../src/prepend.js) for the default prepend function.
+
+### prepended
+
+*Introduced in Infinite Ajax Scroll 3.1.0*
+
+This event is triggered after the items have been prepended.
+
+| property | type | description                                        |
+| :--- | :--- |:---------------------------------------------------|
+| items | array | Array of items that have been prepended            |
+| parent | Element | The element to which the items have been prepended |
+
 ### last
 
 Triggered when the last page is appended.
 
 ```javascript
 ias.on('last', () => {
-  console.log('Users has reached the last page');
+  console.log('User has reached the last page');
 })
 ```
 
 [Read more on how we can inform the user about reaching the last page](advanced/last-page-message.md)
 
+### first
+
+*Introduced in Infinite Ajax Scroll 3.1.0*
+
+Triggered when the last page is appended.
+
+```javascript
+ias.on('first', () => {
+  console.log('User has reached the first page');
+})
+```
+
 ### page
 
 Triggered when the user scrolls past a page break. The event provides information about the page in view.

docs/options.md

@@ -44,6 +44,29 @@ let ias = new InfiniteAjaxScroll(/*..*/, {
 })
 ```
 
+## prev
+
+*Introduced in Infinite Ajax Scroll 3.1.0*
+
+**Type:** `string`<br>
+**Default:** `undefined`<br>
+**Required:** no
+
+Selector of the previous link. The `href` attribute will be used for the url of the previous page. Only a single element should match this selector.
+
+```html
+<a href="/page/1" class="pager__prev">Prev</a>
+<span class="pager__current">2</span>
+<a href="/page/3" class="pager__next">Next</a>
+```
+
+```javascript
+let ias = new InfiniteAjaxScroll(/*..*/, {
+  next: '.pager__next',
+  prev: '.pager__prev'
+})
+```
+
 ## pagination
 
 **Type:** `boolean|string|Element`<br>

examples/articles/index.js

@@ -3,6 +3,7 @@ import InfiniteAjaxScroll from '@webcreate/infinite-ajax-scroll';
 window.ias = new InfiniteAjaxScroll('.surface-container', {
   item: '.article',
   next: '.pager__next',
+  prev: '.pager__prev',
   pagination: '.pager',
   spinner: '.loader'
 });
@@ -21,3 +22,8 @@ ias.on('page', (e) => {
 
   history.replaceState(state, e.title, e.url);
 });
+
+// disable cache busting
+ias.on('load', function(event) {
+  event.nocache = true;
+});

examples/articles/package.json

@@ -29,7 +29,7 @@
     "jquery-ias"
   ],
   "dependencies": {
-    "@webcreate/infinite-ajax-scroll": "^3.0.0"
+    "@webcreate/infinite-ajax-scroll": "^3.1.0"
   },
   "devDependencies": {
     "parcel": "^2.0.0"

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webcreate/infinite-ajax-scroll",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "title": "Infinite Ajax Scroll",
   "description": "Turn your existing pagination into infinite scrolling pages with ease",
   "license": "AGPL-3.0-only",

src/defaults.js

@@ -1,6 +1,7 @@
 export default {
   item: undefined,
   next: undefined,
+  prev: undefined,
   pagination: undefined,
   responseType: 'document',
   bind: true,

src/events.js

@@ -1,14 +1,20 @@
 export const APPEND = 'append';
 export const APPENDED = 'appended';
+export const PREPEND = 'prepend';
+export const PREPENDED = 'prepended';
 export const BINDED = 'binded';
 export const UNBINDED = 'unbinded';
 export const HIT = 'hit';
+export const TOP = 'top';
 export const LOAD = 'load';
 export const LOADED = 'loaded';
 export const ERROR = 'error';
+export const FIRST = 'first';
 export const LAST = 'last';
 export const NEXT = 'next';
 export const NEXTED = 'nexted';
+export const PREV = 'prev';
+export const PREVED = 'preved';
 export const READY = 'ready';
 export const SCROLLED = 'scrolled';
 export const RESIZED = 'resized';
@@ -19,15 +25,21 @@ export const PREFILLED = 'prefilled';
 const events = {
   APPEND,
   APPENDED,
+  PREPEND,
+  PREPENDED,
   BINDED,
   UNBINDED,
   HIT,
+  TOP,
   LOAD,
   LOADED,
   ERROR,
+  FIRST,
   LAST,
   NEXT,
   NEXTED,
+  PREV,
+  PREVED,
   READY,
   SCROLLED,
   RESIZED,