piral-dashboard
    TypeScript icon, indicating that this package has built-in type declarations

    0.14.7 • Public • Published

    Piral Logo

    Piral Dashboard · GitHub License npm version tested with jest Gitter Chat

    This is plugin that only has a peer dependency to piral-core. What piral-dashboard brings to the table is a set of Pilet API extensions that can be used with piral or piral-core.

    Why and When

    Many portal and tool applications come with a dashboard view that easily allows getting an overview over the most interesting pieces of functionality and information. This plugin allows creating dashboard pages that contain components registered as "tiles". The layout and behavior of these can be fully configured. The standard options include variable rows, columns, and resize properties.

    Alternatives: Use extensions to define this generically without the need for a plugin. Place each dashboard in its own extension slot registering components dynamically for these.

    Video

    We also have a video for this plugin:

    @youtube

    Documentation

    The following functions are brought to the Pilet API.

    registerTile()

    Adds the definition of a tile to the app shell. Optionally specifies display characteristics like the initial rows, initial columns, or if the tile can be resized by the user.

    If the first argument is a string a named tile is registered. A named tile can also be removed.

    unregisterTile()

    Removes a tile from the app shell. This requires a named tile.

    Usage

    ::: summary: For pilet authors

    You can use the registerTile function from the Pilet API to add a new tile in the app shell.

    Note: When the first argument is a string we call it a named tile.

    Example use:

    import { PiletApi } from '<name-of-piral-instance>';
    import { MyTile } from './MyTile';
    
    export function setup(piral: PiletApi) {
      piral.registerTile(MyTile);
    }

    You can use the unregisterTile function from the Pilet API to remove a previously added tile from the app shell.

    Note: You'll need to have added a named tile in order to be able to remove it.

    Example use:

    import { PiletApi } from '<name-of-piral-instance>';
    import { MyTile } from './MyTile';
    
    export function setup(piral: PiletApi) {
      // register with a name
      piral.registerTile('first', MyTile);
      // and unregister; maybe some time later?
      piral.unregisterTile('first');
    }

    :::

    ::: summary: 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 createDashboardApi from the piral-dashboard package.

    import { createDashboardApi } from 'piral-dashboard';

    The integration looks like:

    const instance = createInstance({
      // important part
      plugins: [createDashboardApi()],
      // ...
    });

    Via the options the defaultPreferences and the global / initially available tiles can be defined.

    Consider for example:

    const instance = createInstance({
      // important part
      plugins: [createDashboardApi({
        defaultPreferences: {
          initialColumns: 2,
          initialRows: 2,
          resizable: true,
        },
        tiles: [
          {
            component: MyTeaserTile,
            preferences: {
              initialColumns: 2,
              initialRows: 4,
            },
          },
        ],
      })],
      // ...
    });

    To fully integrate the dashboard the Dashboard component can be used. It can be part of a page or a page itself:

    <SetRoute path="/" component={Dashboard} />

    The Dashboard component also comes with a prop called filter, which might be handy together with custom options for actually using multiple dashboards.

    <SetRoute path="/dashboard1" component={props => <Dashboard {...props} filter={tile => tile.preferences.category === 'self'} />} />
    <SetRoute path="/dashboard2" component={props => <Dashboard {...props} filter={tile => tile.preferences.category === 'group'} />} />

    Customizing

    You can customize the available tiles and their options.

    import type {} from 'piral-dashboard';
    
    declare module 'piral-dashboard/lib/types' {
      interface PiralCustomTilePreferences {
        category?: string;
      }
    }
    
    // now registerTile(() => null, { category: 'general' }) is strongly typed in pilets

    :::

    License

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

    Install

    npm i piral-dashboard

    Homepage

    piral.io

    DownloadsWeekly Downloads

    1,186

    Version

    0.14.7

    License

    MIT

    Unpacked Size

    58.1 kB

    Total Files

    56

    Last publish

    Collaborators

    • florianrappl