# How-to Guides

This section provides practical, step-by-step guides for completing common tasks and implementing specific workflows using the library's components. Each guide is designed to be a self-contained set of instructions to help you achieve a specific outcome efficiently.

<x-cards data-columns="2">
  <x-card data-title="Add Custom Elements to the Header" data-icon="lucide:layout-template" data-href="#how-to-add-custom-elements-to-the-header">
    Learn how to use the `addons` render prop to extend the `Header` component with custom buttons, navigation, or other interactive elements.
  </x-card>
  <x-card data-title="Handle Optional Component Dependencies" data-icon="lucide:puzzle" data-href="#how-to-handle-optional-component-dependencies">
    Implement a workflow that prompts administrators to install required components on-demand, ensuring your blocklet's features run smoothly.
  </x-card>
  <x-card data-title="Implement Real-time User Notifications" data-icon="lucide:bell-ring" data-href="#how-to-implement-real-time-user-notifications">
    Set up a real-time notification system using WebSockets to keep users informed of important events within your application.
  </x-card>
  <x-card data-title="Publish Resources with BlockletStudio" data-icon="lucide:rocket" data-href="#how-to-publish-resources-with-blockletstudio">
    Integrate the `BlockletStudio` component to provide a user interface for publishing and managing resources and dependent components.
  </x-card>
</x-cards>

---

## How to Add Custom Elements to the Header

The `Header` component is designed to be extensible. You can add custom buttons, search bars, or other React components directly into the header by leveraging the `addons` prop.

### Goal

To add a custom "Chat" button, a search input, and additional action icons to the main application header.

### Prerequisites

- A functional React application with the `@arcblock/ux` library installed.
- An existing `<Header>` component instance. For more information, see the [Header component documentation](./components-layout-header.md).

### Steps

The `addons` prop accepts a render function. This function receives the default addons (like the session manager) as its first argument, allowing you to decide where to place your custom elements relative to the defaults.

1.  **Define the `addons` Render Prop**

    In your `Header` component, pass a function to the `addons` prop. This function should return the JSX you want to render.

    ```jsx
    <Header
      meta={meta}
      addons={(defaultAddons, { navigation }) => {
        // Your custom components will go here
        return (
          <>
            {/* Render your custom components */}
            {defaultAddons}
          </>
        );
      }}
    />
    ```

2.  **Add Custom Components**

    Inside the render function, you can add any components you need. In this example, we'll add a standard Material-UI `Button`, a few `AddonButton` components for icons, and a `Divider`.

3.  **Combine with Default Addons**

    It is standard practice to render the `defaultAddons` that are passed into the function. This ensures that essential elements like the locale switcher and session manager are still displayed. You can place your custom components before or after the `defaultAddons`.

### Complete Example

Here is a complete example demonstrating how to add several custom elements to the header. This includes navigation, buttons, and icons, rendered alongside the default session manager.

```javascript How to Add Custom Elements to the Header icon=logos:react
import { Box, Divider, Button } from '@mui/material';
import { SessionContext } from '@arcblock/did-connect-react/lib/Session';
import { AddonButton } from '@arcblock/ux/lib/Header/addon-button';
import NavMenu from '@arcblock/ux/lib/NavMenu';
import SessionManager from '@arcblock/ux/lib/SessionManager';
import Header from '@arcblock/ux/lib/Header';
import { Icon } from '@iconify/react';

// Mock data for demonstration purposes
const mockBlockletMeta = {
  title: 'My App',
  description: 'A great application',
  logoUrl: 'https://www.arcblock.io/image-bin/uploads/eb1cf5d60cd85c42362920c49e3768cb.svg'
};

const mockSessionContextValue = {
  session: {
    user: {
      fullName: 'Demo User',
      did: 'z1ex...',
      role: 'admin',
    },
    // ... other session properties
  },
};

export default function CustomHeaderGuide() {
  const meta = {
    ...mockBlockletMeta,
    enableConnect: true,
    enableLocale: true,
  };

  return (
    <SessionContext.Provider value={mockSessionContextValue}>
      <Header
        meta={meta}
        homeLink="https://www.arcblock.io"
        addons={(defaultAddons, { navigation }) => (
          <>
            {/* 1. Add custom navigation */}
            {navigation.navItems?.length > 0 && (
              <NavMenu
                activeId={navigation.activeId}
                items={navigation.navItems}
                className="header-nav"
              />
            )}
            {/* 2. Add a custom button */}
            <Button variant="contained" color="primary" size="small">
              Button
            </Button>
            {/* 3. Add custom icon buttons */}
            <AddonButton icon={<Icon icon="tabler:message-circle" />}>Chat</AddonButton>
            <AddonButton icon={<Icon icon="tabler:bell" />} />
            <Divider orientation="vertical" flexItem sx={{ height: 12, alignSelf: 'center' }} />
            {/* 4. Render the default addons (includes session manager) */}
            {defaultAddons}
          </>
        )}
      />
    </SessionContext.Provider>
  );
}
```

