diff --git a/16/umbraco-forms/developer/extending/README.md b/16/umbraco-forms/developer/extending/README.md index 635b9fd8f8e..5e9204b570c 100644 --- a/16/umbraco-forms/developer/extending/README.md +++ b/16/umbraco-forms/developer/extending/README.md @@ -1,9 +1,65 @@ # Extending -Umbraco Forms functionality can be extended in different ways. In this section we focus on techniques available to a back-end/C# developer. +Umbraco Forms functionality can be extended in different ways. For front-end extensions, specifically via theming, see the [Themes](../themes.md) section. +## Extending the Backoffice +Umbraco Forms publishes an NPM package called `@umbraco-forms/backoffice` that holds typings and other niceties to build extensions. + +{% hint style="warning" %} +Ensure that you install the version of the Backoffice package that is compatible with your Umbraco Forms installation. You can find the appropriate version on the [`@umbraco-forms/backoffice` npm page](https://www.npmjs.com/package/@umbraco-forms/backoffice). +{% endhint %} + +You can install this package by running the command: + +```bash +npm install -D @umbraco-forms/backoffice@x.x.x +``` + +This will add a package to your devDependencies containing the TypeScript definitions for Umbraco Forms. + +### TSConfig + +Make sure to configure your TypeScript compiler so it includes the Global Types from the package. This enables you to utilize the declared Extension Types. If your project uses other Packages that provide their Extension Types, list those as well. + +In your `tsconfig.json` file, add the array `types` inside `compilerOptions`, with the entry of `@umbraco-forms/backoffice`: + +```json +{ + "compilerOptions": { + ... + "types": [ + ... + "@umbraco-forms/backoffice" + ] + } +} +``` + +### Take extra care when using Vite + +It is important that this namespace is ignored in your bundler. If you are using Vite, you can add the following to your `vite.config.ts` file: + +```ts +import { defineConfig } from "vite"; + +export default defineConfig({ + // other config + // ... + // add this to your config + build: { + rollupOptions: { + external: [/^@umbraco/], + }, + } +}); +``` + +This ensures that the Umbraco Backoffice packages are not bundled with your package. + +Read more about using Vite with Umbraco in the [Vite Package Setup](https://docs.umbraco.com/umbraco-cms/customizing/development-flow/vite-package-setup) article. + ## Developing Custom Providers Although the Forms package comes with many fields, workflows and other built-in types, you can still create and develop your own if needed. diff --git a/16/umbraco-forms/developer/extending/adding-a-fieldtype.md b/16/umbraco-forms/developer/extending/adding-a-fieldtype.md index 57b05eafd03..ff8b1a44b24 100644 --- a/16/umbraco-forms/developer/extending/adding-a-fieldtype.md +++ b/16/umbraco-forms/developer/extending/adding-a-fieldtype.md @@ -172,6 +172,18 @@ With Forms 14+, aspects of the presentation and functionality of the custom fiel To create custom backoffice components for Umbraco 14, it's recommended to use a front-end build setup using Vite, TypeScript, and Lit. For more information, see the [Extension with Vite, TypeScript, and Lit](https://app.gitbook.com/s/G1Byxw7XfiZAj8zDMCTD/tutorials/creating-your-first-extension#extension-with-vite-typescript-and-lit) article. +The examples here are using the `@umbraco-forms/backoffice` package to get access to Forms-specific types and contexts. It is recommended to install this package as a development dependency in your project. + +{% hint style="warning" %} +Ensure that you install the version of the Backoffice package that is compatible with your Umbraco Forms installation. You can find the appropriate version on the [`@umbraco-forms/backoffice` npm page](https://www.npmjs.com/package/@umbraco-forms/backoffice). +{% endhint %} + +```bash +npm install -D @umbraco-forms/backoffice@x.x.x +``` + +This will add a package to your devDependencies containing the TypeScript definitions for Umbraco Forms. + To display a name and description on a custom field, you need to register a JavaScript file as shown in the [Localization](https://app.gitbook.com/s/7MBVdnTbFiAgWuRsHpNS/customizing/extending-overview/extension-types/localization) article. ### Field Preview @@ -240,14 +252,14 @@ And it is registered via a manifest: import MyFieldPreviewSliderElement from './slider-preview.element.js'; const sliderPreviewManifest = { - type: "formsFieldPreview", - alias: "My.FieldPreview.Slider", - name: "Forms UUI Slider Field Preview", - api: MyFieldPreviewSliderElement, - element: () => import('./slider-preview.element.js') - }; - - export const manifests = [sliderPreviewManifest]; + type: "formsFieldPreview", + alias: "My.FieldPreview.Slider", + name: "Forms UUI Slider Field Preview", + api: MyFieldPreviewSliderElement, + element: () => import('./slider-preview.element.js') +}; + +export const manifests = [sliderPreviewManifest]; ``` ### Field Editor @@ -403,20 +415,23 @@ The following code shows the structure for these converter elements. ```javascript import type { UmbPropertyValueData } from "@umbraco-cms/backoffice/property"; +import type { FormsSettingValueConverterApi, Setting } from "@umbraco-forms/backoffice"; -export class SliderSettingValueConverter { - - async getSettingValueForEditor(setting, alias: string, value: string) { +export class SliderSettingValueConverter + implements FormsSettingValueConverterApi { + async getSettingValueForEditor(setting: Setting, alias: string, value: string) { return Promise.resolve(value); } - async getSettingValueForPersistence(setting, valueData: UmbPropertyValueData) { - return Promise.resolve(valueData.value); + async getSettingValueForPersistence(setting: Setting, valueData: UmbPropertyValueData) { + return Promise.resolve(valueData.value?.toString() || ""); } - async getSettingPropertyConfig(setting, alias: string, values: UmbPropertyValueData[]) { + async getSettingPropertyConfig(setting: Setting, alias: string, values: UmbPropertyValueData[]) { return Promise.resolve([]); } + + destroy(): void { } } ``` diff --git a/17/umbraco-forms/developer/extending/README.md b/17/umbraco-forms/developer/extending/README.md index 635b9fd8f8e..5e9204b570c 100644 --- a/17/umbraco-forms/developer/extending/README.md +++ b/17/umbraco-forms/developer/extending/README.md @@ -1,9 +1,65 @@ # Extending -Umbraco Forms functionality can be extended in different ways. In this section we focus on techniques available to a back-end/C# developer. +Umbraco Forms functionality can be extended in different ways. For front-end extensions, specifically via theming, see the [Themes](../themes.md) section. +## Extending the Backoffice +Umbraco Forms publishes an NPM package called `@umbraco-forms/backoffice` that holds typings and other niceties to build extensions. + +{% hint style="warning" %} +Ensure that you install the version of the Backoffice package that is compatible with your Umbraco Forms installation. You can find the appropriate version on the [`@umbraco-forms/backoffice` npm page](https://www.npmjs.com/package/@umbraco-forms/backoffice). +{% endhint %} + +You can install this package by running the command: + +```bash +npm install -D @umbraco-forms/backoffice@x.x.x +``` + +This will add a package to your devDependencies containing the TypeScript definitions for Umbraco Forms. + +### TSConfig + +Make sure to configure your TypeScript compiler so it includes the Global Types from the package. This enables you to utilize the declared Extension Types. If your project uses other Packages that provide their Extension Types, list those as well. + +In your `tsconfig.json` file, add the array `types` inside `compilerOptions`, with the entry of `@umbraco-forms/backoffice`: + +```json +{ + "compilerOptions": { + ... + "types": [ + ... + "@umbraco-forms/backoffice" + ] + } +} +``` + +### Take extra care when using Vite + +It is important that this namespace is ignored in your bundler. If you are using Vite, you can add the following to your `vite.config.ts` file: + +```ts +import { defineConfig } from "vite"; + +export default defineConfig({ + // other config + // ... + // add this to your config + build: { + rollupOptions: { + external: [/^@umbraco/], + }, + } +}); +``` + +This ensures that the Umbraco Backoffice packages are not bundled with your package. + +Read more about using Vite with Umbraco in the [Vite Package Setup](https://docs.umbraco.com/umbraco-cms/customizing/development-flow/vite-package-setup) article. + ## Developing Custom Providers Although the Forms package comes with many fields, workflows and other built-in types, you can still create and develop your own if needed. diff --git a/17/umbraco-forms/developer/extending/adding-a-fieldtype.md b/17/umbraco-forms/developer/extending/adding-a-fieldtype.md index 57b05eafd03..1655a41d47c 100644 --- a/17/umbraco-forms/developer/extending/adding-a-fieldtype.md +++ b/17/umbraco-forms/developer/extending/adding-a-fieldtype.md @@ -172,6 +172,18 @@ With Forms 14+, aspects of the presentation and functionality of the custom fiel To create custom backoffice components for Umbraco 14, it's recommended to use a front-end build setup using Vite, TypeScript, and Lit. For more information, see the [Extension with Vite, TypeScript, and Lit](https://app.gitbook.com/s/G1Byxw7XfiZAj8zDMCTD/tutorials/creating-your-first-extension#extension-with-vite-typescript-and-lit) article. +The examples here are using the `@umbraco-forms/backoffice` package to get access to Forms-specific types and contexts. It is recommended to install this package as a development dependency in your project. + +{% hint style="warning" %} +Ensure that you install the version of the Backoffice package that is compatible with your Umbraco Forms installation. You can find the appropriate version on the [`@umbraco-forms/backoffice` npm page](https://www.npmjs.com/package/@umbraco-forms/backoffice). +{% endhint %} + +```bash +npm install -D @umbraco-forms/backoffice@x.x.x +``` + +This will add a package to your devDependencies containing the TypeScript definitions for Umbraco Forms. + To display a name and description on a custom field, you need to register a JavaScript file as shown in the [Localization](https://app.gitbook.com/s/7MBVdnTbFiAgWuRsHpNS/customizing/extending-overview/extension-types/localization) article. ### Field Preview @@ -181,29 +193,24 @@ The alias of the preview to use is defined on the field type via the `PreviewVie A preview for our slider, representing the selected setting values could look as follows: ```javascript -import { UmbElementMixin } from "@umbraco-cms/backoffice/element-api"; import { - LitElement, css, customElement, html, property, } from "@umbraco-cms/backoffice/external/lit"; +import { FormsFieldPreviewBaseElement } from "@umbraco-forms/backoffice"; const elementName = "my-field-preview-slider"; @customElement(elementName) -export class MyFieldPreviewSliderElement extends UmbElementMixin(LitElement) { +export class MyFieldPreviewSliderElement extends FormsFieldPreviewBaseElement { @property() settings = {}; @property({ type: Array }) prevalues = []; - getSettingValue(key: string) { - return this.settings[key]; - } - render() { return html`
import('./slider-preview.element.js') - }; +const sliderPreviewManifest: ManifestFormsFieldPreview = { + type: "formsFieldPreview", + alias: "My.FieldPreview.Slider", + name: "Forms UUI Slider Field Preview", + element: MyFieldPreviewSliderElement +}; - export const manifests = [sliderPreviewManifest]; +export const manifests = [sliderPreviewManifest]; ``` ### Field Editor @@ -403,20 +410,23 @@ The following code shows the structure for these converter elements. ```javascript import type { UmbPropertyValueData } from "@umbraco-cms/backoffice/property"; +import type { FormsSettingValueConverterApi, Setting } from "@umbraco-forms/backoffice"; -export class SliderSettingValueConverter { - - async getSettingValueForEditor(setting, alias: string, value: string) { +export class SliderSettingValueConverter + implements FormsSettingValueConverterApi { + async getSettingValueForEditor(setting: Setting, alias: string, value: string) { return Promise.resolve(value); } - async getSettingValueForPersistence(setting, valueData: UmbPropertyValueData) { - return Promise.resolve(valueData.value); + async getSettingValueForPersistence(setting: Setting, valueData: UmbPropertyValueData) { + return Promise.resolve(valueData.value?.toString() || ""); } - async getSettingPropertyConfig(setting, alias: string, values: UmbPropertyValueData[]) { + async getSettingPropertyConfig(setting: Setting, alias: string, values: UmbPropertyValueData[]) { return Promise.resolve([]); } + + destroy(): void { } } ``` @@ -424,8 +434,9 @@ It's registered as follows. The `propertyEditorUiAlias` matches with the propert ```javascript import { SliderSettingValueConverter } from "./slider-setting-value-converter.api"; +import { ManifestFormsSettingValueConverterPreview } from "@umbraco-forms/backoffice"; -const sliderValueConverterManifest = { +const sliderValueConverterManifest: ManifestFormsSettingValueConverterPreview = { type: "formsSettingValueConverter", alias: "My.SettingValueConverter.Slider", name: "Slider Value Converter", diff --git a/17/umbraco-forms/release-notes.md b/17/umbraco-forms/release-notes.md index a441caae57d..81966316cc1 100644 --- a/17/umbraco-forms/release-notes.md +++ b/17/umbraco-forms/release-notes.md @@ -16,6 +16,14 @@ If you are upgrading to a new major version, you can find information about the This section contains the release notes for Umbraco Forms 17 including all changes for this version. +### 17.0.0-rc2 (November 13th 2025) + +* Update dependencies to 17.0.0-rc2 + +### 17.0.0-rc1 (October 30th 2025) + +* Update dependencies to 17.0.0-rc1 + ## Legacy release notes You can find the release notes for versions out of support in the [Legacy documentation on GitHub](https://github.com/umbraco/UmbracoDocs/blob/umbraco-eol-versions/12/umbraco-forms/release-notes.md) and [Umbraco Forms Package page](https://our.umbraco.com/packages/developer-tools/umbraco-forms/).