docs/api/history.html
<!doctype html>
<html>
<head>
<meta charset='utf-8'>
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<meta name="viewport" content="width=device-width">
<title>Cycle.js - API reference (history)</title>
<!-- Flatdoc -->
<script src='../support/vendor/jquery.js'></script>
<script src='../support/vendor/highlight.pack.js'></script>
<script src='../legacy.js'></script>
<script src='../flatdoc.js'></script>
<!-- Algolia's DocSearch main theme -->
<link href='//cdn.jsdelivr.net/docsearch.js/2/docsearch.min.css' rel='stylesheet' />
<!-- Others -->
<script async src="//static.jsbin.com/js/embed.js"></script>
<!-- Flatdoc theme -->
<link href='../theme/style.css' rel='stylesheet'>
<script src='../theme/script.js'></script>
<link href='../support/vendor/highlight-github-gist.css' rel='stylesheet'>
<!-- Meta -->
<meta content="Cycle.js - API reference (history)" property="og:title">
<meta content="A functional and reactive JavaScript framework for predictable code" name="description">
<!-- Content -->
<script id="markdown" type="text/markdown" src="index.html">
# Cycle History - [source](https://github.com/cyclejs/cyclejs/tree/master/history)
This is the standard Cycle.js driver for dealing with the History API.
This project is 100% compatible with mjackson/history, most notably used to create React-Router. This allows for a Cycle.js application to be embedded inside of an existing React application and share history instances.
Though this library makes use of the interface that the mjackson/history library provides, any other library can be used which satisfies the interface. Also take note of the ServerHistory object we have made to easily allow for server-side rendering of your Cycle application.
```
npm install @cycle/history
```
# API
## <a id="makeHistoryDriver"></a> `makeHistoryDriver(options)`
Create a History Driver to be used in the browser.
This is a function which, when called, returns a History Driver for Cycle.js
apps. The driver is also a function, and it takes a stream of new locations
(strings representing pathnames or location objects) as input, and outputs
another stream of locations that were applied. Example:
```js
import {run} from '@cycle/run';
import {makeHistoryDriver} from '@cycle/history';
function main(sources){
return {
// updates the browser URL every 500ms
history: xs.periodic(500).map(i => `url-${i}`)
};
}
const drivers = {
history: makeHistoryDriver()
};
run(main, drivers);
```
#### Arguments:
- `options: object|History|MemoryHistory` an object with some options specific to this driver. These options are the same as for the corresponding
`createBrowserHistory()` function in History v4. Check its
[docs](https://github.com/mjackson/history/tree/v4.5.1#usage) for a good
description on the options. Alternatively, a History object can also be sent
in case the external consumer needs direct access to any of the direct History
methods
#### Returns:
*(Function)* the History Driver function
## <a id="makeHashHistoryDriver"></a> `makeHashHistoryDriver(options)`
Create a History Driver for older browsers using hash routing.
This is a function which, when called, returns a History Driver for Cycle.js
apps. The driver is also a function, and it takes a stream of new locations
(strings representing pathnames or location objects) as input, and outputs
another stream of locations that were applied.
#### Arguments:
- `options: object` an object with some options specific to this driver. These options are the same as for the corresponding
`createHashHistory()` function in History v4. Check its
[docs](https://github.com/mjackson/history/tree/v4.5.1#usage) for a good
description on the options.
#### Returns:
*(Function)* the History Driver function
## <a id="captureClicks"></a> `captureClicks(driver)`
Wraps a History Driver to add "click capturing" functionality.
If you want to intercept and handle any click event that leads to a link,
like on an `<a>` element, you pass your existing driver (e.g. created from
`makeHistoryDriver()`) as argument and this function will return another
driver of the same nature, but including click capturing logic. Example:
```js
import {captureClicks, makeHistoryDriver} from '@cycle/history';
const drivers = {
history: captureClicks(makeHistoryDriver())
};
```
#### Arguments:
- `driver: Function` an existing History Driver function.
#### Returns:
*(Function)* a History Driver function
## <a id="makeServerHistoryDriver"></a> `makeServerHistoryDriver(options)`
Create a History Driver to be used in non-browser enviroments such as
server-side Node.js.
This is a function which, when called, returns a History Driver for Cycle.js
apps. The driver is also a function, and it takes a stream of new locations
(strings representing pathnames or location objects) as input, and outputs
another stream of locations that were applied.
#### Arguments:
- `options: object` an object with some options specific to this driver. These options are the same as for the corresponding
`createMemoryHistory()` function in History v4. Check its
[docs](https://github.com/mjackson/history/tree/v4.5.1#usage) for a good
description on the options.
#### Returns:
*(Function)* the History Driver function
</script>
<!-- Initializer -->
<script>
Flatdoc.run({
fetcher: function (callback) {
callback(null, document.getElementById('markdown').innerHTML);
},
highlight: function (code, value) {
return hljs.highlight(value, code).value;
},
});
</script>
</head>
<body role='flatdoc' class="no-literate">
<div class='header'>
<div class='left'>
<h1><a href="/"><img class="logo" src="../img/cyclejs_logo.svg">Cycle.js</a></h1>
<ul>
<li><a href='../getting-started.html'>Guide</a></li>
<li><a href='../api/index.html'>API</a></li>
<li><a href='../releases.html'>Releases</a></li>
<li><a href='https://github.com/cyclejs/cyclejs'>GitHub</a></li>
</ul>
<input id="docsearch" />
</div>
<div class='right'>
<!-- GitHub buttons: see https://ghbtns.com -->
<iframe src="https://ghbtns.com/github-btn.html?user=cyclejs&repo=cyclejs&type=watch&count=true"
allowtransparency="true" frameborder="0" scrolling="0" width="110" height="20"></iframe>
</div>
</div>
<div class='content-root'>
<div class='menubar'>
<div class='menu section'>
<div role='flatdoc-menu'></div>
</div>
</div>
<div role='flatdoc-content' class='content'></div>
</div>
<script>
((window.gitter = {}).chat = {}).options = {
room: 'cyclejs/cyclejs'
};
</script>
<script src="https://sidecar.gitter.im/dist/sidecar.v1.js" async defer></script>
<script src='//cdn.jsdelivr.net/docsearch.js/2/docsearch.min.js'></script>
<script src='../docsearch.js'></script>
</body>
</html>