This is a plugin that only has a peer dependency to piral-core
. What piral-feeds
brings to the table is a set of Pilet API extensions that can be used with piral
or piral-core
.
By default, these API extensions are not integrated in piral
, so you'd need to add them to your Piral instance.
Documentation
The following functions are brought to the Pilet API.
createConnector
Creates a new feed connector, which is an abstraction over a state container driven by the typical lifecycle of a data feed connection.
Returns a higher-order component for providing a data
prop that reflects the current feed data.
Usage
For authors of pilets
You can use the createConnector
function from the Pilet API to create a global container managed data feed inside the Piral instance.
There are two kind of calls. The simple variant just uses a callback to populate the data via a lazy loading mechanism.
Example use:
import { PiletApi } from '<name-of-piral-instance>';
import { Page } from './Page';
export function setup(piral: PiletApi) {
const connect = createConnector(() => fetch('http://example.com').then(res => res.json()));
piral.registerPage('/sample', connect(Page));
}
The most powerful variant declares three different sections:
initialize
to declare how data should be loaded initially (e.g., by loading from some API)connect
to define how updates of the data should be retrieved (e.g., via a WebSocket connection)update
to handle the patching of data (e.g., combining the current data with the data retrieved from a WebSocket connection)
Example use:
import { PiletApi } from '<name-of-piral-instance>';
import { Page } from './Page';
export function setup(piral: PiletApi) {
const connect = createConnector({
initialize() {
return fetch('http://example.com').then(res => res.json());
},
connect(cb) {
const ws = new WebSocket();
ws.onmessage = e => cb(JSON.parse(e.data));
return () => ws.close();
},
update(data, item) {
return [...data, item];
},
});
piral.registerPage('/sample', connect(({ data }) => <Page items={data} />));
}
Calling createConnector
returns a higher-order component that injects a new prop called data
into the component.
Setup and Bootstrapping
For Piral instance developers
The provided library only brings API extensions for pilets to a Piral instance.
For the setup of the library itself you'll need to import createFeedsApi
from the piral-feeds
package.
import { createFeedsApi } from 'piral-feeds';
The integration looks like:
const instance = createInstance({
extendApi: [createFeedsApi()],
});
There are no options available.
License
Piral is released using the MIT license. For more information see the license file.