From 4eead9d6e43b583c49626ce30ff62df809948cf0 Mon Sep 17 00:00:00 2001 From: Mads Rasmussen Date: Wed, 6 May 2026 21:03:17 +0200 Subject: [PATCH 01/21] Add Table Collection View docs and TOC --- 17/umbraco-cms/SUMMARY.md | 1 + .../collections/collection-view/README.md | 1 + .../collections/collection-view/table.md | 65 +++++++++++++++++++ 3 files changed, 67 insertions(+) create mode 100644 17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/table.md diff --git a/17/umbraco-cms/SUMMARY.md b/17/umbraco-cms/SUMMARY.md index 3c129ac1fca..70550ffecfd 100644 --- a/17/umbraco-cms/SUMMARY.md +++ b/17/umbraco-cms/SUMMARY.md @@ -204,6 +204,7 @@ * [Workspace Views](customizing/extending-overview/extension-types/workspaces/workspace-views.md) * [Collections](customizing/extending-overview/extension-types/collections/README.md) * [Collection View](customizing/extending-overview/extension-types/collections/collection-view/README.md) + * [Table View](customizing/extending-overview/extension-types/collections/collection-view/table.md) * [Card View](customizing/extending-overview/extension-types/collections/collection-view/card.md) * [Reference View](customizing/extending-overview/extension-types/collections/collection-view/reference.md) * [Custom View](customizing/extending-overview/extension-types/collections/collection-view/custom.md) diff --git a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/README.md b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/README.md index a331e2520ca..b2c65f546fd 100644 --- a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/README.md +++ b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/README.md @@ -18,6 +18,7 @@ Before creating a Collection View, make sure you are familiar with the [Extensio There are a couple of built-in Collection Views Kinds available in Umbraco, each suited for different display needs. You can also create custom Collection Views if the built-in options do not meet your requirements. +- **[Table View](table.md)**: Displays entities in a table layout with configurable columns. - **[Card View](card.md)**: Displays entities as cards in a grid layout, suitable for visual content. - **[Reference View](reference.md)**: Displays entities in a list-style layout. - **[Custom View](custom.md)**: Create your own Collection View from scratch to meet specific requirements. diff --git a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/table.md b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/table.md new file mode 100644 index 00000000000..850aaae887c --- /dev/null +++ b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/table.md @@ -0,0 +1,65 @@ +# Table Collection View + +When you want to display entities in a tabular layout within a collection, use the Table Collection View Kind. This will render a table layout without requiring a custom element — you only need to define which columns to show in the manifest. + +The default Collection Item Model used in a Table Collection View is based on the following interface: + +```typescript +export interface UmbCollectionItemModel { + unique: string; + entityType: string; + name?: string; + icon?: string; +} +``` + +If your collection exposes additional fields, extend the base model with your own interface: + +```typescript +export interface MyCollectionItemModel extends UmbCollectionItemModel { + status: string; + creator: string; +} +``` + +The table kind always renders the following columns automatically: + +| Column | Description | +|---|---| +| **Name** | Always the first column. Renders the item icon and name. | +| **Description** | Rendered only when at least one item in the collection has a description. | +| _(manifest columns)_ | Any columns defined in `meta.columns`, inserted after Name/Description. Values are rendered as strings. | +| **[Entity Actions](../entity-actions.md)** | Always the last column. Right-aligned; renders the item's context menu. | + +Register the Table Collection View in the extension registry with the kind set to "table": + +## Manifest + +{% code title="umbraco-package.json" %} +```json +{ + "type": "collectionView", + "kind": "table", + "alias": "My.CollectionView.Table", + "name": "My Table Collection View", + "meta": { + "columns": [ + { + "label": "Status", + "field": "status" + }, + { + "label": "Creator", + "field": "creator" + } + ] + }, + "conditions": [ + { + "alias": "Umb.Condition.CollectionAlias", + "match": "My.Collection" // Collection alias to display this collection view for + } + ] +} +``` +{% endcode %} From e7b1dee8947d3a7a2890227022dfe3fa4b14d207 Mon Sep 17 00:00:00 2001 From: Mads Rasmussen Date: Wed, 6 May 2026 21:37:55 +0200 Subject: [PATCH 02/21] change custom view implementation from table to a simpler example --- .../collections/collection-view/custom.md | 150 +++++------------- 1 file changed, 39 insertions(+), 111 deletions(-) diff --git a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/custom.md b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/custom.md index d051ec19722..36a14f6ab39 100644 --- a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/custom.md +++ b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/custom.md @@ -8,18 +8,18 @@ When the existing Collection View kinds do not meet your requirements, you can c ```json { "type": "collectionView", - "alias": "My.CollectionView.Alias", - "name": "My Collection View", + "alias": "My.CollectionView.Custom", + "name": "My Custom Collection View", "element": "/App_Plugins/my-collection-view/my-collection-view.js", "meta": { - "label": "Table", + "label": "My View", "icon": "icon-list", - "pathName": "table" + "pathName": "my-view" }, "conditions": [ { "alias": "Umb.Condition.CollectionAlias", - "match": "Umb.Collection.Document" // Collection alias to display this collection view for + "match": "My.Collection" // Collection alias to display this collection view for } ] } @@ -28,127 +28,55 @@ When the existing Collection View kinds do not meet your requirements, you can c ## Implementation -Implement your Collection View as a Lit element that extends `UmbLitElement`. -This defines how a list of entities is rendered in your collection. +Implement your Collection View as a Lit element that extends `UmbCollectionViewElementBase`. The base class provides the collection items via `_items`, handles selection state, and exposes helper methods such as `_selectItem`, `_deselectItem`, and `_isSelectableItem`. Override `render()` to define how the collection is displayed. {% code title="my-collection-view.ts" %} ```typescript -import { css, customElement, html, state } from '@umbraco-cms/backoffice/external/lit'; -import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element'; -import { UMB_DOCUMENT_COLLECTION_CONTEXT } from '@umbraco-cms/backoffice/document'; -import type { UmbDocumentCollectionItemModel } from '@umbraco-cms/backoffice/document'; -import type { UmbCollectionColumnConfiguration } from '@umbraco-cms/backoffice/collection'; +import { customElement, html, nothing } from '@umbraco-cms/backoffice/external/lit'; +import { UmbCollectionViewElementBase } from '@umbraco-cms/backoffice/collection'; +import type { UmbCollectionItemModel } from '@umbraco-cms/backoffice/collection'; -@customElement('my-document-table-collection-view') -export class MyDocumentTableCollectionViewElement extends UmbLitElement { +@customElement('my-collection-view') +export class MyCollectionViewElement extends UmbCollectionViewElementBase { - @state() private _columns: Array<{ name: string; alias: string; align?: string }> = []; - @state() private _items?: Array = []; - - constructor() { - super(); - - this.consumeContext(UMB_DOCUMENT_COLLECTION_CONTEXT, (collectionContext) => { - collectionContext?.setupView(this); - - this.observe(collectionContext?.userDefinedProperties, (props) => { - this.#createColumns(props); - }); - - this.observe(collectionContext?.items, (items) => { - this._items = items; - }); - }); + override render() { + if (this._loading) return nothing; + return html` +
    + ${this._items.map((item) => this.#renderItem(item))} +
+ `; } - #createColumns(userProps: Array = []) { - const baseCols = [ - { name: 'Name', alias: 'name' }, - { name: 'State', alias: 'state' }, - ]; - const userCols = userProps.map((p) => ({ - name: p.nameTemplate ?? p.alias, - alias: p.alias, - })); - this._columns = [...baseCols, ...userCols, { name: '', alias: 'entityActions', align: 'right' }]; - } + #renderItem(item: UmbCollectionItemModel) { + const href = item.unique ? this._itemHrefs.get(item.unique) : undefined; + const selectable = this._isSelectableItem(item); + const selected = this._isSelectedItem(item.unique); - override render() { - if (this._items === undefined) return html`

Not found...

`; return html` - - - - ${this._columns.map((col) => html``)} - - - - ${this._items.map( - (item) => html` - - ${this._columns.map((col) => { - switch (col.alias) { - case 'name': - return html``; - case 'state': - return html``; - case 'sortOrder': - return html``; - case 'updateDate': - return html`` - case 'creator': - return html``; - case 'entityActions': - return html``; - default: - const val = item.values.find((v) => v.alias === col.alias)?.value ?? ''; - return html``; - } - })} - - ` - )} - -
${col.name}
${item.name}${item.state}${item.sortOrder}${item.updateDate}${item.creator}⋮${val}
+
  • + ${selectable + ? html` selected + ? this._deselectItem(item.unique) + : this._selectItem(item.unique)}/>` + : nothing} + ${href && !this._selectOnly + ? html`${item.name}` + : html`${item.name}`} + +
    • `; } - - static override styles = css` - :host { - display: block; - width: 100%; - overflow-x: auto; - font-family: sans-serif; - } - table { - width: 100%; - border-collapse: collapse; - } - th, - td { - padding: 6px 10px; - border: 1px solid #ddd; - white-space: nowrap; - } - th { - background: #f8f8f8; - font-weight: 600; - } - a { - color: var(--uui-color-interactive, #0366d6); - text-decoration: none; - } - a:hover { - text-decoration: underline; - } - `; } -export default MyDocumentTableCollectionViewElement; +export { MyCollectionViewElement as element }; declare global { interface HTMLElementTagNameMap { - 'my-document-table-collection-view': MyDocumentTableCollectionViewElement; + 'my-collection-view': MyCollectionViewElement; } } ``` @@ -159,7 +87,7 @@ declare global { Use the `match` property in your manifest to target a specific collection type. | **Match Value** | **Description** | -|------------------|-----------------| +|---|---| | `Umb.Collection.Document` | Targets the **Document** collection (content items). | | `Umb.Collection.Media` | Targets the **Media** collection (images, videos, files). | | `Umb.Collection.Member` | Targets the **Member** collection. | From f43a2dd5d149c1ee37a0bbcb61992b45444d5ebd Mon Sep 17 00:00:00 2001 From: Mads Rasmussen Date: Wed, 6 May 2026 21:46:43 +0200 Subject: [PATCH 03/21] Update table.md --- .../extension-types/collections/collection-view/table.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/table.md b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/table.md index 850aaae887c..4ee5383d92e 100644 --- a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/table.md +++ b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/table.md @@ -29,7 +29,7 @@ The table kind always renders the following columns automatically: | **Name** | Always the first column. Renders the item icon and name. | | **Description** | Rendered only when at least one item in the collection has a description. | | _(manifest columns)_ | Any columns defined in `meta.columns`, inserted after Name/Description. Values are rendered as strings. | -| **[Entity Actions](../entity-actions.md)** | Always the last column. Right-aligned; renders the item's context menu. | +| **[Entity Actions](../../entity-actions.md)** | Always the last column. Right-aligned; renders the item's context menu. | Register the Table Collection View in the extension registry with the kind set to "table": From 357dcd5b64eafe26c4431ddacff4a48de0b5b419 Mon Sep 17 00:00:00 2001 From: Mads Rasmussen Date: Thu, 7 May 2026 11:05:27 +0200 Subject: [PATCH 04/21] Add Collection docs and update collections overview --- 17/umbraco-cms/SUMMARY.md | 1 + .../extension-types/collections/README.md | 24 +++- .../collections/collection-view/table.md | 12 +- .../extension-types/collections/collection.md | 118 ++++++++++++++++++ 4 files changed, 149 insertions(+), 6 deletions(-) diff --git a/17/umbraco-cms/SUMMARY.md b/17/umbraco-cms/SUMMARY.md index 70550ffecfd..d0429c0da85 100644 --- a/17/umbraco-cms/SUMMARY.md +++ b/17/umbraco-cms/SUMMARY.md @@ -203,6 +203,7 @@ * [Workspace Footer Apps](customizing/extending-overview/extension-types/workspaces/workspace-footer-apps.md) * [Workspace Views](customizing/extending-overview/extension-types/workspaces/workspace-views.md) * [Collections](customizing/extending-overview/extension-types/collections/README.md) + * [Collection](customizing/extending-overview/extension-types/collections/collection.md) * [Collection View](customizing/extending-overview/extension-types/collections/collection-view/README.md) * [Table View](customizing/extending-overview/extension-types/collections/collection-view/table.md) * [Card View](customizing/extending-overview/extension-types/collections/collection-view/card.md) diff --git a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/README.md b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/README.md index 323c657fb09..6d177160acc 100644 --- a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/README.md +++ b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/README.md @@ -1,6 +1,26 @@ --- description: >- - An overview of the available extension types related to collections. + Learn how to register a Collection extension, connect it to a Collection Repository and configure Collection Views to display entity lists. --- -# Extension Types: Collections +# Collections + +A Collection is an extension that fetches and exposes a list of entities in the Umbraco backoffice. It connects a **Collection Repository**, for fetching data, and to one or more **Collection Views** (the display layer). + +The Collection itself does not render anything. It manages pagination, filtering, and selection state — the Collection Views decide how items are presented. + +## How the parts relate + +| Part | Role | +|---|---| +| **Collection** | Registers the extension and points to a repository alias | +| **Collection Repository** | Implements `requestCollection` to fetch and return items | +| **Collection View** | Bound to the collection via its alias; renders the items | + +A Collection View uses the `Umb.Condition.CollectionAlias` condition to attach itself to a specific collection. This means you can register multiple views (table, card, reference) for the same collection alias, and the backoffice will offer them as view options. + +## Articles + +* [Collection](collection.md) +* [Collection View](collection-view/README.md) +* [Collection Action](collection-action.md) diff --git a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/table.md b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/table.md index 4ee5383d92e..a06d51f1651 100644 --- a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/table.md +++ b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/table.md @@ -1,8 +1,10 @@ # Table Collection View -When you want to display entities in a tabular layout within a collection, use the Table Collection View Kind. This will render a table layout without requiring a custom element — you only need to define which columns to show in the manifest. +The Table Collection View renders items produced by an active [Collection](../collection.md). The collection is responsible for fetching items through its [Collection Repository](../collection.md#collection-repository). -The default Collection Item Model used in a Table Collection View is based on the following interface: +When you want to display entities in a tabular layout within a collection, use the Table Collection View Kind. The table renders without a custom element — you only need to define which columns to show in the manifest. + +The base Collection Item Model that all items must satisfy is: ```typescript export interface UmbCollectionItemModel { @@ -13,7 +15,7 @@ export interface UmbCollectionItemModel { } ``` -If your collection exposes additional fields, extend the base model with your own interface: +If your collection's repository returns additional fields, extend the base model with your own interface. This interface documents the contract between the repository output and the column definitions. ```typescript export interface MyCollectionItemModel extends UmbCollectionItemModel { @@ -22,6 +24,8 @@ export interface MyCollectionItemModel extends UmbCollectionItemModel { } ``` +Define this interface alongside your repository. For a full example of a repository that populates these fields, see [Collection](../collection.md). + The table kind always renders the following columns automatically: | Column | Description | @@ -29,7 +33,7 @@ The table kind always renders the following columns automatically: | **Name** | Always the first column. Renders the item icon and name. | | **Description** | Rendered only when at least one item in the collection has a description. | | _(manifest columns)_ | Any columns defined in `meta.columns`, inserted after Name/Description. Values are rendered as strings. | -| **[Entity Actions](../../entity-actions.md)** | Always the last column. Right-aligned; renders the item's context menu. | +| **[Entity Actions](../../entity-actions.md)** | Renders the item's Entity Actions menu. | Register the Table Collection View in the extension registry with the kind set to "table": diff --git a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection.md b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection.md index e69de29bb2d..8bbd778c7b2 100644 --- a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection.md +++ b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection.md @@ -0,0 +1,118 @@ +--- +description: >- + Learn how to register a Collection extension and implement a Collection + Repository to provide data for Collection Views. +--- + +# Collection + +A Collection is an extension type that registers under a unique alias and uses a **Collection Repository** to fetch items. **Collection Views** bind themselves to the collection via that alias to display the items. + +## Manifest + +Register a collection using the `collection` extension type. The `repositoryAlias` in `meta` must match the alias of a registered Collection Repository. + +{% code title="umbraco-package.json" %} +```json +{ + "type": "collection", + "kind": "default", + "alias": "My.Collection", + "name": "My Collection", + "meta": { + "repositoryAlias": "My.Collection.Repository" + } +} +``` +{% endcode %} + +## Collection Repository + +A Collection Repository fetches and returns the items displayed in the collection. It must implement the `UmbCollectionRepository` interface, which requires a single `requestCollection` method. + +### Manifest + +Register the repository as a separate extension. The `api` property points to the file that exports the repository class: + +{% code title="umbraco-package.json" %} +```json +{ + "type": "repository", + "alias": "My.Collection.Repository", + "name": "My Collection Repository", + "api": "/App_Plugins/my-collection/my-collection.repository.js" +} +``` +{% endcode %} + +### Item model + +Define the shape of the items your repository returns by extending `UmbCollectionItemModel`. The property names you add here are what Collection Views use when rendering the items. + +{% code title="types.ts" %} +```typescript +import type { UmbCollectionItemModel } from '@umbraco-cms/backoffice/collection'; + +export interface MyCollectionItemModel extends UmbCollectionItemModel { + status: string; + creator: string; +} +``` +{% endcode %} + +### Implementation + +Extend `UmbRepositoryBase` and implement `UmbCollectionRepository`. The `requestCollection` method receives a filter object with `skip` and `take` for pagination, and must return `{ data: { items, total } }`. For guidance on making HTTP requests to a server API, see [Fetching Data](../../../../foundation/fetching-data/README.md): + +{% code title="my-collection.repository.ts" %} +```typescript +import type { MyCollectionItemModel } from './types.js'; +import { UmbRepositoryBase } from '@umbraco-cms/backoffice/repository'; +import type { UmbCollectionRepository, UmbCollectionFilterModel } from '@umbraco-cms/backoffice/collection'; + +export class MyCollectionRepository + extends UmbRepositoryBase + implements UmbCollectionRepository +{ + async requestCollection(filter: UmbCollectionFilterModel) { + const skip = filter.skip ?? 0; + const take = filter.take ?? 10; + + // Replace this with a real API call. + const allItems: MyCollectionItemModel[] = [ + { + unique: 'b3e31e9c-7d66-4c99-a9e5-d9f2b1e2b22f', + entityType: 'my-entity', + name: 'Item One', + status: 'Published', + creator: 'Admin', + }, + { + unique: 'ac9b6e24-4b11-4dd6-8d4e-7c4f70e59f3c', + entityType: 'my-entity', + name: 'Item Two', + status: 'Draft', + creator: 'Editor', + }, + ]; + + const items = allItems.slice(skip, skip + take); + + return { + data: { + items, + total: allItems.length, + }, + }; + } +} + +export { MyCollectionRepository as api }; +``` +{% endcode %} + +The exported `api` alias lets the extension registry instantiate the class when the collection loads. + +## Next steps + +With a collection and repository registered, add a [Collection View](collection-view/README.md) to control how the items are displayed. Each view binds to your collection via its alias using the `Umb.Condition.CollectionAlias` condition. From 56aa80596164cad478c6d6a3aa0e7fb4b33989c5 Mon Sep 17 00:00:00 2001 From: Mads Rasmussen Date: Thu, 7 May 2026 12:41:46 +0200 Subject: [PATCH 05/21] Update README.md --- .../extending-overview/extension-types/collections/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/README.md b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/README.md index 6d177160acc..2c49d212ef5 100644 --- a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/README.md +++ b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/README.md @@ -5,7 +5,7 @@ description: >- # Collections -A Collection is an extension that fetches and exposes a list of entities in the Umbraco backoffice. It connects a **Collection Repository**, for fetching data, and to one or more **Collection Views** (the display layer). +A Collection is an extension that fetches and exposes a list of entities in the Umbraco backoffice. It connects a **Collection Repository**, for fetching data, and one or more **Collection Views** (the display layer). The Collection itself does not render anything. It manages pagination, filtering, and selection state — the Collection Views decide how items are presented. From 14f4080cb523d3c145a1a94cfc9a521bbe21380d Mon Sep 17 00:00:00 2001 From: Mads Rasmussen Date: Thu, 7 May 2026 12:43:13 +0200 Subject: [PATCH 06/21] Update README.md --- .../extending-overview/extension-types/collections/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/README.md b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/README.md index 2c49d212ef5..395418c4021 100644 --- a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/README.md +++ b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/README.md @@ -14,7 +14,7 @@ The Collection itself does not render anything. It manages pagination, filtering | Part | Role | |---|---| | **Collection** | Registers the extension and points to a repository alias | -| **Collection Repository** | Implements `requestCollection` to fetch and return items | +| **Collection Repository** | Fetches and returns items | | **Collection View** | Bound to the collection via its alias; renders the items | A Collection View uses the `Umb.Condition.CollectionAlias` condition to attach itself to a specific collection. This means you can register multiple views (table, card, reference) for the same collection alias, and the backoffice will offer them as view options. From 5cd77b4572a3408c31d42c97d4eb1efa04d6050d Mon Sep 17 00:00:00 2001 From: Mads Rasmussen Date: Thu, 7 May 2026 12:47:33 +0200 Subject: [PATCH 07/21] Add UmbCollectionItemModel to docs --- .../extension-types/collections/collection.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection.md b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection.md index 8bbd778c7b2..7b37183255d 100644 --- a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection.md +++ b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection.md @@ -49,6 +49,17 @@ Register the repository as a separate extension. The `api` property points to th Define the shape of the items your repository returns by extending `UmbCollectionItemModel`. The property names you add here are what Collection Views use when rendering the items. +The base Collection Item Model that all items must satisfy is: + +```typescript +export interface UmbCollectionItemModel { + unique: string; + entityType: string; + name?: string; + icon?: string; +} +``` + {% code title="types.ts" %} ```typescript import type { UmbCollectionItemModel } from '@umbraco-cms/backoffice/collection'; From c218b9632b1a8f91358506795ccdd9aa06e08912 Mon Sep 17 00:00:00 2001 From: Mads Rasmussen Date: Thu, 7 May 2026 12:55:55 +0200 Subject: [PATCH 08/21] remove redundant information --- .../extension-types/collections/collection.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection.md b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection.md index 7b37183255d..4141c91a275 100644 --- a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection.md +++ b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection.md @@ -126,4 +126,4 @@ The exported `api` alias lets the extension registry instantiate the class when ## Next steps -With a collection and repository registered, add a [Collection View](collection-view/README.md) to control how the items are displayed. Each view binds to your collection via its alias using the `Umb.Condition.CollectionAlias` condition. +With a collection and repository registered, add a [Collection View](collection-view/README.md) to control how the items are displayed. From be68979a9b064ba82833c67ca8f1d4187944a9d5 Mon Sep 17 00:00:00 2001 From: Mads Rasmussen Date: Thu, 7 May 2026 13:13:55 +0200 Subject: [PATCH 09/21] remove redundant information --- .../collections/collection-view/table.md | 22 +------------------ 1 file changed, 1 insertion(+), 21 deletions(-) diff --git a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/table.md b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/table.md index a06d51f1651..774bfd76936 100644 --- a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/table.md +++ b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/table.md @@ -4,27 +4,7 @@ The Table Collection View renders items produced by an active [Collection](../co When you want to display entities in a tabular layout within a collection, use the Table Collection View Kind. The table renders without a custom element — you only need to define which columns to show in the manifest. -The base Collection Item Model that all items must satisfy is: - -```typescript -export interface UmbCollectionItemModel { - unique: string; - entityType: string; - name?: string; - icon?: string; -} -``` - -If your collection's repository returns additional fields, extend the base model with your own interface. This interface documents the contract between the repository output and the column definitions. - -```typescript -export interface MyCollectionItemModel extends UmbCollectionItemModel { - status: string; - creator: string; -} -``` - -Define this interface alongside your repository. For a full example of a repository that populates these fields, see [Collection](../collection.md). +The columns defined in `meta.columns` map to fields on your collection item model. In the example below, `status` and `creator` map to fields on `MyCollectionItemModel`. For details on defining the item model, see [Collection](../collection.md#item-model). The table kind always renders the following columns automatically: From 05a0f57197c5c841cb481957ea904aeba5c65675 Mon Sep 17 00:00:00 2001 From: Mads Rasmussen Date: Thu, 7 May 2026 13:19:37 +0200 Subject: [PATCH 10/21] Update table.md --- .../extension-types/collections/collection-view/table.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/table.md b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/table.md index 774bfd76936..342ba00a9ac 100644 --- a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/table.md +++ b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/table.md @@ -1,6 +1,6 @@ # Table Collection View -The Table Collection View renders items produced by an active [Collection](../collection.md). The collection is responsible for fetching items through its [Collection Repository](../collection.md#collection-repository). +The Table Collection View renders items produced by a [Collection](../collection.md). The collection is responsible for fetching items through its [Collection Repository](../collection.md#collection-repository). When you want to display entities in a tabular layout within a collection, use the Table Collection View Kind. The table renders without a custom element — you only need to define which columns to show in the manifest. From 52ea400f42e75c3d9fcdea57448bc9de8911773e Mon Sep 17 00:00:00 2001 From: Mads Rasmussen Date: Thu, 7 May 2026 13:26:31 +0200 Subject: [PATCH 11/21] Clarify collection-view docs and model refs --- .../collections/collection-view/card.md | 13 +++---------- .../collections/collection-view/custom.md | 2 ++ .../collections/collection-view/reference.md | 13 +++---------- 3 files changed, 8 insertions(+), 20 deletions(-) diff --git a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/card.md b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/card.md index 4ccf3160f37..16edc83fe20 100644 --- a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/card.md +++ b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/card.md @@ -1,17 +1,10 @@ # Card Collection View -When you want to display entities as cards within a collection, use the Card Collection View Kind. This will render a card-style grid layout. Each card renders a default layout with the entity's name and icon. You can further customize the card layout by registering a custom card collection item as needed. +The Card Collection View renders items produced by a [Collection](../collection.md). The collection is responsible for fetching items through its [Collection Repository](../collection.md#collection-repository). -The default Collection Item Model used in a Card Collection View is based on the following interface: +When you want to display entities as cards within a collection, use the Card Collection View Kind. This will render a card-style grid layout. Each card renders a default layout with the entity's name and icon. You can further customize the card layout by registering a custom card collection item as needed. -```typescript -export interface UmbCollectionItemModel { - unique: string; - entityType: string; - name?: string; - icon?: string; -} -``` +Each card renders fields from your collection item model. For details on defining and extending the item model, see [Collection](../collection.md#item-model). Register the Card Collection View in the extension registry with the kind set to "card": diff --git a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/custom.md b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/custom.md index 36a14f6ab39..644810c96ed 100644 --- a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/custom.md +++ b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/custom.md @@ -1,5 +1,7 @@ # Custom Collection View +A Custom Collection View renders items produced by a [Collection](../collection.md). The collection is responsible for fetching items through its [Collection Repository](../collection.md#collection-repository). + When the existing Collection View kinds do not meet your requirements, you can create a custom Collection View from scratch. ## Manifest diff --git a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/reference.md b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/reference.md index 2e23c0aeef6..ac0a1e7dc9f 100644 --- a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/reference.md +++ b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/reference.md @@ -1,17 +1,10 @@ # Reference Collection View -When you want to display entities as a list of references within a collection, use the Reference Collection View Kind. This will render a basic list layout. Each item renders a default layout with the entity's name and icon. You can further customize the item layout by registering a custom Ref Collection Item when needed. +The Reference Collection View renders items produced by a [Collection](../collection.md). The collection is responsible for fetching items through its [Collection Repository](../collection.md#collection-repository). -The default Collection Item Model used in a Reference Collection View is based on the following interface: +When you want to display entities as a list of references within a collection, use the Reference Collection View Kind. This will render a basic list layout. Each item renders a default layout with the entity's name and icon. You can further customize the item layout by registering a custom Ref Collection Item when needed. -```typescript -export interface UmbCollectionItemModel { - unique: string; - entityType: string; - name?: string; - icon?: string; -} -``` +Each item renders fields from your collection item model. For details on defining and extending the item model, see [Collection](../collection.md#item-model). Register the Reference Collection View in the extension registry with the kind set to "ref": From 4223956941d6635d1a86f1c73805aa80801b4f26 Mon Sep 17 00:00:00 2001 From: Mads Rasmussen Date: Thu, 7 May 2026 13:50:37 +0200 Subject: [PATCH 12/21] change flow --- .../extension-types/collections/collection-view/card.md | 4 ++-- .../extension-types/collections/collection-view/custom.md | 4 ++-- .../extension-types/collections/collection-view/reference.md | 4 ++-- .../extension-types/collections/collection-view/table.md | 4 ++-- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/card.md b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/card.md index 16edc83fe20..f364b3e3afc 100644 --- a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/card.md +++ b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/card.md @@ -1,9 +1,9 @@ # Card Collection View -The Card Collection View renders items produced by a [Collection](../collection.md). The collection is responsible for fetching items through its [Collection Repository](../collection.md#collection-repository). - When you want to display entities as cards within a collection, use the Card Collection View Kind. This will render a card-style grid layout. Each card renders a default layout with the entity's name and icon. You can further customize the card layout by registering a custom card collection item as needed. +The Card Collection View renders items produced by a [Collection](../collection.md). The collection is responsible for fetching items through its [Collection Repository](../collection.md#collection-repository). + Each card renders fields from your collection item model. For details on defining and extending the item model, see [Collection](../collection.md#item-model). Register the Card Collection View in the extension registry with the kind set to "card": diff --git a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/custom.md b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/custom.md index 644810c96ed..2ba3e64aca5 100644 --- a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/custom.md +++ b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/custom.md @@ -1,9 +1,9 @@ # Custom Collection View -A Custom Collection View renders items produced by a [Collection](../collection.md). The collection is responsible for fetching items through its [Collection Repository](../collection.md#collection-repository). - When the existing Collection View kinds do not meet your requirements, you can create a custom Collection View from scratch. +A Custom Collection View renders items produced by a [Collection](../collection.md). The collection is responsible for fetching items through its [Collection Repository](../collection.md#collection-repository). + ## Manifest {% code title="umbraco-package.json" %} diff --git a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/reference.md b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/reference.md index ac0a1e7dc9f..dc5b2267f11 100644 --- a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/reference.md +++ b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/reference.md @@ -1,9 +1,9 @@ # Reference Collection View -The Reference Collection View renders items produced by a [Collection](../collection.md). The collection is responsible for fetching items through its [Collection Repository](../collection.md#collection-repository). - When you want to display entities as a list of references within a collection, use the Reference Collection View Kind. This will render a basic list layout. Each item renders a default layout with the entity's name and icon. You can further customize the item layout by registering a custom Ref Collection Item when needed. +The Reference Collection View renders items produced by a [Collection](../collection.md). The collection is responsible for fetching items through its [Collection Repository](../collection.md#collection-repository). + Each item renders fields from your collection item model. For details on defining and extending the item model, see [Collection](../collection.md#item-model). Register the Reference Collection View in the extension registry with the kind set to "ref": diff --git a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/table.md b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/table.md index 342ba00a9ac..93bf3adf55f 100644 --- a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/table.md +++ b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/table.md @@ -1,9 +1,9 @@ # Table Collection View -The Table Collection View renders items produced by a [Collection](../collection.md). The collection is responsible for fetching items through its [Collection Repository](../collection.md#collection-repository). - When you want to display entities in a tabular layout within a collection, use the Table Collection View Kind. The table renders without a custom element — you only need to define which columns to show in the manifest. +The Table Collection View renders items produced by a [Collection](../collection.md). The collection is responsible for fetching items through its [Collection Repository](../collection.md#collection-repository). + The columns defined in `meta.columns` map to fields on your collection item model. In the example below, `status` and `creator` map to fields on `MyCollectionItemModel`. For details on defining the item model, see [Collection](../collection.md#item-model). The table kind always renders the following columns automatically: From 5f55cfcc8dd8d4979195fb3041796b0ef94b22d9 Mon Sep 17 00:00:00 2001 From: Mads Rasmussen Date: Thu, 7 May 2026 20:18:52 +0200 Subject: [PATCH 13/21] Split collection view into view and item elements --- .../collections/collection-view/custom.md | 112 +++++++++++++++--- 1 file changed, 93 insertions(+), 19 deletions(-) diff --git a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/custom.md b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/custom.md index 2ba3e64aca5..f316e68a697 100644 --- a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/custom.md +++ b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/custom.md @@ -30,13 +30,16 @@ A Custom Collection View renders items produced by a [Collection](../collection. ## Implementation -Implement your Collection View as a Lit element that extends `UmbCollectionViewElementBase`. The base class provides the collection items via `_items`, handles selection state, and exposes helper methods such as `_selectItem`, `_deselectItem`, and `_isSelectableItem`. Override `render()` to define how the collection is displayed. +Implement the Collection View as a Lit element that extends `UmbCollectionViewElementBase`. The base class provides the collection items via `_items`, handles selection state, and exposes helper methods such as `_isSelectableItem` and `_isSelectedItem`. Override `render()` to define how the collection is displayed. + +Split the view into two elements: a view element that handles the layout and delegates item rendering to a dedicated item element. {% code title="my-collection-view.ts" %} ```typescript import { customElement, html, nothing } from '@umbraco-cms/backoffice/external/lit'; import { UmbCollectionViewElementBase } from '@umbraco-cms/backoffice/collection'; import type { UmbCollectionItemModel } from '@umbraco-cms/backoffice/collection'; +import './my-collection-view-item.element.js'; @customElement('my-collection-view') export class MyCollectionViewElement extends UmbCollectionViewElementBase { @@ -44,41 +47,112 @@ export class MyCollectionViewElement extends UmbCollectionViewElementBase { override render() { if (this._loading) return nothing; return html` -
      +
      ${this._items.map((item) => this.#renderItem(item))} -
    + `; } #renderItem(item: UmbCollectionItemModel) { - const href = item.unique ? this._itemHrefs.get(item.unique) : undefined; - const selectable = this._isSelectableItem(item); - const selected = this._isSelectedItem(item.unique); + return html` + this._selectItem(item.unique)} + @deselected=${() => this._deselectItem(item.unique)}> + + `; + } +} + +export { MyCollectionViewElement as element }; + +declare global { + interface HTMLElementTagNameMap { + 'my-collection-view': MyCollectionViewElement; + } +} +``` +{% endcode %} + +The item element receives the item model as a property and dispatches `UmbSelectedEvent` and `UmbDeselectedEvent` when the user interacts with the selection control. The base class on the parent view handles these events automatically. + +{% code title="my-collection-view-item.element.ts" %} +```typescript +import { UmbDeselectedEvent, UmbSelectedEvent } from '@umbraco-cms/backoffice/event'; +import { customElement, html, nothing, property } from '@umbraco-cms/backoffice/external/lit'; +import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element'; +import { UmbEntityContext } from '@umbraco-cms/backoffice/entity'; +import type { UmbCollectionItemModel } from '@umbraco-cms/backoffice/collection'; + +@customElement('my-collection-view-item') +export class MyCollectionViewItemElement extends UmbLitElement { + + #item?: UmbCollectionItemModel; + #entityContext?: UmbEntityContext; + + @property({ type: Object }) + get item(): UmbCollectionItemModel | undefined { + return this.#item; + } + set item(value: UmbCollectionItemModel | undefined) { + const oldValue = this.#item; + this.#item = value; + if (value) { + this.#entityContext = new UmbEntityContext(this); + this.#entityContext.setEntityType(value.entityType); + this.#entityContext.setUnique(value.unique); + } else { + this.#entityContext?.destroy(); + this.#entityContext = undefined; + } + this.requestUpdate('item', oldValue); + } + + @property({ type: Boolean }) + selectable = false; + + @property({ type: Boolean }) + selected = false; + + @property({ type: String }) + href?: string; + + override render() { + if (!this.item) return nothing; return html` -
  • - ${selectable +
    + ${this.selectable ? html` selected - ? this._deselectItem(item.unique) - : this._selectItem(item.unique)}/>` + .checked=${this.selected} + @change=${() => this.selected ? this.#onDeselected() : this.#onSelected()}/>` : nothing} - ${href && !this._selectOnly - ? html`${item.name}` - : html`${item.name}`} + ${this.href + ? html`${this.item.name}` + : html`${this.item.name}`} -
    • + `; } -} -export { MyCollectionViewElement as element }; + #onSelected() { + if (!this.item) return; + this.dispatchEvent(new UmbSelectedEvent(this.item.unique)); + } + + #onDeselected() { + if (!this.item) return; + this.dispatchEvent(new UmbDeselectedEvent(this.item.unique)); + } +} declare global { interface HTMLElementTagNameMap { - 'my-collection-view': MyCollectionViewElement; + 'my-collection-view-item': MyCollectionViewItemElement; } } ``` From 6fef69543829803ccfc9902b0c9daa80aa4dd354 Mon Sep 17 00:00:00 2001 From: Mads Rasmussen Date: Thu, 7 May 2026 20:27:28 +0200 Subject: [PATCH 14/21] Add select-only mode for collection items --- .../extension-types/collections/collection-view/custom.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/custom.md b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/custom.md index f316e68a697..92ddd35700a 100644 --- a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/custom.md +++ b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection-view/custom.md @@ -60,6 +60,7 @@ export class MyCollectionViewElement extends UmbCollectionViewElementBase { .href=${item.unique ? this._itemHrefs.get(item.unique) : undefined} ?selectable=${this._isSelectableItem(item)} ?selected=${this._isSelectedItem(item.unique)} + ?selectOnly=${this._selectOnly} @selected=${() => this._selectItem(item.unique)} @deselected=${() => this._deselectItem(item.unique)}> @@ -117,6 +118,9 @@ export class MyCollectionViewItemElement extends UmbLitElement { @property({ type: Boolean }) selected = false; + @property({ type: Boolean }) + selectOnly = false; + @property({ type: String }) href?: string; @@ -131,7 +135,7 @@ export class MyCollectionViewItemElement extends UmbLitElement { .checked=${this.selected} @change=${() => this.selected ? this.#onDeselected() : this.#onSelected()}/>` : nothing} - ${this.href + ${this.href && !this.selectOnly ? html`${this.item.name}` : html`${this.item.name}`} From d2d080ce3e669fd4cc115322c5b55cb48ddf7313 Mon Sep 17 00:00:00 2001 From: Mads Rasmussen Date: Thu, 7 May 2026 20:36:09 +0200 Subject: [PATCH 15/21] Update README.md --- .../extending-overview/extension-types/collections/README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/README.md b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/README.md index 395418c4021..3dbffeaf9d8 100644 --- a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/README.md +++ b/17/umbraco-cms/customizing/extending-overview/extension-types/collections/README.md @@ -17,8 +17,6 @@ The Collection itself does not render anything. It manages pagination, filtering | **Collection Repository** | Fetches and returns items | | **Collection View** | Bound to the collection via its alias; renders the items | -A Collection View uses the `Umb.Condition.CollectionAlias` condition to attach itself to a specific collection. This means you can register multiple views (table, card, reference) for the same collection alias, and the backoffice will offer them as view options. - ## Articles * [Collection](collection.md) From 2b8c4f4f83d2b0cfef8aec5b3bcac6fb3f10bd1e Mon Sep 17 00:00:00 2001 From: Mads Rasmussen Date: Tue, 12 May 2026 16:52:43 +0200 Subject: [PATCH 16/21] Create collection.md --- .../collections/collection-view/collection.md | 129 ++++++++++++++++++ 1 file changed, 129 insertions(+) create mode 100644 17/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-types/collections/collection-view/collection.md diff --git a/17/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-types/collections/collection-view/collection.md b/17/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-types/collections/collection-view/collection.md new file mode 100644 index 00000000000..4141c91a275 --- /dev/null +++ b/17/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-types/collections/collection-view/collection.md @@ -0,0 +1,129 @@ +--- +description: >- + Learn how to register a Collection extension and implement a Collection + Repository to provide data for Collection Views. +--- + +# Collection + +A Collection is an extension type that registers under a unique alias and uses a **Collection Repository** to fetch items. **Collection Views** bind themselves to the collection via that alias to display the items. + +## Manifest + +Register a collection using the `collection` extension type. The `repositoryAlias` in `meta` must match the alias of a registered Collection Repository. + +{% code title="umbraco-package.json" %} +```json +{ + "type": "collection", + "kind": "default", + "alias": "My.Collection", + "name": "My Collection", + "meta": { + "repositoryAlias": "My.Collection.Repository" + } +} +``` +{% endcode %} + +## Collection Repository + +A Collection Repository fetches and returns the items displayed in the collection. It must implement the `UmbCollectionRepository` interface, which requires a single `requestCollection` method. + +### Manifest + +Register the repository as a separate extension. The `api` property points to the file that exports the repository class: + +{% code title="umbraco-package.json" %} +```json +{ + "type": "repository", + "alias": "My.Collection.Repository", + "name": "My Collection Repository", + "api": "/App_Plugins/my-collection/my-collection.repository.js" +} +``` +{% endcode %} + +### Item model + +Define the shape of the items your repository returns by extending `UmbCollectionItemModel`. The property names you add here are what Collection Views use when rendering the items. + +The base Collection Item Model that all items must satisfy is: + +```typescript +export interface UmbCollectionItemModel { + unique: string; + entityType: string; + name?: string; + icon?: string; +} +``` + +{% code title="types.ts" %} +```typescript +import type { UmbCollectionItemModel } from '@umbraco-cms/backoffice/collection'; + +export interface MyCollectionItemModel extends UmbCollectionItemModel { + status: string; + creator: string; +} +``` +{% endcode %} + +### Implementation + +Extend `UmbRepositoryBase` and implement `UmbCollectionRepository`. The `requestCollection` method receives a filter object with `skip` and `take` for pagination, and must return `{ data: { items, total } }`. For guidance on making HTTP requests to a server API, see [Fetching Data](../../../../foundation/fetching-data/README.md): + +{% code title="my-collection.repository.ts" %} +```typescript +import type { MyCollectionItemModel } from './types.js'; +import { UmbRepositoryBase } from '@umbraco-cms/backoffice/repository'; +import type { UmbCollectionRepository, UmbCollectionFilterModel } from '@umbraco-cms/backoffice/collection'; + +export class MyCollectionRepository + extends UmbRepositoryBase + implements UmbCollectionRepository +{ + async requestCollection(filter: UmbCollectionFilterModel) { + const skip = filter.skip ?? 0; + const take = filter.take ?? 10; + + // Replace this with a real API call. + const allItems: MyCollectionItemModel[] = [ + { + unique: 'b3e31e9c-7d66-4c99-a9e5-d9f2b1e2b22f', + entityType: 'my-entity', + name: 'Item One', + status: 'Published', + creator: 'Admin', + }, + { + unique: 'ac9b6e24-4b11-4dd6-8d4e-7c4f70e59f3c', + entityType: 'my-entity', + name: 'Item Two', + status: 'Draft', + creator: 'Editor', + }, + ]; + + const items = allItems.slice(skip, skip + take); + + return { + data: { + items, + total: allItems.length, + }, + }; + } +} + +export { MyCollectionRepository as api }; +``` +{% endcode %} + +The exported `api` alias lets the extension registry instantiate the class when the collection loads. + +## Next steps + +With a collection and repository registered, add a [Collection View](collection-view/README.md) to control how the items are displayed. From 9fb76216e85a1f09c5e0813aec7ab57ed226b14d Mon Sep 17 00:00:00 2001 From: Mads Rasmussen Date: Tue, 12 May 2026 16:57:17 +0200 Subject: [PATCH 17/21] move to new location --- .../collections/collection-view/collection.md | 129 ------------------ .../extension-types/collections/collection.md | 0 2 files changed, 129 deletions(-) delete mode 100644 17/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-types/collections/collection-view/collection.md rename 17/umbraco-cms/{customizing => extend-your-project/backoffice-extensions}/extending-overview/extension-types/collections/collection.md (100%) diff --git a/17/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-types/collections/collection-view/collection.md b/17/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-types/collections/collection-view/collection.md deleted file mode 100644 index 4141c91a275..00000000000 --- a/17/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-types/collections/collection-view/collection.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -description: >- - Learn how to register a Collection extension and implement a Collection - Repository to provide data for Collection Views. ---- - -# Collection - -A Collection is an extension type that registers under a unique alias and uses a **Collection Repository** to fetch items. **Collection Views** bind themselves to the collection via that alias to display the items. - -## Manifest - -Register a collection using the `collection` extension type. The `repositoryAlias` in `meta` must match the alias of a registered Collection Repository. - -{% code title="umbraco-package.json" %} -```json -{ - "type": "collection", - "kind": "default", - "alias": "My.Collection", - "name": "My Collection", - "meta": { - "repositoryAlias": "My.Collection.Repository" - } -} -``` -{% endcode %} - -## Collection Repository - -A Collection Repository fetches and returns the items displayed in the collection. It must implement the `UmbCollectionRepository` interface, which requires a single `requestCollection` method. - -### Manifest - -Register the repository as a separate extension. The `api` property points to the file that exports the repository class: - -{% code title="umbraco-package.json" %} -```json -{ - "type": "repository", - "alias": "My.Collection.Repository", - "name": "My Collection Repository", - "api": "/App_Plugins/my-collection/my-collection.repository.js" -} -``` -{% endcode %} - -### Item model - -Define the shape of the items your repository returns by extending `UmbCollectionItemModel`. The property names you add here are what Collection Views use when rendering the items. - -The base Collection Item Model that all items must satisfy is: - -```typescript -export interface UmbCollectionItemModel { - unique: string; - entityType: string; - name?: string; - icon?: string; -} -``` - -{% code title="types.ts" %} -```typescript -import type { UmbCollectionItemModel } from '@umbraco-cms/backoffice/collection'; - -export interface MyCollectionItemModel extends UmbCollectionItemModel { - status: string; - creator: string; -} -``` -{% endcode %} - -### Implementation - -Extend `UmbRepositoryBase` and implement `UmbCollectionRepository`. The `requestCollection` method receives a filter object with `skip` and `take` for pagination, and must return `{ data: { items, total } }`. For guidance on making HTTP requests to a server API, see [Fetching Data](../../../../foundation/fetching-data/README.md): - -{% code title="my-collection.repository.ts" %} -```typescript -import type { MyCollectionItemModel } from './types.js'; -import { UmbRepositoryBase } from '@umbraco-cms/backoffice/repository'; -import type { UmbCollectionRepository, UmbCollectionFilterModel } from '@umbraco-cms/backoffice/collection'; - -export class MyCollectionRepository - extends UmbRepositoryBase - implements UmbCollectionRepository -{ - async requestCollection(filter: UmbCollectionFilterModel) { - const skip = filter.skip ?? 0; - const take = filter.take ?? 10; - - // Replace this with a real API call. - const allItems: MyCollectionItemModel[] = [ - { - unique: 'b3e31e9c-7d66-4c99-a9e5-d9f2b1e2b22f', - entityType: 'my-entity', - name: 'Item One', - status: 'Published', - creator: 'Admin', - }, - { - unique: 'ac9b6e24-4b11-4dd6-8d4e-7c4f70e59f3c', - entityType: 'my-entity', - name: 'Item Two', - status: 'Draft', - creator: 'Editor', - }, - ]; - - const items = allItems.slice(skip, skip + take); - - return { - data: { - items, - total: allItems.length, - }, - }; - } -} - -export { MyCollectionRepository as api }; -``` -{% endcode %} - -The exported `api` alias lets the extension registry instantiate the class when the collection loads. - -## Next steps - -With a collection and repository registered, add a [Collection View](collection-view/README.md) to control how the items are displayed. diff --git a/17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection.md b/17/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-types/collections/collection.md similarity index 100% rename from 17/umbraco-cms/customizing/extending-overview/extension-types/collections/collection.md rename to 17/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-types/collections/collection.md From 7f969d1e2d406687653537737880c92e6987b79f Mon Sep 17 00:00:00 2001 From: Mads Rasmussen Date: Tue, 12 May 2026 18:05:06 +0200 Subject: [PATCH 18/21] Update SUMMARY.md --- 17/umbraco-cms/SUMMARY.md | 1 + 1 file changed, 1 insertion(+) diff --git a/17/umbraco-cms/SUMMARY.md b/17/umbraco-cms/SUMMARY.md index 35a60da9fe7..35fd09fcf8a 100644 --- a/17/umbraco-cms/SUMMARY.md +++ b/17/umbraco-cms/SUMMARY.md @@ -364,6 +364,7 @@ * [Workspace Footer Apps](extend-your-project/backoffice-extensions/extending-overview/extension-types/workspaces/workspace-footer-apps.md) * [Workspace Views](extend-your-project/backoffice-extensions/extending-overview/extension-types/workspaces/workspace-views.md) * [Collections](extend-your-project/backoffice-extensions/extending-overview/extension-types/collections/README.md) + * [Collection](extend-your-project/backoffice-extensions/extending-overview/extension-types/collections/collction.md) * [Collection View](extend-your-project/backoffice-extensions/extending-overview/extension-types/collections/collection-view/README.md) * [Table View](extend-your-project/backoffice-extensions/extending-overview/extension-types/collections/collection-view/table.md) * [Card View](extend-your-project/backoffice-extensions/extending-overview/extension-types/collections/collection-view/card.md) From 9c926c7c92bacda8a723d0990f12673f7fa931d0 Mon Sep 17 00:00:00 2001 From: Mads Rasmussen Date: Tue, 12 May 2026 18:49:27 +0200 Subject: [PATCH 19/21] Update SUMMARY.md --- 17/umbraco-cms/SUMMARY.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/17/umbraco-cms/SUMMARY.md b/17/umbraco-cms/SUMMARY.md index 35fd09fcf8a..e9c74deff5f 100644 --- a/17/umbraco-cms/SUMMARY.md +++ b/17/umbraco-cms/SUMMARY.md @@ -364,7 +364,7 @@ * [Workspace Footer Apps](extend-your-project/backoffice-extensions/extending-overview/extension-types/workspaces/workspace-footer-apps.md) * [Workspace Views](extend-your-project/backoffice-extensions/extending-overview/extension-types/workspaces/workspace-views.md) * [Collections](extend-your-project/backoffice-extensions/extending-overview/extension-types/collections/README.md) - * [Collection](extend-your-project/backoffice-extensions/extending-overview/extension-types/collections/collction.md) + * [Collection](extend-your-project/backoffice-extensions/extending-overview/extension-types/collections/collection.md) * [Collection View](extend-your-project/backoffice-extensions/extending-overview/extension-types/collections/collection-view/README.md) * [Table View](extend-your-project/backoffice-extensions/extending-overview/extension-types/collections/collection-view/table.md) * [Card View](extend-your-project/backoffice-extensions/extending-overview/extension-types/collections/collection-view/card.md) From 4a2bf2449fe00d89974e840286133df60bb617b7 Mon Sep 17 00:00:00 2001 From: Mads Rasmussen Date: Tue, 12 May 2026 22:58:52 +0200 Subject: [PATCH 20/21] Remove Collection Action link from README --- .../extending-overview/extension-types/collections/README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/17/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-types/collections/README.md b/17/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-types/collections/README.md index 3dbffeaf9d8..bc35ffb9756 100644 --- a/17/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-types/collections/README.md +++ b/17/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-types/collections/README.md @@ -21,4 +21,3 @@ The Collection itself does not render anything. It manages pagination, filtering * [Collection](collection.md) * [Collection View](collection-view/README.md) -* [Collection Action](collection-action.md) From 4f388c8d9d338bf612bd2eca0b742c4740e6d1a3 Mon Sep 17 00:00:00 2001 From: Mads Rasmussen Date: Tue, 12 May 2026 22:59:04 +0200 Subject: [PATCH 21/21] Fix relative link to Fetching Data README --- .../extension-types/collections/collection.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/17/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-types/collections/collection.md b/17/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-types/collections/collection.md index 4141c91a275..ffde7e94cd4 100644 --- a/17/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-types/collections/collection.md +++ b/17/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-types/collections/collection.md @@ -73,7 +73,7 @@ export interface MyCollectionItemModel extends UmbCollectionItemModel { ### Implementation -Extend `UmbRepositoryBase` and implement `UmbCollectionRepository`. The `requestCollection` method receives a filter object with `skip` and `take` for pagination, and must return `{ data: { items, total } }`. For guidance on making HTTP requests to a server API, see [Fetching Data](../../../../foundation/fetching-data/README.md): +Extend `UmbRepositoryBase` and implement `UmbCollectionRepository`. The `requestCollection` method receives a filter object with `skip` and `take` for pagination, and must return `{ data: { items, total } }`. For guidance on making HTTP requests to a server API, see [Fetching Data](../../../foundation/fetching-data/README.md): {% code title="my-collection.repository.ts" %} ```typescript