---

## How to Handle Optional Component Dependencies

Many blocklets rely on other components to provide specific features. The `ComponentInstaller` allows you to build features that depend on optional components, and if they are not installed, it provides a user-friendly way for an administrator to install them.

### Goal

To protect a feature that requires another blocklet component to be installed. If the component is missing, an administrator will be shown an interface to install it, while other users will see nothing.

### Prerequisites

- A feature in your application that depends on another component (e.g., a "Media Manager" that requires the "Media Kit" blocklet).
- The DID of the component dependency.
- Familiarity with user roles (`owner`, `admin`).

### Steps

1.  **Import `ComponentInstaller`**

    First, import the component from the library.

    ```javascript
    import ComponentInstaller from '@arcblock/ux/lib/ComponentInstaller';
    ```

2.  **Wrap Your Feature**

    Wrap the component or feature that has the dependency with the `ComponentInstaller`.

3.  **Provide the Component DID**

    Pass the DID of the required component to the `did` prop. This can be a single string or an array of strings if there are multiple dependencies.

4.  **Configure Behavior for Non-Admins**

    Use the `noPermissionMute` prop. When set to `true`, users who do not have permission to install components (i.e., non-admins) will not see the installation prompt. You can provide a `fallback` component to show them instead.

### Complete Example

In this scenario, we have a `MyFeatureButton` that should only be rendered if the component with DID `z8ia...` is installed.

```javascript How to Handle Optional Component Dependencies icon=logos:react
import ComponentInstaller from '@arcblock/ux/lib/ComponentInstaller';
import { Button } from '@mui/material';

const REQUIRED_COMPONENT_DID = 'z8ia1mAXo8ZE7ytGF36L5uBf9kD2kenhqFGp9'; // Example DID

// This is the component that requires the dependency
function MyFeatureButton() {
  return <Button variant="contained">Use Awesome Feature</Button>;
}

export default function OptionalComponentGuide() {
  return (
    <ComponentInstaller
      // The DID of the component to check for
      did={REQUIRED_COMPONENT_DID}
      // A list of roles that are allowed to see the installer UI
      roles={['owner', 'admin']}
      // If true, non-admins will not see the installer UI
      noPermissionMute
      // Optional: What to show non-admins if the component is not installed
      fallback={<div>This feature is not available.</div>}
      // A callback that fires after a successful installation
      onInstalled={() => console.log('Component was installed successfully!')}
    >
      {/* This child will only be rendered if the component is already installed */}
      <MyFeatureButton />
    </ComponentInstaller>
  );
}
```

When an admin visits this page and the component is not installed, they will see a pop-up allowing them to install it. A regular user will see the fallback message. Once installed, all users will see the `MyFeatureButton`.

---

## How to Implement Real-time User Notifications

You can provide users with real-time feedback and notifications by listening to WebSocket events from the Blocklet Server. The `NotificationAddon` component is a ready-to-use solution for displaying an unread notification count in the header.

### Goal

To add a notification bell icon to the application header that displays a badge with the count of unread notifications and updates in real-time.

### Prerequisites

- Your blocklet must be running on a Blocklet Server version that supports the notification service (`1.16.42` or higher).
- A `<Header>` component where the notification icon will be placed.
- A session context providing user information.

### Key Concepts

- **WebSocket Events**: The Blocklet Server broadcasts events when notifications are created or read.
- **`useListenWsClient`**: A hook to get a WebSocket client instance for a specific channel (e.g., 'user').
- **Event Naming**: Events are scoped to the user and blocklet. The format for new notifications is `${blocklet.did}/${user.did}/notification:blocklet:create`.

### Steps

The `NotificationAddon` component encapsulates all the required logic for listening to WebSocket events and displaying the unread count.

1.  **Import `NotificationAddon`**

    ```javascript
    import NotificationAddon from '@arcblock/ux/lib/common/notification-addon';
    ```

2.  **Add to Header `addons`**

    The simplest way to use this is to add it inside the `Header`'s `addons` render prop.

3.  **Pass the Session Object**

    The `NotificationAddon` component requires the `session` object to identify the current user and manage the unread count state.

### Complete Example

This example shows how to integrate the `NotificationAddon` into the `Header`. It will automatically connect to the WebSocket, listen for events, and update the badge count.

