Migration guide for @uploadcare/blocks v0.25.0
On this page
BREAKING CHANGES
Configuration in CSS is now deprecated. Although it currently works, it will be removed shortly. In lieu of this, we are introducing a new lr-config block for configuration definitions.
The
css-src
attribute is now required on solution blocks. This implies that the use of Shadow DOM is enforced.The
ctx-name
attribute is required for each block on the page.Method
setUploadMetadata
is deprecated in favour ofmetadata
DOM property on thelr-config
block.Method
addFiles
is deprecated in favour ofaddFileFromObject
CloudEditor
(lr-cloud-editor
) solution block is renamed toCloudImageEditor
(lr-cloud-image-editor
).CloudImageEditor
(lr-cloud-image-editor
) activity is renamed toCloudImageEditorActivity
(lr-cloud-image-editor-activity
).All solution bundles are prefixed with
lr-
prefix:
file-uploader-regular.min.js
->lr-file-uploader-regular.min.js
file-uploader-regular.min.css
->lr-file-uploader-regular.min.css
file-uploader-inline.min.js
->lr-file-uploader-inline.min.js
file-uploader-inline.min.css
->lr-file-uploader-inline.min.css
file-uploader-minimal.min.js
->lr-file-uploader-minimal.min.js
file-uploader-minimal.min.css
->lr-file-uploader-minimal.min.css
- Solution bundles do not automatically register blocks. You will need to register them manually:
import * as LR from 'https://cdn.jsdelivr.net/npm/@uploadcare/blocks/web/lr-file-uploader-regular.min.js'
LR.registerBlocks(LR)
javascript
Bundle
blocks.iife.js
is renamed toblocks.iife.min.js
.Bundle
blocks-browser.min.js
is deprecated. Useblocks.iife.min.js
instead.
How to migrate
Configuration
First and foremost, you need to shift all the configuration from CSS to the lr-config
block.
For instance, if you have the following CSS:
.config {
--ctx-name: 'my-uploader';
--cfg-pubkey: 'YOUR_PUBLIC_KEY';
--cfg-multiple-min: 0;
--cfg-multiple-max: 3;
}
css
Move it to the lr-config
block:
<lr-config
ctx-name="my-uploader"
pubkey="YOUR_PUBLIC_KEY"
multiple-min="0"
multiple-max="3"
></lr-config>
html
Subsequently, you should link your solution block to the lr-config
block using the ctx-name
attribute:
<lr-file-uploader-regular
ctx-name="my-uploader"
css-src="https://cdn.jsdelivr.net/npm/@uploadcare/blocks/web/lr-file-uploader-regular.min.css"
></lr-file-uploader-regular>
html
The property names remain the same but without the --cfg
prefix. For example,
--cfg-pubkey
becomes simply pubkey
.
See the configuration reference for more details.
Dynamic configuration updates
If you have dynamically updated CSS configuration like this:
const uploader = document.querySelector('lr-file-uploader-regular')
uploader.style.setProperty('--cfg-pubkey', 'YOUR_PUBLIC_KEY')
const uploaderCtx = document.querySelector('lr-upload-ctx-provider')
uploaderCtx.updateCtxCssData()
javascript
You need to update it to the following:
const config = document.querySelector('lr-config')
config.setAttribute('pubkey', 'YOUR_PUBLIC_KEY') // using attribute
config.pubkey = 'YOUR_PUBLIC_KEY' // or using DOM property
javascript
Both attributes and DOM properties are reactive, so you don't need to call
updateCtxCssData
anymore.
Shadow DOM and css-src
Shadow DOM is now enforced for all the solution blocks. It means that you need
to use css-src
attribute to attach CSS to the block.
If you previously attached CSS to the global like this:
<link href="https://cdn.jsdelivr.net/npm/@uploadcare/blocks/web/lr-file-uploader-regular.min.css" rel="stylesheet" />
<lr-file-uploader-regular class="lr-wgt-common"></lr-file-uploader-regular>
html
You need to use css-src
attribute instead:
<lr-file-uploader-regular
css-src="https://cdn.jsdelivr.net/npm/@uploadcare/blocks/web/lr-file-uploader-regular.min.css"
></lr-file-uploader-regular>
html
(Other attributes are omitted for brevity)
ctx-name
attribute
ctx-name
attribute is required for all the blocks now, even if you have only
one block on the page. It's used to wire blocks to the lr-config
block. For
example:
<lr-config ctx-name="my-uploader"></lr-config>
<lr-file-uploader-regular ctx-name="my-uploader"></lr-file-uploader-regular>
<lr-upload-ctx-provider ctx-name="my-uploader"></lr-upload-ctx-provider>
<lr-data-output ctx-name="my-uploader"></lr-data-output>
html
(Other attributes are omitted for brevity)
Replace setUploadMetadata
with metadata
DOM property
If you were using setUploadMetadata
method like this:
uploaderCtxProvider.setUploadMetadata({ foo: 'bar' })
javascript
You need to replace it with metadata
DOM property on the lr-config
block:
const config = document.querySelector('lr-config')
config.metadata = { foo: 'bar' }
// or
config.metadata = () => Promise.resolve({ foo: 'bar' })
javascript
See the configuration reference for more details.
Replace addFiles
with addFileFromObject
If you were using addFiles
method like this:
const file = new File(["foo"], "foo.txt", {
type: "text/plain",
});
uploaderCtxProvider.addFiles([file])
javascript
You need to replace it with addFileFromObject
:
const file = new File(["foo"], "foo.txt", {
type: "text/plain",
});
uploaderCtxProvider.addFileFromObject(file)
javascript
In case of multiple files, you need to call addFileFromObject
for each file:
const files = [
new File(["1"], "1.txt", {
type: "text/plain",
}),
new File(["2"], "2.txt", {
type: "text/plain",
}),
];
for(const file of files) {
uploaderCtxProvider.addFileFromObject(file)
}
javascript
See the addFileFromObject
reference for more details.
Rename CloudEditor
-> CloudImageEditor
If you were using a standalone lr-cloud-editor
solution block, you need to rename
it to lr-cloud-image-editor
like this:
<lr-cloud-image-editor
uuid="7c167b79-9f27-4489-8032-3f3be1840605"
css-src="https://cdn.jsdelivr.net/npm/@uploadcare/blocks/web/lr-cloud-image-editor.min.css"
ctx-name="my-editor"
></lr-cloud-image-editor>
html
Rename CloudImageEditor
-> CloudImageEditorActivity
If you were using lr-cloud-image-editor
activity block inside your custom
Symbiote.js templates, you need to rename it to lr-cloud-image-editor-activity
like this:
FileUploaderRegular.template = /* HTML */ `
<lr-simple-btn></lr-simple-btn>
<lr-modal strokes block-body-scrolling>
<lr-start-from>
<lr-drop-area with-icon clickable></lr-drop-area>
<lr-source-list wrap></lr-source-list>
<lr-copyright></lr-copyright>
</lr-start-from>
<lr-upload-list></lr-upload-list>
<lr-camera-source></lr-camera-source>
<lr-url-source></lr-url-source>
<lr-external-source></lr-external-source>
<lr-cloud-image-editor-activity></lr-cloud-image-editor-activity>
<!-- here it is -->
</lr-modal>
<lr-message-box></lr-message-box>
<lr-progress-bar-common></lr-progress-bar-common>
`
javascript
Rename imported JS and CSS bundles
Just rename all the imports according to the following table:
Old name | New name |
---|---|
file-uploader-regular.min.js | lr-file-uploader-regular.min.js |
file-uploader-regular.min.css | lr-file-uploader-regular.min.css |
file-uploader-inline.min.js | lr-file-uploader-inline.min.js |
file-uploader-inline.min.css | lr-file-uploader-inline.min.css |
file-uploader-minimal.min.js | lr-file-uploader-minimal.min.js |
file-uploader-minimal.min.css | lr-file-uploader-minimal.min.css |
For example:
<script type="module">
import * as LR from "https://cdn.jsdelivr.net/npm/@uploadcare/blocks/web/file-uploader-regular.min.js";
LR.registerBlocks(LR);
</script>
<lr-config ctx-name="my-uploader" pubkey="YOUR_PUBLIC_KEY"></lr-config>
<lr-file-uploader-regular
ctx-name="my-uploader"
css-src="https://cdn.jsdelivr.net/npm/@uploadcare/blocks/web/file-uploader-regular.min.css"
></lr-file-uploader-regular>
html
Became:
<script type="module">
import * as LR from "https://cdn.jsdelivr.net/npm/@uploadcare/blocks/web/lr-file-uploader-regular.min.js";
LR.registerBlocks(LR);
</script>
<lr-config ctx-name="my-uploader" pubkey="YOUR_PUBLIC_KEY"></lr-config>
<lr-file-uploader-regular
ctx-name="my-uploader"
css-src="https://cdn.jsdelivr.net/npm/@uploadcare/blocks/web/lr-file-uploader-regular.min.css"
></lr-file-uploader-regular>
html
Call registerBlocks
manually
If you have installed blocks using min.js
bundles, you need to call
registerBlocks
manually:
<script type="module">
import * as LR from "https://cdn.jsdelivr.net/npm/@uploadcare/blocks/web/lr-file-uploader-regular.min.js";
LR.registerBlocks(LR);
</script>
html
Rename blocks.iife.js
to blocks.iife.min.js
If you previously used the blocks.iife.js
bundle, you need to rename it to
blocks.iife.min.js
as follows:
<script src="https://cdn.jsdelivr.net/npm/@uploadcare/blocks/web/blocks.iife.min.js" async />
html
Rename blocks-browser.min.js
to blocks.iife.min.js
If you were using the connectBlocksFrom
method in conjunction with the
blocks-browser.min.js
bundle, you need to rename it to blocks.iife.min.js
,
as shown below:
connectBlocksFrom('https://cdn.jsdelivr.net/npm/@uploadcare/blocks/web/blocks.iife.min.js').then(
(LR) => {
LR.registerBlocks(LR);
// ...
}
);
javascript
If you were using blocks-browser.min.js
via a script
tag with type="module"
,
you need to rename it to blocks.min.js
, as shown below:
<script type="module">
import * as LR from 'https://cdn.jsdelivr.net/npm/@uploadcare/blocks/web/blocks.min.js';
LR.registerBlocks(LR);
</script>
html
If you were using blocks-browser.min.js
via a script
tag without
type="module"
, you need to rename it to blocks.iife.min.js
, as shown below:
<script src="https://cdn.jsdelivr.net/npm/@uploadcare/blocks/web/blocks.iife.min.js" async />
html