Migration guide for @uploadcare/blocks v0.25.0

BREAKING CHANGES

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

  2. The css-src attribute is now required on solution blocks. This implies that the use of Shadow DOM is enforced.

  3. The ctx-name attribute is required for each block on the page.

  4. Method setUploadMetadata is deprecated in favour of metadata DOM property on the lr-config block.

  5. Method addFiles is deprecated in favour of addFileFromObject

  6. CloudEditor (lr-cloud-editor) solution block is renamed to CloudImageEditor (lr-cloud-image-editor).

  7. CloudImageEditor (lr-cloud-image-editor) activity is renamed to CloudImageEditorActivity (lr-cloud-image-editor-activity).

  8. 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
  1. Solution bundles do not automatically register blocks. You will need to register them manually:
1import * as LR from 'https://cdn.jsdelivr.net/npm/@uploadcare/blocks@0.25.0/web/lr-file-uploader-regular.min.js'
2
3LR.registerBlocks(LR)
  1. Bundle blocks.iife.js is renamed to blocks.iife.min.js.

  2. Bundle blocks-browser.min.js is deprecated. Use blocks.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:

1.config {
2 --ctx-name: 'my-uploader';
3 --cfg-pubkey: 'YOUR_PUBLIC_KEY';
4 --cfg-multiple-min: 0;
5 --cfg-multiple-max: 3;
6}

Get YOUR_PUBLIC_KEY from API keys.

Move it to the lr-config block:

1<lr-config
2 ctx-name="my-uploader"
3 pubkey="YOUR_PUBLIC_KEY"
4 multiple-min="0"
5 multiple-max="3"
6></lr-config>

Subsequently, you should link your solution block to the lr-config block using the ctx-name attribute:

1<lr-file-uploader-regular
2 ctx-name="my-uploader"
3 css-src="https://cdn.jsdelivr.net/npm/@uploadcare/blocks@0.25.0/web/lr-file-uploader-regular.min.css"
4></lr-file-uploader-regular>

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:

1const uploader = document.querySelector('lr-file-uploader-regular')
2uploader.style.setProperty('--cfg-pubkey', 'YOUR_PUBLIC_KEY')
3
4const uploaderCtx = document.querySelector('lr-upload-ctx-provider')
5uploaderCtx.updateCtxCssData()

You need to update it to the following:

1const config = document.querySelector('lr-config')
2config.setAttribute('pubkey', 'YOUR_PUBLIC_KEY') // using attribute
3config.pubkey = 'YOUR_PUBLIC_KEY' // or using DOM property

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:

1<link href="https://cdn.jsdelivr.net/npm/@uploadcare/blocks@0.25.0/web/lr-file-uploader-regular.min.css" rel="stylesheet" />
2
3<lr-file-uploader-regular class="lr-wgt-common"></lr-file-uploader-regular>

You need to use css-src attribute instead:

1<lr-file-uploader-regular
2 css-src="https://cdn.jsdelivr.net/npm/@uploadcare/blocks@0.25.0/web/lr-file-uploader-regular.min.css"
3></lr-file-uploader-regular>