```javascript How to Implement Real-time User Notifications icon=logos:react
import { SessionContext } from '@arcblock/did-connect-react/lib/Session';
import Header from '@arcblock/ux/lib/Header';
import NotificationAddon from '@arcblock/ux/lib/common/notification-addon';

// Mock data for demonstration purposes
const mockBlockletMeta = {
  title: 'My App',
  description: 'A great application',
  logoUrl: 'https://www.arcblock.io/image-bin/uploads/eb1cf5d60cd85c42362920c49e3768cb.svg'
};

const mockSessionContextValue = {
  session: {
    user: {
      fullName: 'Demo User',
      did: 'z1ex...',
      role: 'admin',
    },
    unReadCount: 3, // Initial unread count
    setUnReadCount: () => {}, // State setter function
    // ... other session properties
  },
};

export default function NotificationGuide() {
  const meta = { ...mockBlockletMeta, enableConnect: true };

  return (
    <SessionContext.Provider value={mockSessionContextValue}>
      <Header
        meta={meta}
        addons={(defaultAddons) => (
          <>
            {/* The NotificationAddon will handle real-time updates */}
            <NotificationAddon session={mockSessionContextValue.session} />
            {defaultAddons}
          </>
        )}
      />
    </SessionContext.Provider>
  );
}
```

When a new notification for the logged-in user is created, the badge count on the bell icon will automatically increment. Clicking the icon will navigate the user to their notifications page.

---

## How to Publish Resources with BlockletStudio

The `BlockletStudio` component provides a complete, embeddable UI for publishing resources and components. It handles user connection, resource selection, and the release process, simplifying a complex workflow into a single component.

### Goal

To add a button that opens a dialog, allowing users to select and publish files and dependent components from the blocklet.

### Prerequisites

- An API endpoint in your blocklet that returns a list of available resources.
- The DID of the component that provides the publishing UI (the "studio" component).

### Steps

1.  **Import `BlockletStudio` and Manage State**

    You'll need to manage the visibility of the studio dialog using component state.

    ```javascript
    import { useState } from 'react';
    import { BlockletStudio } from '@arcblock/ux/lib/BlockletStudio';
    import { Button, CircularProgress } from '@mui/material';
    ```

2.  **Render the Component**

    Place the `<BlockletStudio />` component in your app and control its visibility with the `open` and `setOpen` props.

3.  **Configure Essential Props**

    - `componentDid`: The DID of the studio blocklet that provides the publishing service.
    - `title`, `description`: Metadata for the item being published.
    - `resourcesParams`: An object passed as query parameters to your resource-fetching API.
    - `components`: An array of components to be pre-selected or required.
    - `resources`: An object specifying which resources to pre-select.

4.  **Handle Lifecycle Events**

    Use the `onOpened`, `onUploaded`, and `onReleased` callbacks to respond to events in the publishing lifecycle, such as hiding a loading spinner or showing a success message.

### Complete Example

This example shows a button that, when clicked, opens the `BlockletStudio` dialog. It also demonstrates managing a loading state for a better user experience.

```javascript How to Publish Resources with BlockletStudio icon=logos:react
import { useState } from 'react';
import { Button, CircularProgress } from '@mui/material';
import { BlockletStudio } from '@arcblock/ux/lib/BlockletStudio';

// The DID of the blocklet that provides the studio/publishing UI
const AI_STUDIO_COMPONENT_DID = 'z8ia1mAXo8ZE7ytGF36L5uBf9kD2kenhqFGp9'; // Example DID

export default function PublisherGuide() {
  const [isStudioOpen, setStudioOpen] = useState(false);
  const [isOpening, setOpening] = useState(false);

  const handleShowDialog = () => {
    setOpening(true);
    setStudioOpen(true);
  };

  return (
    <>
      <Button
        variant="contained"
        onClick={handleShowDialog}
        disabled={isOpening}
        startIcon={isOpening ? <CircularProgress size={16} /> : null}>
        Publish to Studio
      </Button>

      <BlockletStudio
        // Controls the dialog's visibility
        open={isStudioOpen}
        setOpen={setStudioOpen}
        // Basic information for the published item
        title="My Demo Project"
        description="This is a project published from my blocklet."
        // The DID of the studio service component
        componentDid={AI_STUDIO_COMPONENT_DID}
        // Parameters sent to your blocklet's resource API
        resourcesParams={{ projectId: 'test-project-123' }}
        // Pre-selected components
        components={[
          { did: 'z8ia3xzq2tMq8CRHfaXj1BTYJyYnEcHbqP8cJ', included: true, required: true },
          { did: 'z2qZyjnsRffFtn2PDnDwDHTRbAu53RpKqDtFZ', included: true, required: false },
        ]}
        // Pre-selected resources
        resources={{
          // The key is the DID of the resource provider blocklet
          z8iZpog7mcgcgBZzTiXJCWESvmnRrQmnd3XBB: [
            'template-448698592710885376',
            'example-448698592710885376',
          ],
        }}
        // Event handlers
        onOpened={() => setOpening(false)}
        onUploaded={() => alert('Upload complete!')}
        onReleased={() => {
          alert('Successfully released!');
          setStudioOpen(false);
        }}
      />
    </>
  );
}
```