File Management & Image Handling

Uploads land in Topol's storage unless you route them elsewhere, and these options are where that routing happens. The file manager can keep its built-in flow with your preferences applied, talk to your backend through the file management endpoints, or be replaced entirely with your own picker via customFileManager. Alongside the routing, a few options control image size limits, compression, and the built-in image editor.

customFileManager

The customFileManager option (boolean, default false) bypasses the built-in file manager. Whenever a user attempts to upload or select a file, the editor triggers your onOpenFileManager callback instead, so your own file picker, storage workflow, or upload system takes over.

Note that customFileManager is a config option, while onOpenFileManager is a callback passed next to config. Hand the selected file URL back to the editor with the chooseFile() method:

const LPE = LandingPageEditor({
  config: {
    authorize: { apiKey: "YOUR_API_KEY", userId: "user-123" },
    customFileManager: true,
  },
  onOpenFileManager: () => {
    // Open your custom file picker UI.
    // When the user selects a file, pass its URL back to the editor:
    openMyPicker((url) => LPE.chooseFile(url));
  },
});
LPE.render("#landing-page-editor");

Cleaning up deleted files: when users delete files or folders in the built-in file manager, the editor fires the onImageDelete callback with the deleted items, so the deletion can be mirrored in your own storage:

onImageDelete: (items) => {
  // items: [{ name, type: "file" | "folder", path, url?, key }]
  items.forEach((item) => deleteFromMyStorage(item));
};

imageMaxSize

The imageMaxSize option (number, default 2097152, i.e. 2 MB) sets the maximum allowed image size in bytes. The editor validates files before upload and rejects any that exceed the limit:

{
  imageMaxSize: 5242880 // 5 MB in bytes
}

For reference: 1 MB = 1048576 bytes, 5 MB = 5242880, 10 MB = 10485760.

imageCompressionOptions

The imageCompressionOptions object configures automatic compression and resizing of uploaded images. When it is not set, compression and auto-resize are enabled with quality 0.95 (JPEG) / 0.8 (PNG). The properties:

• qualityJpeg (number, 0 to 1): JPEG compression quality (default: 0.95)
• qualityPng (number, 0 to 1): PNG compression quality (default: 0.8)
• enableAutoResize (boolean): automatically resize large images (default: true)
• enableCompression (boolean): enable image compression (default: true)

If enableCompression is false, both compression and auto-resize are disabled.

{
  imageCompressionOptions: {
    qualityJpeg: 0.85,
    qualityPng: 0.8,
    enableAutoResize: true,
    enableCompression: true
  }
}

WARNING

Quality values use the 0 to 1 scale, not 0 to 100. A value like 85 is not rejected, but it feeds an out-of-range number into the compressor. Always use decimals between 0 and 1.

imageEditorOptions

The imageEditorOptions object configures the built-in image editor. Its one property, hideControls (string[]), removes the listed controls from the image editor UI:

{
  imageEditorOptions: {
    hideControls: ["crop"]
  }
}

The image editor supports cropping, rotation, resizing, and basic adjustments. The editor itself cannot be disabled through an option; the legacy imageEditor boolean is accepted but currently has no effect.

fileManagerPreferences

The fileManagerPreferences object adjusts the built-in file manager's UI defaults:

• defaultTilesView (boolean): show files in tiles/grid view by default (vs. list view)
• hidePexelsIntegration (boolean): hides the Pexels stock-image tab. Pexels is enabled by default.
• maxUploadingFiles (number, positive integer): caps how many files can be selected and uploaded at once.

{
  fileManagerPreferences: {
    defaultTilesView: true,
    hidePexelsIntegration: true,
    maxUploadingFiles: 5
  }
}

enableFileManagerInGif

The enableFileManagerInGif option (boolean, default false) lets users pick a GIF from the file manager instead of only through the Giphy integration:

{
  enableFileManagerInGif: true
}

API Integration for File Management

The built-in File Manager UI connects directly to your infrastructure through a set of endpoints: listing files and folders, uploading images, creating folders, deleting files or folders, and saving edited images from the built-in image editor.

All API responses must follow the expected structure to work correctly within the editor.

WARNING

Before implementing the endpoints, check how to work with API endpoints.

List Images & Folders

Used when the File Manager opens, to retrieve files and folders.

• URL: /{API.FOLDERS}
• Method: GET
• Params: path, hostname, userId, uuid
• Content-Type: application/json

The {key} placeholder

If your FOLDERS URL contains a {key} placeholder (e.g. https://your-domain.com/folders/{key}), the editor substitutes your API key into the path. Otherwise it appends the key as a ?key=<apiKey> query parameter.

Response:

[
  {
    "name": "filename.jpg",
    "date": "2024-12-01T14:23:00Z",
    "size": 512000,
    "path": "/path/",
    "type": "file",
    "extension": ".jpg",
    "url": "https://url-to-image.com/image.jpeg"
  },
  {
    "name": "holiday-images",
    "path": "/",
    "type": "folder"
  }
]

Create New Folder

Used when a user adds a new folder in the File Manager.

• URL: /{API.FOLDERS}
• Method: POST
• Content-Type: application/json

Request:

{
  "name": "new-folder",
  "path": "/user-123/"
}

The path value is prefixed with /{userId} (the authorize.userId), so a folder created at the file manager root arrives as "/user-123/" rather than "/". Identification values (hostname, userId, uuid, id, and the API key unless embedded in the URL) are sent as query parameters.

Response:

HTTP 2xx on success. The response body is not read by the editor.

Delete Images or Folders

Used when a user deletes selected images or folders. The editor automatically appends /delete to the FOLDERS API path.

• URL: /{API.FOLDERS}/delete
• Method: POST
• Content-Type: application/json

Request:

[
  {
    "name": "filename.jpg",
    "type": "file",
    "path": "/"
  },
  {
    "name": "old-folder",
    "type": "folder",
    "path": "/",
    "key": null
  }
]

Response:

HTTP 200 or 204 on success (no body required).

Image Upload

Used when a user uploads a file via the File Manager or drops an image onto an image block.

• URL: /{API.IMAGE_UPLOAD}
• Method: POST
• Content-Type: multipart/form-data

Request (form fields):

Field	Value
image	The file (binary)
path	Target folder path, e.g. /
uuid	The user ID

Response:

{
  "success": true,
  "url": "https://your-domain.com/images/uploaded-image.jpg",
  "name": "uploaded-image.jpg"
}

Upload Image from Image Editor

Used when a user saves an image from the integrated image editor.

• URL: /{API.IMAGE_EDITOR_UPLOAD}
• Method: POST
• Content-Type: application/json

WARNING

If customFileManager is enabled but api.IMAGE_EDITOR_UPLOAD is not set, saving from the image editor fails silently (the error only appears in the browser console). Always configure this endpoint when using a custom file manager.

Request:

{
  "content": "data:image/png;base64,...",
  "filename": "edited-image.png"
}

Response:

{
  "url": "https://your-domain.com/images/edited-image.png"
}