Installation

Run this code in the command prompt:

``cmd
$ npm i useblocks@1.0.103 -save
`

Add the Blocks plugin to your App config.


$3


Package import:
`javascript
const useblocksPlugin = require('useblocks/webpack')
`
Defining the package in the app:
`javascript
module.exports = {
plugins: [
new UseblocksWebpackPlugin(),
]
}
`

$3

Package import:
`javascript
import useblocksPlugin from 'useblocks/vite'
`
Defining the package in the app:
`javascript
export default defineConfig({
plugins: [useblocksPlugin()],
})
`

Initialization

Import the Blocks plugin into your component:
`javascript
import * as useblocks from "useblocks"
`
The Plugin configuration contains a parameter named getAuthToken. For authorization, you must pass the application's OAuth token to its value. For debugging purposes, the dev version of the plugin supports a mechanism for obtaining a token from the front of the application. To use this mechanism you need first to define auth-proxy in AppConfig:

$3

`javascript
curl --location 'https://api.useblocks.io/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=*' \
--data-urlencode 'client_secret=*' \
--data-urlencode 'grant_type=client_credentials'
`

$3

`javascript
useblocks.init({
getAuthToken: getAuthToken,
element: "#test",
content: {
title: "Email subject",
html: "EMAIL_CODE",
},
config: { }
}).then(instance => { })
`
You can get the EMAIL_CODE from our example or paste the HTML code of your own email

Configuration

Plugin configuration is JSON with several nesting levels. In the config you can set the appearance, content, and the logic the plugin will work with.

$3

You can send the element line into the plugin configuration. It is a DOM element selector and you need to initiate the plugin inside of it. If the element is not defined, the app will run in the background mode.

$3

The content section contains parameters of an email that must be displayed in the editor. This is what can be sent to this parameter:

#### {string}

HTML code of an email.

#### {object} email options
`javascript
{
id?: string; // A unique ID of a project in your system.
html?: string; // HTML code of an email.
subject?: string; // Email subject line.
preheader?: string; // Email preheader.
}

