Put Preview
This section details how to create or update rich previews for your objects in DID Spaces. The PutPreviewObjectCommand allows you to upload preview template data, along with associated resources, to a specified folder within your DID Space. This is crucial for enabling rich display experiences for your content.
For more information on managing preview metadata, refer to the Preview Commands overview. You can also Get Preview or Delete Preview objects.
PutPreviewObjectCommand#
The PutPreviewObjectCommand facilitates the creation or update of preview metadata for a given object or collection of objects. The preview data is stored as a .meta/preview.yml file within the specified directory, and any linked resources (like images) are uploaded as standard objects.
Parameters#
Name | Type | Description | Default Value |
|---|---|---|---|
|
| The path to the folder where the preview metadata will be stored. This path must end with a | |
|
| The structured data for the preview template. This defines the title, description, image, and other relevant information for the preview. | |
|
| Optional. Custom metadata to associate with the preview object. |
|
|
| Optional. The IPFS CID v1 hash of the object, if available, for integrity verification. | |
|
| Optional. A list of resources (e.g., images, linked files) that are part of the preview. Each resource must conform to the |
|
Returns#
Name | Type | Description |
|---|---|---|
|
| The HTTP status code of the operation. |
|
| The HTTP status message of the operation. |
|
| This command does not return any specific data in the response body. |
Return Value Example
{
"statusCode": 200,
"statusMessage": "OK",
"data": null
}Example#
The following example demonstrates how to upload a preview for a document located at my-documents/report/. The preview includes a title, description, and a reference to an image resource that is also uploaded as part of the command.
import { SpaceClient } from '@did-space/client';
import { PutPreviewObjectCommand } from '@did-space/client/commands/preview';
import { PutObjectCommand } from '@did-space/client/commands/object';
async function putDocumentPreview(client, wallet) {
const folderKey = 'my-documents/report/';
const previewData = {
title: 'Quarterly Report Q1 2024',
description: 'A comprehensive overview of our performance in the first quarter.',
image: `${folderKey}report-cover.png`, // Path relative to the preview folder key
type: 'document',
url: `did:space:your_space_did/${folderKey}`
};
const imageResourceData = Buffer.from('...'); // Replace with actual image buffer
const imageHash = 'bafybeibabafyibabafybeibabafybeibabafybeibabafybeibabafybeibabafybeibabafybeibabafybeibab'; // Replace with actual image hash
try {
const command = new PutPreviewObjectCommand(
{
key: folderKey,
data: previewData,
metadata: { category: 'financial' },
hash: 'bafybeibabafybeibabafybeibabafybeibabafybeibabafybeibabafybeibabafybeibabafybeibabafybeibab',
resources: [
new PutObjectCommand({
key: `${folderKey}report-cover.png`,
data: imageResourceData,
hash: imageHash,
// metadata for the image itself if needed
}).input, // We need the input data for the resources array
],
},
{ wallet, endpoint: 'https://beta.did.space' } // Your DID Space endpoint
);
const result = await client.send(command);
console.log('Preview object put successfully:', result.statusCode, result.statusMessage);
return result;
} catch (error) {
console.error('Error putting preview object:', error);
throw error;
}
}
// Example usage (assuming 'client' and 'wallet' are initialized)
// const client = new SpaceClient();
// const wallet = new Wallet(...);
// putDocumentPreview(client, wallet);This example first defines the folderKey where the preview and its associated resources will reside. It then constructs previewData with essential information, including a path to an image that will be uploaded as a resource. The imageResourceData and imageHash would typically come from your application's file system or content generation process. Finally, it creates a PutPreviewObjectCommand instance, including the PutObjectCommandInput for the image resource in the resources array, and sends it to DID Spaces.
This section provided a detailed guide on using the PutPreviewObjectCommand to manage rich previews for your content in DID Spaces. You can now effectively create and update how your objects are displayed. Proceed to the Get Preview section to learn how to retrieve this preview metadata.