(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:

1<lr-config ctx-name="my-uploader"></lr-config>
2<lr-file-uploader-regular ctx-name="my-uploader"></lr-file-uploader-regular>
3<lr-upload-ctx-provider ctx-name="my-uploader"></lr-upload-ctx-provider>
4<lr-data-output ctx-name="my-uploader"></lr-data-output>

(Other attributes are omitted for brevity)

Replace setUploadMetadata with metadata DOM property

If you were using setUploadMetadata method like this:

1uploaderCtxProvider.setUploadMetadata({ foo: 'bar' })

You need to replace it with metadata DOM property on the lr-config block:

1const config = document.querySelector('lr-config')
2config.metadata = { foo: 'bar' }
3// or
4config.metadata = () => Promise.resolve({ foo: 'bar' })

See the configuration reference for more details.

Replace addFiles with addFileFromObject

If you were using addFiles method like this:

1const file = new File(["foo"], "foo.txt", {
2 type: "text/plain",
3});
4uploaderCtxProvider.addFiles([file])

You need to replace it with addFileFromObject:

1const file = new File(["foo"], "foo.txt", {
2 type: "text/plain",
3});
4uploaderCtxProvider.addFileFromObject(file)

In case of multiple files, you need to call addFileFromObject for each file:

1const files = [
2 new File(["1"], "1.txt", {
3 type: "text/plain",
4 }),
5 new File(["2"], "2.txt", {
6 type: "text/plain",
7 }),
8];
9for(const file of files) {
10 uploaderCtxProvider.addFileFromObject(file)
11}

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:

1<lr-cloud-image-editor
2 uuid="7c167b79-9f27-4489-8032-3f3be1840605"
3 css-src="https://cdn.jsdelivr.net/npm/@uploadcare/blocks@0.25.0/web/lr-cloud-image-editor.min.css"
4 ctx-name="my-editor"
5></lr-cloud-image-editor>

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:

1FileUploaderRegular.template = /* HTML */ `
2 <lr-simple-btn></lr-simple-btn>
3
4 <lr-modal strokes block-body-scrolling>
5 <lr-start-from>
6 <lr-drop-area with-icon clickable></lr-drop-area>
7 <lr-source-list wrap></lr-source-list>
8 <lr-copyright></lr-copyright>
9 </lr-start-from>
10 <lr-upload-list></lr-upload-list>
11 <lr-camera-source></lr-camera-source>
12 <lr-url-source></lr-url-source>
13 <lr-external-source></lr-external-source>
14 <lr-cloud-image-editor-activity></lr-cloud-image-editor-activity>
15 <!-- here it is -->
16 </lr-modal>
17
18 <lr-message-box></lr-message-box>
19 <lr-progress-bar-common></lr-progress-bar-common>
20`

Rename imported JS and CSS bundles

Just rename all the imports according to the following table:

Old nameNew name
file-uploader-regular.min.jslr-file-uploader-regular.min.js
file-uploader-regular.min.csslr-file-uploader-regular.min.css
file-uploader-inline.min.jslr-file-uploader-inline.min.js
file-uploader-inline.min.csslr-file-uploader-inline.min.css
file-uploader-minimal.min.jslr-file-uploader-minimal.min.js
file-uploader-minimal.min.csslr-file-uploader-minimal.min.css

For example:

1<script type="module">
2 import * as LR from "https://cdn.jsdelivr.net/npm/@uploadcare/blocks@0.25.0/web/file-uploader-regular.min.js";
3 LR.registerBlocks(LR);
4</script>
5
6<lr-config ctx-name="my-uploader" pubkey="YOUR_PUBLIC_KEY"></lr-config>
7
8<lr-file-uploader-regular
9 ctx-name="my-uploader"
10 css-src="https://cdn.jsdelivr.net/npm/@uploadcare/blocks@0.25.0/web/file-uploader-regular.min.css"
11></lr-file-uploader-regular>

Became:

1<script type="module">
2 import * as LR from "https://cdn.jsdelivr.net/npm/@uploadcare/blocks@0.25.0/web/lr-file-uploader-regular.min.js";
3 LR.registerBlocks(LR);
4</script>
5
6<lr-config ctx-name="my-uploader" pubkey="YOUR_PUBLIC_KEY"></lr-config>
7
8<lr-file-uploader-regular
9 ctx-name="my-uploader"
10 css-src="https://cdn.jsdelivr.net/npm/@uploadcare/blocks@0.25.0/web/lr-file-uploader-regular.min.css"
11></lr-file-uploader-regular>

Call registerBlocks manually

If you have installed blocks using min.js bundles, you need to call registerBlocks manually:

1<script type="module">
2 import * as LR from "https://cdn.jsdelivr.net/npm/@uploadcare/blocks@0.25.0/web/lr-file-uploader-regular.min.js";
3 LR.registerBlocks(LR);
4</script>

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:

1<script src="https://cdn.jsdelivr.net/npm/@uploadcare/blocks@0.25.0/web/blocks.iife.min.js" async />

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:

1connectBlocksFrom('https://cdn.jsdelivr.net/npm/@uploadcare/blocks@0.25.0/web/blocks.iife.min.js').then(
2 (LR) => {
3 LR.registerBlocks(LR);
4 // ...
5 }
6);

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:

1<script type="module">
2 import * as LR from 'https://cdn.jsdelivr.net/npm/@uploadcare/blocks@0.25.0/web/blocks.min.js';
3
4 LR.registerBlocks(LR);
5</script>

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:

1<script src="https://cdn.jsdelivr.net/npm/@uploadcare/blocks@0.25.0/web/blocks.iife.min.js" async />