Changelog (Beta)

This beta release introduces APIs for Permissions:

• Plugins are now available to all users, not just the ones with Full Access.

• Calling a method that is not usable by the user will result in an error.

• isAllowedTo lets you check methods' availability to the user.

• subscribeToIsAllowedTo lets you subscribe to changes in isAllowedTo.

• useIsAllowedTo is a React hook version of subscribeToIsAllowedTo.

Learn more with the Permission guide.

Important: Make sure to update vite-plugin-framer to ^1.0.7 as framer-plugin now uses a top-level await and won't work without it. If you don't rely on vite-plugin-framer then make sure you target es2022 at the minimum. Vite targets esnext by default, but it might still need the following addition in its configuration:

optimizeDeps: { esbuildOptions: { target: "esnext" } }

esnext is a safe choice here as optimizeDeps is development-only.

This beta release brings many improvements to the Localization Beta APIs, including the ability to directly manage Localizations during the creation or updating of Collection Items, both for managed and non-managed Collections.

Localization

We are stabilizing these APIs and removing their unstable_ prefix. We are also making some changes to where these APIs can be called:

• getLocales, getDefaultLocale, and getActiveLocale are now available in all modes.

• setLocalizationData and getLocalizationGroups can no longer be called from the "configureManagedCollection" or "syncManagedCollection" plugin modes.

In addition, there are some breaking changes being made to property naming:

• getLocalizationGroups now returns a statusByLocale instead of the previous hiddenLocales.

• setLocalizationData now accepts a statusByLocaleByGroup instead of the previous hiddenLocalesByGroup.

• Localization Sources now have a valueByLocale property instead of the previous locales.

Collection

• When calling ManagedCollection.addItems or Collection.addItems, you can now pass statusByLocale, and a valueByLocale for each field in fieldData.

• When calling Collection.getItems, fields' values in fieldData that are localizable now have a valueByLocale property containing the field's Localized Values, and the item itself has a slugByLocale property with the slug's Localized Values.

• Added slugFieldBasedOn on non-managed Collections, which returns the ID of the field the slug is based on.

• Non-managed Enum Fields can now update, remove, and sort their Enum Cases.

• You can now pass a required property when creating fields, allowing them to be marked as required.

• Fixed a bug where adding items with a Formatted Text Field that contains HTML (e.g., <pre> tag) would sometimes error.

• Fixed a bug where it was not possible to update the referenced Collection of a Reference or Multi Reference Field on managed Collection.

Canvas

• Added an onDragComplete callback to the Draggable component.

This release introduces two entirely new sets of APIs for Plugins: Localization and Permissions. With the new Localization APIs, Plugins are now able to programmatically read and update a site’s Locales and Localization sources.
With the Permissions API, Plugins can check which permissions the Plugin user has (e.g. Design, Content-only) and adapt the Plugin functionality accordingly. Learn how to get started in the Localization Guide and Permission guide.

Note

The framer-plugin package now uses a top-level await, make sure to update vite-framer-plugin to 1.0.7 or higher.

Localization

This release introduces brand new APIs for managing your site's Localizations.

• getLocales lets you get all your site's Locales.

• getDefaultLocale gives you the default Locale.

• getActiveLocale gives you the active Locale.

• getLocalizationGroups retrives all Localization groups and sources.

• setLocalizationData lets you update your site's Localization data.

We have also added Localization support to other existing APIs.

• Collection.getItems now includes Localization data for each item.

• ManagedCollection.addItems lets you include item Localization data.

• Collection.addItems lets you include item Localization data.

• CollectionItem.setAttributes lets you include item Localization data.

Permissions (Preview)

Today, Plugins can only be launched and used by those with full permissions on a Project. A few weeks from now, we’ll allow Plugins to be launched and used by those without design permissions as well. With the Permissions API Preview, we’re giving Plugin authors time to proactively accommodate for this change via these new APIs. Learn more about these flows in the Permissions guide.

• Calling a method unavailable to the user will result in an error.

• isAllowedTo lets you check methods' availability to the user.

• subscribeToIsAllowedTo lets you subscribe to changes in isAllowedTo.

• useIsAllowedTo is a React hook version of subscribeToIsAllowedTo.

CMS

• slugFieldBasedOn is the ID of the field that a Collection's slug is based on.

• Enum Fields can now update, remove, and sort their Enum Cases.

• Fields can now be marked as required during creation.

• Fixed a bug where adding items with HTML content would sometimes error.

• Fixed a bug preventing the referenced Collection of fields being updated.

Canvas

• onDragComplete was added as a callback to the Draggable component.

• preferredImageRendering can now be provided when adding images.

Styles

• Fixed a bug where renaming a Text Style or Color Style would reset its path.

• Text Styles and Color Styles now both expose their full path.
  
  

Plugins version 3.0 enables entirely new functionality within CMS Plugins with a new set of APIs for modifying and adding to existing Collections that weren’t created by your Plugin (known as UnmanagedCollection). Along with this, we’ve made a few changes to the core CMS APIs to add stronger typing and set us up for additional features coming soon.

Breaking Changes

The following CMS functions now require their fieldData to be an object, with value and type properties. Which enforces stronger types across CMS APIs.

• Collection.getFields() now returns Field[].

• BooleanField, StringField, etc. are classes now.

• SupportedCollectionField type has been removed.

• CollectionField type has been removed.

• Collection.getItems() returns typed fieldData.

• CollectionItem.setAttributes() requires typed fieldData.

• ManagedCollection.addItems() requires typed fieldData.

// Before 
managedCollection.addItems([
  { [fieldID]: "Your Value" }
])

// After
managedCollection.addItems([
  { [fieldID]: {
      type: "string",
      value:  "Your Value"
  }
}])

Collections

• Plugins can now write to Collections.

• Added Collection.addItems().

• Added Collection.setItemOrder().

• Added Collection.setFieldOrder().

Collection Fields

• Collection.addFields() lets you create new fields.

• Field.setAttributes() allows you to update the field.

• Field.remove() removes the field from the Collection.

• Collection.removeFields() removes fields in bulk.

The 2.2.0 release brings some updates to the CMS API, with a focus on improving the experience around having multiple Managed Collections created by the same Plugin.

Managed Collections

• Added new ⁠getManagedCollections() method to get all Collections managed by your Plugin.

• Added ⁠setAsActive() method to select the active Collection in the Editor

• Deprecated ⁠getManagedCollection() in favor of ⁠getActiveManagedCollection().

• Fixed a bug where setting Plugin Data on a CollectionItemNode was throwing a Node not found error.

Collections

• Added support for ⁠FieldDivider type in collection fields.

• Added ⁠setAsActive() method to make a collection the active one.

• Added ⁠removeFields() method to remove fields by their ID.

• Added ⁠setFieldOrder() method to arrange fields in a specific order.

• Added ⁠slugFieldName property to Collection interface.

The 2.0 release contains a single breaking change to the id field of the APIs below. Our hashing algorithm for the id had a higher potential for ID collisions than expected. The id field will now be a different hashed value for the same user/project compared to 1.x.x. Logic that stores and compares these values will need updating. To migrate from the old value to the new value, you can reference the apiVersion1Id field.

• getProjectInfo()

• getCurrentUser()

• Resolution support has been added to all image APIs.

• Collection item draft status is now exposed in the API.

• Plugin windows now support maximum width/height.

Plugins initial public release.