piral-feeds

Piral Feeds ·

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:

1. initialize to declare how data should be loaded initially (e.g., by loading from some API)
2. connect to define how updates of the data should be retrieved (e.g., via a WebSocket connection)
3. 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({
  // important part
  extendApi: [createFeedsApi()],
  // ...
});

There are no options available.

License

Piral is released using the MIT license. For more information see the license file.

Changelog

0.10.0 (February 2, 2020)

• Introduce compatibility check for the Piral CLI (#94)
• Added new optional plugin piral-mithril for Mithril.js (#79)
• Added new optional plugin piral-aurelia for Aurelia (#80)
• Added new optional plugin piral-litel for LitElement (#85)
• Added new optional plugin piral-ember for Ember.js (#96)
• Added new optional plugin piral-svelte for Svelte (#97)
• Added new optional plugin piral-elm for Elm (#118)
• Added new optional plugin piral-riot for Riot.js
• Added new optional plugin piral-react-15 for React v15
• Added new optional plugin piral-lazy for generic lazy loading
• Replaced react-arbiter with piral-base (#109)
• Changed --skip-install (default: false) flag to --install (default: true) for scaffolding
• Changed --only-core to --framework (supporting piral-base)
• Changed --tag to be a positional argument (for pilet upgrade)
• Allow async setup in pilets
• Support for teardown function in pilets
• Added dispatch and readState actions
• Allow async pilet module evaluation
• Integrated state and router in foreign context
• Introduced additional checks for missing files (#129)
• Changed generation of the Piral instance declaration (#116)