pastpresentfuture
v0.1.6
Published
Where have we been? Where are we going?
Downloads
23
Keywords
Readme
PastPresentFuture
A JavaScipt library for manipulating browser history with pushState and AJAX.
Introduction
PastPresentFuture is a JavaScript library for interacting with history.pushState() while loading internal URLs with AJAX. The goal is to maintain a single load of CSS and JS assets per user session, speeding up page changes for time-on-site retention with increased page views. Below you will find documentation on its configuration and usage.
Installation
Bower
Use the Bower package manager to install PastPresentFuture into your project. To do so you can either use the CLI:
$ bower install pastpresentfuture --saveOr define it in your bower.json manifest:
"dependencies": {
"pastpresentfuture": "latest"
}npm
Similarly, PastPresentFuture can be installed using npm. To do so you can either use the CLI:
$ npm install pastpresentfuture --saveOr define it in your package.json manifest:
"dependencies": {
"pastpresentfuture": "latest"
}Direct download
If package managers are not your thing, the library can be downloaded directly from GitHub using the Download ZIP button.
Basic Usage
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>PastPresentFuture Usage</title>
<script src="jquery.js"></script>
<script src="PastPresentFuture.min.js"></script>
</head>
<body>
<!--
This is the main container with content that can be changed.
-->
<div class="page_content_holder"></div>
<script type="text/javascript">
( function () {
PastPresentFuture();
} () );
</script>
</body>
</html>Configuration
| key | type |
| -------------------------------------------- | -------- |
| content | String |
| ajaxContainer | String |
| prefetchCacheLimit | Integer |
| ajaxCacheLimit | Integer |
| onParseHtml | Function |
Example Configuration:
{
content: '.page_content_holder',
ajaxContainer: '.page_content_holder',
prefetchCacheLimit: 15,
ajaxCacheLimit: 15
}content
Type: String
Default: '.page_content_holder'
Description: The wrapper that contains the dynamic aspects of the page to be replaced.
ajaxContainer
Type: String
Default: '.page_content_holder'
Description: The wrapper that new content will be applied. This defaults the current container, but can be used for a new container if an animation affect is desired.
prefetchCacheLimit
Type: Integer
Default: 15
Description: This declares the number of pages that are stored in the prefetch cache. The prefetch cache is set by a flag on the next article it increase the load of that page.
ajaxCacheLimit
Type: Integer
Default: 15
Description: This declares the limit of the cache on pages that have already been visited that are not already in the prefetch cache.
onParseHtml
Type: Function
Default: None.
Description: Callback to filter the HTML before insertion into the DOM. Must return the HTML collection.
Events
Custom jQuery events prefixed with PastPresentFuture.
| event | trigger source |
| ---------------------------------------------------------------------------- | --------------- |
| PastPresentFuture:AfterInitState | internal |
| PastPresentFuture:PushState | internal |
| PastPresentFuture:NewState | internal |
| PastPresentFuture:PopState | internal |
| PastPresentFuture:LoadingReveal | internal |
| PastPresentFuture:LoadingComplete | internal |
| PastPresentFuture:GotoUrl | both |
| PastPresentFuture:RecordPageview | internal |
| PastPresentFuture:RenderUrl | internal |
| PastPresentFuture:FetchedData | internal |
| PastPresentFuture:BeforeTransition | internal |
| PastPresentFuture:AnimateTransition | internal |
| PastPresentFuture:ResetPage | internal |
PastPresentFuture:AfterInitState
Description: Called on initial load and after pushState.
PastPresentFuture:PushState
Description: An event wrapper for history.pushState(). It is called before render of AJAX data.
Parameter: options {Object}
| name | type | description |
| ---------- | ------- | --------------------------------------------- |
| url | String | The url to push into the brower’s history. |
| popstate | Boolean | Whether this is a popstate event. Optional. |
| title | String | The page title for the new url. Optional. |
PastPresentFuture:NewState
Description: Called after pushState.
PastPresentFuture:PopState
Description: This event is called when the history is changed by browser forward and back buttons.
PastPresentFuture:LoadingReveal
Description: Called while data from the new page is being loaded into memory.
PastPresentFuture:LoadingComplete
Description: Called just before data is rendered to the DOM.
PastPresentFuture:GotoUrl
Description: A trigger to be used for loading a new page. Accepts the URL and Options for pushState.
Parameters:
url {String} The url of the page to go to.
options {Object}
| name | type | description |
| ---------- | ------- | ------------------------------------------- |
| url | String | The url of the page to go to. |
| popstate | Boolean | Optional, set to false by default. |
| options | Object | Optional, specifically used for pushState. |
PastPresentFuture:RecordPageview
Description: Called on init state, passes the current URL and page title.
PastPresentFuture:RenderUrl
Description: This event is called after a page is fetch for processing the data.
PastPresentFuture:FetchedData
Description: Event for passing data if a page has already been cached.
PastPresentFuture:BeforeTransition
Description: This event is called when the content and ajaxContainer set in the Config aren’t the same.
Parameter: containers {Object}
| name | type | description |
| --------------- | ----- | --------------------------------------------------- |
| contentHolder | Array | jQuery selection for the content element. |
| ajaxContainer | Array | jQuery selection for the ajax container element. |
PastPresentFuture:AnimateTransition
Description: This event is called when the content and ajaxContainer set in the Config aren’t the same. It's called after LoadingComplete is triggered.
PastPresentFuture:ResetPage
Description: This event is fired when the library tries to reload the page it is already on. This is particularly useful if the current page has javascript elements that need to be reset.
Contributing
Coding Style
PastPresentFuture follows the WordPress JavaScript Coding Standards. There is a .jscsrc included in the project for automatic linting using JSCS.
The modules are written in the UMD pattern to support AMD, CommonJS, and global usage.
Development
The project contains a gulpfile.js for concatenation and minification. To use first install gulp and the dependencies (npm install). The default gulp task (gulp) will start the watch task.
Dependencies
PastPresentFuture requires jQuery.