`

#### {object} full description
`javascript
{
temlateId?: string; // Email template ID in Blocks.
email?: object; // email options.
blocks?: []; // Additional blocks.
comments?: []; // Comments in an email.
}
`

You can change the content at any moment after the initialization with the help of the instance.show(content) method.

$3


This section is dedicated to setting the appearance and settings of the editor. You can change the configuration of this section after the initialization with the help of useblocks.setConfig or useblocks.updateConfig.
##### The list of parameters of the config section
| Parameter | Description | Default |
| ---------------------- | --------------------------------- | ------- |
| theme | Plugin theme: light, dark. | light |
| autosaveTimeout | Delay before autosave, ms. | 10000 |
| mergeTags | JSON with the list of dynamic variables. | undefined |
| styles | String with styles in CSS format. | '' |
| | | |
| headerShow | Show header. | true |
| headerArrowBackVisible | Show “Back” arrow. | true |
| headerTitleVisible | Show “Subject” field. | true |
| headerPreheaderVisible | Show “Preheader” field. | true |
| historyEnabled | Show “Version history” button. | true |
| codeEnabled | Show “Code mode” button. | true |
| codeSideEnabled | Show “Code mode” button when desktop/mobile toggle is available. | true |
| previewIconEnabled | Show “Preview” button. | true |
| previewModeEnabled | Link to Preview. | true |
| livePreviewEnabled | Show “Email client testing” button. | true |
| sendTestEnabled | Show “Send test” button. | true |
| sharePreviewEnabled | Show “Share” button. | true |
| webversionEnabled | Show link to web version. | true |
| commonStylesEnabled | Show content styles. | true |
| emailResponsiveControlEnabled | Show email responsiveness toggle. | true |
| templateNotEmAlertShow | Show alert that template is not from EM. | true |
| | | |
| emailDropdownMenuEnabled | Show email menu. | true |
| emailDropdownMenuClone | Show “Clone” item. | true |
| emailDropdownMenuImport | Show “Import” item. | true |
| emailDropdownMenuImportButton | Show “Import” as a button. | true |
| emailDropdownMenuLock | Show “Lock” item. | true |
| emailDropdownMenuRemove | Show “Delete” item. | true |
| | | |
| emailExportEnabled | Show “Export” button. | true |
| exportHtmlEnabled | Export to HTML. | true |
| exportZipEnabled | Export to ZIP. | true |
| exportClipboardEnabled | Export to clipboard. | true |
| exportWebHookEnabled | Export to webhook. | true |
| exportOutlookEnabled | Export to Outlook. | true |
| exportPdfEnabled | Export to PDF. | true |
| exportPngEnabled | Export to PNG. | true |
| | | |
| nextButtonEnabled | Show secondary button. | false |
| nextButtonText | Text on secondary button. | '' |
| saveButtonEnabled | Show primary button. | true |
| saveButtonText | Text on primary button. | true |
| commandButtonsEnabled | Show primary and secondary buttons. | true |
| | | |
| sidePanelFloating | Floating side panel. | true |
| desktopMobileSwitchRule | Modes switch bar. | true |
| desktopMobileSwitchPanel | Modes switch panel. | false |
| onlyCodeModeInMobile | Show only code on mobile. | false |
| | | |
| pathEnabled | Show breadcrumbs. | true |
| copyPasteEnabled | Show copy–paste block in iframe. | true |
| saveBlockEnabled | Show save block button. | true |
| editImageControlEnabled | Show image editing button. | true |
| | | |
| menuDirection | Side panel position. | 'right' |
| defaultBuildPanel | Default opened tab setting. | ''/'empty'/'project'/'common'/'template' |
| commentsEnabled | Show “Comments” button. | true |
| aiAssistentEnabled | Show “AI assistant”. | true |
| optimizeEnabled | Show “Optimization” button. | true |
| optimizeLinksEnabled | Show links check. | true |
| optimizeImagesEnabled | Show images check. | true |
| optimizeSpamAssassinEnabled | Show SpamAssassin check. | true |
| optimizeCheckCodeEnabled | Show code check. | true |
| settingsEnabled | Show “Settings” button. | true |
| UTMEnabled | Show UTM tags tab. | true |
| descriptionEnabled | Show “Description” field in settings. | true |
| tagsEnabled | Show “Tags” field in settings. | true |
| switchDesktopMobilePropsEnabled | Show mobile properties toggle. | true |
| stepToOtherElementEnabled | Show buttons to jump to other elements. | true |
| deleteButtonEnabled | Show delete element button. | true |
| toggleSidePanel | Allow collapsing side panel. | true |
| blocksSectionsShow | Show blocks menu. | true |
| blocksEmptyEnabled | Show empty blocks. | true |
| blocksSavedEnabled | Show saved blocks. | true |
| blocksCommonEnabled | Show common blocks. | true |
| blocksTemplateEnabled | Show template blocks. | true |
| blocksSearchEnabled | Show blocks search. | true |
| blocksAddPanelEnabled | Show add block panel in visual editor. | true |
| imagePathDropdownEnabled | Show dropdown with image path. | true |
| | | |
| formFieldImageTitleEnabled | Show title field in image form. | true |
| formFieldBorderEnabled | Show border controls. | true |
| formFieldBorderRadiusEnabled | Show border radius controls. | true |
| formFieldBoxShadowEnabled | Show shadow controls. | true |
| formFieldVisibilityEnabled | Show element visibility controls. | true |
| formFieldExportAsPictureEnabled | Show “export as image” toggle. | true |
| | | |
| formButtonFieldInsertImageEnabled | Show “insert image into text” button for button. | true |
| formButtonFieldVerticalAlignEnabled | Show vertical alignment controls for button. | true |
| formButtonFieldTextAlignEnabled | Show text alignment controls for button. | true |
| formButtonFieldBackgroundImageEnabled | Show background image controls for button. | true |
| formButtonFieldPaddingsEnabled | Show padding controls for button. | true |
| formButtonFieldReplacerEnabled | Show replacer for button. | true |
| | | |
| formCellFieldVerticalAlignEnabled | Show vertical alignment controls for cell. | true |
| formCellFieldBackgroundImageEnabled | Show background image controls for cell. | true |
| formCellFieldPaddingsEnabled | Show padding controls for cell. | true |
| formCellFieldSizeEnabled | Show width and height controls. | true |
| | | |
| formImageFieldVerticalAlignEnabled | Show vertical alignment controls for image. | true |
| formImageFieldReplacerEnabled | Show replacer for image. | true |
| formImageFieldHeightEnabled | Show height field for image. | true |
| | | |
| formTableFieldBackgroundImageEnabled | Show background image controls for table. | true |
| formDivFieldBackgroundImageEnabled | Show background image controls for container. | true |
| formEmailFieldBackgroundImageEnabled | Show background image controls for email. | true |
| | | |
| formTextFieldTypografEnabled | Show typograph button. | true |
| formTextFieldReplacerEnabled | Show replacer button. | true |
| | | |
| elementImageEnabled | Element Image. | true |
| elementTextEnabled | Element Text. | true |
| elementHeaderEnabled | Element Heading. | true |
| elementButtonEnabled | Element Button. | true |
| elementListULEnabled | Element List UL. | true |
| elementListOLEnabled | Element List OL. | true |
| elementDividerEnabled | Element Divider. | true |
| elementSpacerEnabled | Element Spacer. | true |
| elementSocialEnabled | Element Social. | true |
| elementTableEnabled | Element Table. | true |
| elementCountdownEnabled | Element Countdown. | true |
| elementVideoEnabled | Element Video. | true |
| elementAIimageEnabled | Element AI image. | true |
| elementAItextEnabled | Element AI text. | true |
| elementCarouselEnabled | Element AMP carousel. | true |
| elementAccordionEnabled | Element AMP accordion. | true |
| elementFormEnabled | Element AMP form. | true |
| | | |
| imageCenterStockEnabled | Stock photos tab. | true |
| imageCenterGifEnabled | Stock GIFs tab. | true |
| imageCenterEditorEnabled | Image editor tab. | true |
| compressMaxSize | Max image size after optimization, MB. | true |
| compressMaxWidthOrHeight | Max image width after optimization, px. | true |

$3

Events can be sent to configurations or added to them later while working with the instance of the plugin. All event subscribers can be asynchronous features.

#### Example
`javascript
useblocks.init({
....,
// Subscription to events in the initialization.
handleReadEmail: (e) => {},
handleSaveEmail: async (e) => {}
}).then((instance) => {
// Subscription to events after the initialization.
const dispose = instance.handleReadEmail(e => {});
const dispose = instance.handleSaveEmail(async (e) => {});
});
`

By sending the asynchronous feature you can implement the asynchronous data load.
#### Example
`javascript
useblocks.init({
element: "#test",
content: {
id: "1"
}
handleReadEmail: async (id) => {
return await fetchData(id); // Your data fetch feature.
}
}).then((instance) => {
setTimeout(() => instance.show({ id: "2" }), 1000)
});
`

$3

| Name | Description |
| ------------------------- | -------------------------------------------- |
| handleReadEmail | Read email |
| handleSaveEmail | Save / update email |
| handleReadEmailRevisions | Read autosave list |
| handleEmailAutosave | Autosave |
| handleReadBlocks | Read project blocks list |
| handleSaveBlock | Save / update project block |
| handleRemoveBlock | Delete project block |
| handleReadComments | Read email comments list |
| handleSaveComment | Save / update comment |
| handleRemoveComment | Delete email comment |
| handleSaveButtonClick | Email save button click |
| handleNextButtonClick | Next button click |
| handlePreviousButtonClick | Back button click |
| handleEmailChanged | Any email parameter changed |
| handleHtmlChanged | Email HTML changed |
| handleDestroy | Plugin destroy |
| handleLoad | Plugin instance initialization completed |
| handleLoadImage | Load images |
| handleNotify | Notification |
| handleError | Error notification |
| handleSuccess | Success notification |
| handleTestEmailSend | Test email send |
| handleTestEmailModal | Open test email modal window |

$3

| Method name | Description |
| ------------------------- | -------------------------------------------- |
| init | Initialization (async) |
| show | Update content after initialization |
| destroy | Destroy instance |
| reset | Reset all configuration |
| getEmail | Get current email |
| getConfig | Get configuration |
| getBlocks | Get project blocks |
| getComments | Get email comments |
| getEmailRevisions | Get version control list |
| setConfig | Set new config parameters |
| updateConfig | Add to config parameters |
| notify | Show notifications |
| getElement | Get initialization element |
| save | Save email |
| compileEmail | Get compiled email |

📂 File Manager

To enable the file manager, you need to specify the following configuration during initialization:

`ts
emailmaker.init({
storageProvider: ..., // implementation of the StorageProvider interface
config: {
imageCenterFileManagerView: true
}
});
`

The fileManager section controls the features of the file manager. All fields are optional; if omitted or set to false, the corresponding feature is disabled.

#### Basic Operations

- enableTrash — enables trash functionality for deleted files. When enabled, files are moved to trash instead of permanent deletion. Default: true
- enableRenameFolder — allows renaming folders. Default is true
- enableRenameFile — allows renaming files. Default is true
- enableUpdateFile — allows updating file content or metadata. Default is true
- enableEdit — allows editing files (changing content or properties). Default is true
- enableMoveFile — allows moving files between folders. Default is true
- enableMoveFolder — allows moving folders. Default is true
- enableCopyFile — allows copying files. Default is true
- enableCopyFolder — allows copying folders. Default is true
- enableDelete — allows deleting files and folders. When the recycle bin is enabled, files are moved there instead of being permanently deleted. Default is true
- multiSelect — allows multiple selection of files and folders for batch operations. Default is true
- defaultFolderName — default folder name

#### Pagination & Display

- enablePagination — enables paginated navigation. If disabled, all items are loaded at once. Default: true

#### Client-Side Processing

- clientSideSorting — client-side file sorting.
- If true, applies standard sorting (by name ascending).
- If a function is provided, it receives the current file array, optional sortBy and sortOrder, and returns a sorted array.

- clientSidePaging — client-side file pagination.
- If true, applies standard array slicing based on page and limit.
- If a function is provided, it receives the file array, page and limit, and returns an array for the specific page only.

- clientSideFilter — client-side file filtering.
- If true, applies standard filtering by search text.
- If a function is provided, it receives the file array and optional search, and returns a filtered array.

#### Cache Strategy

- cacheStrategy — caching strategy for performance optimization.
- ttl — cache time-to-live in milliseconds. Default: 300000 (5 minutes)
- errorTtl — cache TTL for errors in milliseconds. Default: 60000 (1 minute)
- allowSortedInsert — allows inserting elements into sorted arrays without full cache invalidation. Default: false
- allowSearchInsert — allows inserting elements into filtered arrays without full cache invalidation. Default: false
- invalidateOnPaginationFull — marks cache as stale when inserting into a full paginated page. Default: true
- comparator — comparison function for sorting two files. Default: name-based comparison
- filterMatch — function to check if a file passes current filters. Default: name-based search




$3

#### Properties

| Property | Type | Description | Default |
|----------|------|-------------|---------|
| pathMode | boolean | Use path as identifier for folders | - |
| rootId | string | Custom identifier for root folder | '' |
| trashPath | string | Path to trash/recycle bin folder | - |
| tempPath | string | Path to temporary folder for uploads | - |
| useSoftDelete | boolean | Enable client-side soft delete | false |
| ensureFolderTrailingSlash | boolean | Add a trailing slash to folder paths | true |
| validateDuplicates | boolean | Client-side check for existing files or folders | - |

#### Methods

##### Core Methods

| Method | Parameters | Returns | Description |
|--------|------------|---------|-------------|
| getItems | options:
- folderId?: string
- search?: string
- sortBy?: string
- sortOrder?: 'asc'\|'desc'
- page?: number
- limit?: number
- itemType: 'all'\|'file'\|'folder' | { items: FileSystemItem[], pagination?: Partial } | Retrieve files/folders with filtering, sorting, pagination |
| createFolder | name: string, parentid?: string | FileSystemItem | Create new folder |
| uploadFile | file:
- name: string
- size: number
- type: string
- folderId?: string
- data: Blob \| string
- thumbnail?: string
- dimensions?: string
- aspectRatio?: string
- extension?: string | FileSystemItemUpdate | Upload file with metadata |
| uploadFiles | request:
- items: { requestId?: string, name: string, size: number, type: string, folderId?: string \| null, data: Blob \| string, extension?: string }[]
- folderId?: string \| null | BatchResult | Upload multiple files. The order of items matters — if requestId is not provided, results are matched by index |
| uploadFileByUrl | url: string, folderId?: string | FileSystemItem | Upload file from URL (check for existing files) |
| findItemByPath | path: string | FileSystemItem \| undefined | Find system files/folders by path |
| setController | controller: StorageProviderController | void | Set cache management controller |
| getFileData | file: FileSystemItem | Blob | Get file content as blob |
| getUrl | file: FileSystemItem | string | Get file access URL |
| getThumbnailUrl | file: FileSystemItem | string | Get thumbnail URL |
| renameItem | item: FileSystemItem, newName: string | FileSystemItemUpdate | Rename file/folder |
| deleteItem | item: FileSystemItem | void | Delete single item (moves to trash if soft delete enabled) |
| deleteItems | items: FileSystemItem[] | BatchResult | Delete multiple items |
| moveItem | item: FileSystemItem, targetFolderId?: string | FileSystemItemUpdate | Move single item |
| moveItems | items: FileSystemItem[], targetFolderId?: string | BatchResult | Move multiple items |
| copyItem | item: FileSystemItem, targetFolderId?: string | FileSystemItemUpdate | Copy single item |
| copyItems | items: FileSystemItem[], targetFolderId?: string | BatchResult | Copy multiple items |
| updateFile | file: FileSystemItem, updates: metadata object | FileSystemItemUpdate | Update file metadata/content |

##### Type Definitions

- MayBePromise: T | Promise
- FileSystemItem: File or folder object
- FileSystemItemUpdate: Item with changed fields
- BatchResult: Result with success/failure details
- ApiPaginationResponse: Pagination metadata

##### Important Notes

- Soft Delete: When useSoftDelete=true, delete operations move items to trashPath
- Root Folder: Use rootId or empty string for root operations
- Path Resolution: trashPath and tempPath are resolved to actual folder IDs
- URL Upload: Should check if file already exists on current server
- Cache Control: Use setController` for cache invalidation requests

$3

none