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#

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.

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(

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#

Output#

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

Example#

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:

{
  "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#

Example#

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.