Managing Folder Previews

DID Space allows you to set a custom preview for any folder. This feature enables you to define how a folder is presented in applications, turning a simple file listing into a rich, interactive experience like a gallery, a document preview, or even a mini-application. This is managed by a special preview.yml file inside the folder's .meta directory.

This guide will walk you through the three primary operations for managing folder previews using the SDK:

Setting a Preview: Create or update a folder's preview configuration and upload its associated assets (e.g., index.html, CSS, JavaScript files) in a single operation.
Retrieving a Preview: Fetch the preview configuration for a specific folder.
Deleting a Preview: Remove the custom preview from a folder.

Setting a Folder Preview

To set or update a folder's preview, you use the PutPreviewObjectCommand. This powerful command not only writes the preview.yml configuration but also uploads all the necessary resource files (like HTML, CSS, and JS) that the preview will use.

Input Parameters

key string (required) — The path to the folder. It must end with a trailing slash (/).
data PreviewTemplate (required) — An object containing the preview configuration. This will be converted to YAML and stored in .meta/preview.yml.
name string (required) — The name of the preview.
description string — A short description of the preview.
entry string (required) — The entry file for the preview, typically an index.html file.
resources PutObjectCommandInput[] (default: []) — An array of file objects to upload as part of the preview. Each resource key must be prefixed with the folder's key.
metadata object (default: {}) — A record of custom metadata to associate with the preview.
hash string — The IPFS CID v1 hash of the object, used for data integrity verification.

Example

The following example demonstrates how to create a simple HTML preview for a folder named my-gallery/. We will upload an index.html and a style.css file along with the preview configuration.

Set a Folder Preview

import { SpaceClient, PutPreviewObjectCommand } from '@blocklet/did-space-js';
import getWallet from '@blocklet/sdk/lib/wallet';

async function setFolderPreview() {
  const wallet = getWallet();
  const client = new SpaceClient({
    endpoint: 'https://www.didspaces.com/app/api/space/...',
    wallet,
  });

  const folderKey = 'my-gallery/';

  const input = {
    key: folderKey,
    // This 'data' object will become the content of '.meta/preview.yml'
    data: {
      name: 'My Image Gallery',
      description: 'A simple preview for my image collection.',
      entry: 'index.html', // The entry point for the preview
    },
    // Upload the preview assets in the same command
    resources: [
      {
        key: `${folderKey}index.html`,
        body: Buffer.from(
          '<!DOCTYPE html><html><head><link rel="stylesheet" href="style.css"></head><body><h1>Welcome to My Gallery</h1></body></html>'
        ),
        contentType: 'text/html',
      },
      {
        key: `${folderKey}style.css`,
        body: Buffer.from('body { background-color: #f0f0f0; color: #333; }'),
        contentType: 'text/css',
      },
    ],
  };

  const command = new PutPreviewObjectCommand(input);
  const output = await client.send(command);

  if (output.statusCode === 200) {
    console.log('Successfully set folder preview!');
  } else {
    console.error('Failed to set folder preview:', output.statusMessage);
  }
}

setFolderPreview();

After this command executes, the my-gallery/ folder will have a .meta/preview.yml file and will contain index.html and style.css.

Retrieving a Folder Preview

To get the configuration of an existing folder preview, use the GetPreviewObjectCommand. This command reads the .meta/preview.yml file and returns its parsed content.

Input Parameters

key string (required) — The path to the folder. It must end with a trailing slash (/).

Output

The command's output contains the parsed PreviewTemplate object in the data property.

data PreviewTemplate — The parsed content of the .meta/preview.yml file.

Example

Get a Folder Preview

import { SpaceClient, GetPreviewObjectCommand } from '@blocklet/did-space-js';
import getWallet from '@blocklet/sdk/lib/wallet';

async function getFolderPreview() {
  const wallet = getWallet();
  const client = new SpaceClient({
    endpoint: 'https://www.didspaces.com/app/api/space/...',
    wallet,
  });

  const command = new GetPreviewObjectCommand({ key: 'my-gallery/' });
  const output = await client.send(command);

  if (output.statusCode === 200) {
    console.log('Preview configuration:', output.data);
  } else {
    console.error('Failed to get folder preview:', output.statusMessage);
  }
}

getFolderPreview();

Example Response

If the command is successful, the output.data would look like this:

Example Response

{
  "name": "My Image Gallery",
  "description": "A simple preview for my image collection.",
  "entry": "index.html"
}

Deleting a Folder Preview

If you want to remove a custom preview and revert a folder to its default appearance, use the DeletePreviewObjectCommand. This command deletes the .meta/preview.yml file but does not affect any other files in the folder, including the resource files you may have uploaded.

Input Parameters

key string (required) — The path to the folder. It must end with a trailing slash (/).

Example

Delete a Folder Preview

import { SpaceClient, DeletePreviewObjectCommand } from '@blocklet/did-space-js';
import getWallet from '@blocklet/sdk/lib/wallet';

async function deleteFolderPreview() {
  const wallet = getWallet();
  const client = new SpaceClient({
    endpoint: 'https://www.didspaces.com/app/api/space/...',
    wallet,
  });

  const command = new DeletePreviewObjectCommand({ key: 'my-gallery/' });
  const output = await client.send(command);

  if (output.statusCode === 200) {
    console.log('Successfully deleted folder preview!');
  } else {
    console.error('Failed to delete folder preview:', output.statusMessage);
  }
}

deleteFolderPreview();

By using these three commands, you can fully manage custom folder previews to create richer and more engaging user experiences in your DID Space-powered applications.