useblocks-dev

Installation

Run this code in the command prompt:

$ npm i useblocks@1.0.104-alpha.4 -save

Add the Blocks plugin to your App config.

For the Webpack module bundler

Package import:

const useblocksPlugin = require('useblocks/webpack')

Defining the package in the app:

module.exports = {
	plugins: [
		new UseblocksWebpackPlugin(),
	]
}

For the Vite module bundler

Package import:

import useblocksPlugin from 'useblocks/vite'

Defining the package in the app:

export default defineConfig({
	plugins: [useblocksPlugin()],
})

Initialization

Import the Blocks plugin into your component:

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:

Fetching the OAuth token on the backend

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'

Creating the Blocks plugin entity

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.

Element

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.

Content

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

{
	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

{
	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.

Config

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
codeModeDirection	Default code editor display mode	none
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

Events

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

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

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)
});

Events

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

Methods

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:

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

Interface StorageProvider

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<ApiPaginationResponse> }	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<UploadFileResultData>	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<never>	Delete multiple items
moveItem	item: FileSystemItem, targetFolderId?: string	FileSystemItemUpdate	Move single item
moveItems	items: FileSystemItem[], targetFolderId?: string	BatchResult<FileSystemItemUpdate>	Move multiple items
copyItem	item: FileSystemItem, targetFolderId?: string	FileSystemItemUpdate	Copy single item
copyItems	items: FileSystemItem[], targetFolderId?: string	BatchResult<FileSystemItemUpdate>	Copy multiple items
updateFile	file: FileSystemItem, updates: metadata object	FileSystemItemUpdate	Update file metadata/content

Type Definitions

• MayBePromise<T>: T | Promise<T>
• FileSystemItem: File or folder object
• FileSystemItemUpdate: Item with changed fields
• BatchResult<T>: 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

Keywords

none