Dashboard

The Dashboard component provides a pre-built, responsive layout for blocklet applications, typically used for administrative interfaces or user-centric views. It automatically constructs a standard dashboard with a sidebar, header, and main content area by interpreting your blocklet's metadata. This component significantly reduces boilerplate code for building common application structures.

The layout is composed of three primary sections: a persistent sidebar for navigation, a header for global actions and user information, and a main content area where the page-specific content is rendered.

Basic Usage#

To use the Dashboard component, simply wrap your page's content with it. The component will automatically render the header and sidebar around your content.

import Dashboard from '@arcblock/blocklet-ui-react/lib/Dashboard';

export default function MyDashboardPage() {
  return (
    <Dashboard>
      <h1>Welcome to the Dashboard</h1>
      <p>This is your main content area.</p>
    </Dashboard>
  );
}

The children passed to the Dashboard component will be displayed in the main content area.

Props#

The Dashboard component accepts the following props to customize its behavior and appearance.

How It Works#

The Dashboard component is designed to be "configuration-driven," deriving its structure and content primarily from the blocklet's metadata file (blocklet.yml).

Navigation from Metadata#

The sidebar navigation is automatically generated from the navigation array in your blocklet.yml. The component specifically looks for navigation items that include dashboard in their section property.

Here is an example of how to define dashboard navigation:

navigation:
  - title: 'Home'
    link: '/'
    section: 'dashboard'
    icon: 'mdi:home'
    role: ['owner', 'admin', 'guest']
  - title: 'Analytics'
    link: '/analytics'
    section: 'dashboard'
    icon: 'mdi:chart-bar'
    role: ['owner', 'admin']
  - title: 'Settings'
    link: '/settings'
    section: 'dashboard'
    icon: 'mdi:cog'
    role: ['owner']
    items:
      - title: 'Profile'
        link: '/settings/profile'
      - title: 'Billing'
        link: '/settings/billing'

Role-Based Access Control#

The Dashboard component enforces role-based access control (RBAC) on navigation links. Each navigation item can have a role property, which is an array of roles that are permitted to see the link.

• If a navigation item does not have a role property, it is visible to everyone.
• If the current user is not authenticated, they can only see items that include the guest role.
• If the current user is authenticated, the component compares their user.role with the role array of each navigation item. The item is only displayed if there is a match.
• A parent navigation item is only visible if at least one of its children is visible.

Using the blocklet.yml example above:

• A user with the guest role will only see the "Home" link.
• A user with the admin role will see "Home" and "Analytics".
• A user with the owner role will see all links, including the nested "Profile" and "Billing" links under "Settings".

Icons#

The icon property for a navigation item should be a string that corresponds to an icon name from the Iconify library (e.g., mdi:home). You can also provide a full URL to an image file.

Customization#

While the Dashboard is designed to work out-of-the-box with metadata, it offers several props for more advanced customization.

Customizing Header Addons#

You can modify the default header addons (e.g., Theme Toggle, Locale Selector, Session Manager) using the headerAddons prop. By passing a function, you can add new elements or rearrange the existing ones.

import Dashboard from '@arcblock/blocklet-ui-react/lib/Dashboard';
import Button from '@mui/material/Button';

function MyCustomButton() {
  return <Button color="inherit" onClick={() => alert('Help!')}>Help</Button>;
}

export default function CustomDashboard() {
  return (
    <Dashboard
      headerAddons={(existingAddons) => {
        const customAddon = <MyCustomButton key="custom-help" />;
        // Add the custom button before the other addons
        return [customAddon, ...existingAddons];
      }}
    >
      <p>Dashboard with a custom header button.</p>
    </Dashboard>
  );
}

Programmatically Adding Links#

The links prop allows you to add or modify sidebar navigation links dynamically from your code. This is useful for links that depend on application state.

import Dashboard from '@arcblock/blocklet-ui-react/lib/Dashboard';
import Icon from '@arcblock/ux/lib/Icon';

const useFeatureFlag = () => {
  // In a real app, this would check a feature flag service
  return true;
};

export default function DynamicDashboard() {
  const isBetaFeatureEnabled = useFeatureFlag();

  return (
    <Dashboard
      links={(existingLinks) => {
        if (isBetaFeatureEnabled) {
          const betaLink = {
            id: 'beta-feature',
            title: 'Beta Feature',
            url: '/beta',
            icon: <Icon name="mdi:test-tube" />,
            external: true, // Required for client-side routing
          };
          return [...existingLinks, betaLink];
        }
        return existingLinks;

Summary#

The Dashboard component is a powerful tool for quickly scaffolding application layouts. By leveraging blocklet metadata, it provides a structured, role-aware navigation system out of the box. For more foundational layout components, see the documentation for Header and Footer.