From 48d3daedffcefe25d17b23f558b6ecaeb3741311 Mon Sep 17 00:00:00 2001 From: sofietoft Date: Thu, 7 Nov 2024 12:42:51 +0100 Subject: [PATCH] Sync Customizing section with 14 --- 15/umbraco-cms/customizing/dashboards.md | 138 ---------- ...extend-and-customize-editing-experience.md | 27 -- .../foundation/contexts/global-context.md | 24 -- .../foundation/contexts/variant-context.md | 25 -- .../customizing/package-manifest.md | 254 ------------------ .../customizing/section-trees/README.md | 29 -- .../section-trees/searchable-trees.md | 165 ------------ .../section-trees/sections/README.md | 76 ------ .../section-trees/sections/section-sidebar.md | 69 ----- .../section-trees/sections/section-view.md | 127 --------- .../customizing/section-trees/trees/README.md | 141 ---------- .../section-trees/trees/entity-actions.md | 216 --------------- .../trees/entity-bulk-actions.md | 57 ---- 15/umbraco-cms/customizing/terminology.md | 23 -- .../customizing/ui-documentation.md | 74 ----- 15/umbraco-cms/customizing/ui-localization.md | 235 ---------------- .../customizing/workspaces/README.md | 24 -- .../workspaces/workspace-context.md | 83 ------ .../workspaces/workspace-editor-actions.md | 55 ---- .../workspaces/workspace-editor-views.md | 100 ------- 20 files changed, 1942 deletions(-) delete mode 100644 15/umbraco-cms/customizing/dashboards.md delete mode 100644 15/umbraco-cms/customizing/extend-and-customize-editing-experience.md delete mode 100644 15/umbraco-cms/customizing/foundation/contexts/global-context.md delete mode 100644 15/umbraco-cms/customizing/foundation/contexts/variant-context.md delete mode 100644 15/umbraco-cms/customizing/package-manifest.md delete mode 100644 15/umbraco-cms/customizing/section-trees/README.md delete mode 100644 15/umbraco-cms/customizing/section-trees/searchable-trees.md delete mode 100644 15/umbraco-cms/customizing/section-trees/sections/README.md delete mode 100644 15/umbraco-cms/customizing/section-trees/sections/section-sidebar.md delete mode 100644 15/umbraco-cms/customizing/section-trees/sections/section-view.md delete mode 100644 15/umbraco-cms/customizing/section-trees/trees/README.md delete mode 100644 15/umbraco-cms/customizing/section-trees/trees/entity-actions.md delete mode 100644 15/umbraco-cms/customizing/section-trees/trees/entity-bulk-actions.md delete mode 100644 15/umbraco-cms/customizing/terminology.md delete mode 100644 15/umbraco-cms/customizing/ui-documentation.md delete mode 100644 15/umbraco-cms/customizing/ui-localization.md delete mode 100644 15/umbraco-cms/customizing/workspaces/README.md delete mode 100644 15/umbraco-cms/customizing/workspaces/workspace-context.md delete mode 100644 15/umbraco-cms/customizing/workspaces/workspace-editor-actions.md delete mode 100644 15/umbraco-cms/customizing/workspaces/workspace-editor-views.md diff --git a/15/umbraco-cms/customizing/dashboards.md b/15/umbraco-cms/customizing/dashboards.md deleted file mode 100644 index 56339b38b26..00000000000 --- a/15/umbraco-cms/customizing/dashboards.md +++ /dev/null @@ -1,138 +0,0 @@ ---- -description: A guide to creating custom dashboards in Umbraco ---- - -# Dashboards - -Each section of the Umbraco backoffice has its own set of default dashboards. Your own custom sections can show dashboards, and you can create your own custom dashboards for existing sections. - -
The Getting Started dashboard in Umbraco

The Getting Started dashboard in Umbraco

- -The dashboard area of Umbraco is used to display an "editor" for the selected item in the tree. If no item is selected, then the default set of section dashboards is shown in the dashboard area. - -Notice that [Section Views](section-trees/sections/section-view.md) is another similar approach to append information to the root of a Section. Section views are thought mainly to be used as Secondary pages. These two approaches should ideally not be combined. - -## Default Dashboards in Umbraco - -The default dashboards in Umbraco are the ones that are displayed when you first enter a section in the backoffice. These dashboards are used to display information and functionality that is relevant to the section you are in. - -The default sections in Umbraco are: - -| Alias | Name | -| ----------------------- | ---------- | -| Umb.Section.Content | Content | -| Umb.Section.Media | Media | -| Umb.Section.Settings | Settings | -| Umb.Section.Members | Members | -| Umb.Section.Users | Users | -| Umb.Section.Translation | Dictionary | - -Here is a table of the default dashboards in Umbraco and the sections they are used including their aliases: - -| Alias | Section | Weight | Description | -| -------------------------------- | -------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | -| Umb.Dashboard.UmbracoNews | Umb.Section.Content | 20 | The Getting Started dashboard users see when they first enter Umbraco. Contains the latest news of Umbraco including outbound links to resources | -| Umb.Dashboard.RedirectManagement | Umb.Section.Content | 10 | Contains a list of active URL redirects | -| Umb.Dashboard.SettingsWelcome | Umb.Section.Settings | 500 | Contains a set of boxes with links to appropriate resources | - -Even though these dashboards are useful, you might want to create your own custom dashboard to display specific information or functionality. - -You can try and [create a custom dashboard](../../tutorials/creating-a-custom-dashboard/) as a way on getting started on this topic. - -## Registering your Dashboard - -This section dives into the Dashboard Extension Manifest, shows how to register one, and append additional details. - -### Example Extension Manifest - -{% hint style="info" %} -You can read more about manifests in the tutorial [Creating Your First Extension](../tutorials/creating-your-first-extension.md). -{% endhint %} - -Insert this as an entry in the `extensions` list in a `umbraco-package.json` file. - -{% code title="~/App_Plugins/WelcomeDashboard/umbraco-package.json" lineNumbers="true" %} -```json -{ - "type": "dashboard", - "alias": "my.welcome.dashboard", - "name": "My Welcome Dashboard", - "element": "/App_Plugins/WelcomeDashboard/dashboard.js", - "weight": -1, - "meta": { - "label": "Welcome Dashboard", - "pathname": "welcome-dashboard" - } -} -``` -{% endcode %} - -This will register a dashboard with the alias `my.welcome.dashboard` and the name `My Welcome Dashboard`. The dashboard will be loaded from the file `/App_Plugins/WelcomeDashboard/dashboard.js`. The dashboard will be displayed with the label `Welcome Dashboard` and the URL `/welcome-dashboard` on _all sections_, e.g. `/section/content/dashboard/welcome-dashboard`. - -### Conditions - -You can specify conditions for when the dashboard should be displayed. This is done by adding a `conditions` property to the manifest. Ideally, we would like the dashboard to be shown only in a specific section. This can be done by specifying the condition called `Umb.Condition.SectionAlias` and providing the [alias of the section](dashboards.md#default-dashboards-in-umbraco) you want the dashboard to be displayed on: - -```json -"conditions": [ - { - "alias": "Umb.Condition.SectionAlias", - "match": "Umb.Section.Content" - } -] -``` - -This will make the dashboard only be displayed on the Content section. - -{% hint style="info" %} -You can read more about [Extension Conditions](extending-overview/extension-types/condition.md) in the documentation. -{% endhint %} - -### Properties - -The dashboard manifest can contain the following properties: - -| Property | Type | Description | -| ----------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| type | string | The type of extension, should be `dashboard` | -| alias | string | A unique alias for the dashboard extension | -| name | string | The name of the dashboard extension | -| element | string | The path to the JavaScript file that exports the dashboard | -| elementName | string | (Optional) The name of the Web Component that contains the dashboard (only if not a default export) | -| weight | number | (Optional) The weight of the dashboard, higher numbers are displayed first | -| meta | object |

Additional metadata for the dashboard

PropertyTypeDescription
LabelstringThe label shown to the user
pathnamestringThe routable URL pathname
| -| Property | Type | Description | -| Label | string | The label shown to the user | -| pathname | string | The routable URL pathname | -| Property | Type | Description | -| Label | string | The label shown to the user | -| pathname | string | The routable URL pathname | -| conditions | array | (Optional) [Conditions](extending-overview/extension-types/condition.md) for when the dashboard should be displayed | - -### Full Example - -{% code title="~/App_Plugins/WelcomeDashboard/umbraco-package.json" lineNumbers="true" %} -```json -{ - "type": "dashboard", - "alias": "my.welcome.dashboard", - "name": "My Welcome Dashboard", - "element": "/App_Plugins/WelcomeDashboard/dashboard.js", - "weight": -1, - "meta": { - "label": "Welcome Dashboard", - "pathname": "welcome-dashboard" - }, - "conditions": [ - { - "alias": "Umb.Condition.SectionAlias", - "match": "Umb.Section.Content" - } - ] -} -``` -{% endcode %} - -
The Welcome Dashboard shown in the Content section

The Welcome Dashboard appears in the Content section

- -You can learn about [creating a custom dashboard](../tutorials/creating-a-custom-dashboard/) in the tutorials section. Here you will learn how to build the dashboard itself as a Web Component. diff --git a/15/umbraco-cms/customizing/extend-and-customize-editing-experience.md b/15/umbraco-cms/customizing/extend-and-customize-editing-experience.md deleted file mode 100644 index cfda9be7aee..00000000000 --- a/15/umbraco-cms/customizing/extend-and-customize-editing-experience.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -description: >- - Get an overview of the different options for extending and customizing the - Umbraco CMS backoffice. ---- - -# Extend and customize the editing experience - -The backoffice is one of the main forces of Umbraco CMS. It is where you build the foundations for the website and where your content editors will work with the content. - -{% hint style="info" %} -Are you looking to **extend and customize the Umbraco CMS**? - -Resources are available in the [Extending](../extending/build-on-umbraco-functionality.md) section for when you are looking to extend Umbraco functionality beyond the backoffice. -{% endhint %} - -In this section, you will find all the resources you need to build an intuitive and fluid editor experience for your content editors. - -
DashboardsThe dashboard is where all the main functionality of the backoffice will be.dashboards.mddashboards-image.png
Sections and TreesExtend the backoffice by customizing existing and building new sections and trees.section-treestrees.image.png
Property EditorsLearn how to extend and build some of the main building blocks in Umbraco CMS.property-editorsproperty-image.png
- -*** - -## Umbraco Training - -Umbraco HQ offers a training course covering extending and customizing the Umbraco Backoffice to enhance the editing experience. The course targets frontend and backend developers familiar with Umbraco who want to extend the UI for editors. - -[Explore the Extending the Backoffice Training Course](https://umbraco.com/training/course-details/extending-the-backoffice-details/) to learn more about the topics covered and how it can enhance your Umbraco development skills. \ No newline at end of file diff --git a/15/umbraco-cms/customizing/foundation/contexts/global-context.md b/15/umbraco-cms/customizing/foundation/contexts/global-context.md deleted file mode 100644 index 744314d195c..00000000000 --- a/15/umbraco-cms/customizing/foundation/contexts/global-context.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -description: Establish the bond for extensions to communication across the application ---- - -# Global Context - -{% hint style="warning" %} -This page is a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice. -{% endhint %} - -A global context manages the logic code from your Lit Element controllers. - -## Registration of a Global Context - -You can register a global context like so: - -```typescript -{ - type: 'globalContext', - alias: 'My.GlobalContext.Products', - name: 'My Products Context', - api: 'my-products.context.js', -} -``` diff --git a/15/umbraco-cms/customizing/foundation/contexts/variant-context.md b/15/umbraco-cms/customizing/foundation/contexts/variant-context.md deleted file mode 100644 index 8fb610ae303..00000000000 --- a/15/umbraco-cms/customizing/foundation/contexts/variant-context.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -description: The Variant Context is a context that holds the data for a set of properties. ---- - -# Property Dataset Context - -{% hint style="warning" %} -This page is a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice. -{% endhint %} - -Property Editors UIs require the Dataset Context to be present to work. This enables Property Editor UIs to have a generic relation with its ownership. - -The Dataset Context holds a name and a set of properties. What makes a property can vary but an alias and a value are required. - -### Dataset Context Concerning Property Editors and Workspaces - -A Dataset Context is the connection point between a Property Editor and a Workspace. - -The hierarchy is as follows: - -* Workspace Context - * Dataset Context - * Property Editor UIs - -A dataset context covers a set of properties, in some cases a workspace then needs to have multiple variants. An example of such is Document Workspace. Each variant has its own set of properties and a name. diff --git a/15/umbraco-cms/customizing/package-manifest.md b/15/umbraco-cms/customizing/package-manifest.md deleted file mode 100644 index 49a0d5597e7..00000000000 --- a/15/umbraco-cms/customizing/package-manifest.md +++ /dev/null @@ -1,254 +0,0 @@ ---- -description: An extension begins with a Package Manifest ---- - -# Package Manifest - -A Package is declared via an Umbraco Package Manifest. This describes the Package and declares one or more UI Extensions. The Package Manifest is a JSON file that is stored in the `App_Plugins/{YourPackageName}` folder. The file is named `umbraco-package.json`. - -## Sample Manifest - -This is a sample manifest. It is always stored in a folder in `App_Plugins/{YourPackageName}`, with the name `umbraco-package.json`. In this example, the package name is `SirTrevor` and is a text box property Data Type. - -{% hint style="info" %} -Before Umbraco 14, the manifest was declared in a `package.manifest` file instead of `umbraco-package.json`. The old format is no longer supported, but you can migrate the contents to the new format. -{% endhint %} - -{% code title="umbraco-package.json" lineNumbers="true" %} -```json -{ - "id": "My.Nuget.Package", - "name": "Sir Trevor", - "version": "1.0.0-beta", - "allowPackageTelemetry": true, - "extensions": [ - { - "type": "propertyEditorUi", - "alias": "Sir.Trevor", - "name": "Sir Trevor Property Editor UI", - "element": "/App_Plugins/SirTrevor/SirTrevor.js", - "meta": { - "label": "Sir Trevor", - "propertyEditorSchemaAlias": "Umbraco.TextBox", - "icon": "icon-code", - "group": "Pickers" - } - } - ] -} -``` -{% endcode %} - -## Root properties - -The manifest takes seven fields: - -```json -{ - "id": "", - "name": "", - "version": "", - "allowPackageTelemetry": true, - "allowPublicAccess": false, - "importmap": { - "imports": { - "": "" - }, - "scopes": { - "": "" - } - }, - "extensions": [] -} -``` - -### Id - -The unique identifier for your package. This is used to identify your package and should be unique to your package. If you are creating a package that is distributed via NuGet, you should use the NuGet package ID as the ID for your package. - -### Name - -Allows you to specify a friendly name for your package that will be used for telemetry. If no name is specified the name of the folder will be used instead. - -### Version - -The version of your package, if this is not specified there will be no version-specific information for your package. This is used for telemetry and to help users understand what version of your package they are using. It is also used for package migrations. The version should follow the [Semantic Versioning](https://semver.org/) format. - -### Allow Package Telemetry - -With this field, you can control the telemetry of this package, this will provide Umbraco with the knowledge of how many installations use this package. - -Default is `false`. - -### Allow Public Access - -This field is used to allow public access to the package. If set to `true`, the package will be available for anonymous usage, for example on the login screen. If set to `false`, the package will only be available to logged-in users. - -Default is `false`. - -### Importmap - -The `importmap` field is an object that contains two properties: `imports` and `scopes`. This is used to define the import map for the package. The `imports` property is an object that contains the import map for the package. The `scopes` property is an object that contains the scopes for the package. - -**Example** - -This example shows how to define an import map for a module exported by a package: - -{% code title="umbraco-package.json" lineNumbers="true" %} -```json -{ - "importmap": { - "imports": { - "mypackage/services": "/App_Plugins/MyPackage/services/index.js", - } - } -} -``` -{% endcode %} - -The `imports` object contains the import map for the package. The key is the specifier for the module that is being imported, and the value is the URL of the module. - -This allows developers to consume modules that are exported by a package without having to know the exact path to the module: - -{% code title="index.js" %} -```javascript -import { MyService } from 'mypackage/services'; -``` -{% endcode %} - -Umbraco supports the current specification of the property as outlined on MDN Web Docs: [importmap](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap). - -### Extensions - -The `extensions` field is an array of UI Extension objects. Each object describes a single UI Extension. - -There are three generic fields that are common to all UI Extensions: - -* `type` - The type of the UI Extension. -* `alias` - The alias of the UI Extension. This must be unique. -* `name` - The name of the UI Extension. - -These are the current types of UI Extensions: - -| Type | Description | -| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| authProvider | An authentication provider for [external login](../reference/security/external-login-providers.md). | -| appEntryPoint | An app entry point is a JavaScript module that is executed when any app is loaded (Login, Installer, Upgrader, and Backoffice). It will never be destroyed. Read more about [Entry Points](extending-overview/extension-types/entry-point.md). | -| backofficeEntryPoint | A backoffice entry point is a JavaScript module that is executed when the backoffice is loaded. It will be destroyed when the backoffice is closed or logged out. Read more about [Entry Points](extending-overview/extension-types/entry-point.md). | -| blockEditorCustomView | A custom view for a block in the block editor. | -| bundle | A bundle is a collection of other manifests that can be loaded together. You would use this in lieu of a `backofficeEntryPoint` if all you needed was to load extensions through JavaScript. | -| condition | A condition that can be used to control the visibility of other UI Extensions. Read more about [Conditions](extending-overview/extension-types/condition.md). | -| currentUserAction | A current user action is a button that can be added to the current user view. | -| dashboard | A dashboard is a view that can be added to any section. It is displayed in the dashboard view with tabs. Read more about [Dashboards](dashboards.md). | -| dashboardCollection | A dashboard collection is a view that can be added to a collection. | -| dynamicRootOrigin | A dynamic root origin is a dynamic root origin that can be added to the Dynamic Root selector. | -| dynamicRootQueryStep | A dynamic root query step is a query step that can be added to the Dynamic Root selector. | -| entityAction | An entity action is a button that can be added to any entity, like a document, media, member, etc. It will be shown in the entity actions menu and in the entity actions menu. | -| entityBulkAction | An entity bulk action is a button that can be added to the bulk actions menu, which is shown when multiple entities are selected in a collection view. | -| entryPoint | (Deprecated) Old name for `backofficeEntryPoint`. | -| globalContext | A global context is a context instance that is available to all components in the Backoffice. It is used to share state between components and to provide a way to communicate between components. Read more about [Global Context](foundation/contexts/global-context.md). | -| granularUserPermissions | A granular user permission is a permission that can be added to a user. It is used to control access to specific parts of the Backoffice. | -| headerApp | A header app is a component that can be added to the header such as a button or a link. Read more about [Header Apps](extending-overview/extension-types/header-apps.md). | -| healthCheck | A health check is a check that can be added to the health check dashboard. Read more about the backend side of [Health Checks](../reference/configuration/healthchecks.md). | -| icons | An icon is a set of icons that can be added to the icon picker. Read more in the [Icons article](extending-overview/extension-types/icons.md). | -| localization | A localization is a set of translations that can be added to the localization service. Read more about [Localization](ui-localization.md) in the UI. | -| menu | A menu is a component that can be added to the menu bar. Read more about [Menus](extending-overview/extension-types/menu.md). | -| menuItem | A menu item is a component that can be added to a menu. | -| mfaLoginProvider | This type of login provider is the UI component of [Two-Factor Authentication](../reference/security/two-factor-authentication.md) used to enable/disable the provider. | -| modal | A modal dialog. Read more about [Modals](extending-overview/extension-types/modals/). | -| monacoMarkdownEditorAction | A Monaco Markdown Editor action is a button that can be added to the toolbar of the [Markdown Property Editor](../fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/markdown-editor.md). | -| packageView | A package view is an optional view that can be shown in the "Packages" section of the Backoffice. The user can navigate to this view to see more information about the package and to manage it. | -| previewAppProvider | A preview app provider is a provider that can be used to provide a preview app for the Save and Preview action on a document. | -| propertyAction | A property action is a button that can be added to the property actions menu. | -| propertyEditorSchema | A property editor schema is a model that describes a Data Editor and its properties from the backend to the UI. It is used by Property Editor UIs. Read more about [Property Editors](property-editors/). | -| propertyEditorUi | A property editor UI is a UI component that can be added to content types. It is used to render the UI of a Data Editor. Read more about [Property Editors](property-editors/). | -| searchProvider | A search provider is a provider that can be used to provide search results for the search bar in the Backoffice. | -| searchResultItem | A search result item is a component that can be added to the search results. | -| theme | A theme is a set of styles that can be added to the Backoffice. The user can select their preferred theme in the current user modal. | -| tinyMcePlugin | A TinyMCE plugin is a plugin that can be added to the TinyMCE editor. Read more about [TinyMCE Plugins](../fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/rte-plugins.md). | -| treeItem | A tree item that can be added to the tree. | -| tree | A tree that can be added to a section. | -| ufmComponent | This type of component is a formatter that can be added to the [Umbraco Flavoured Markdown](../reference/umbraco-flavored-markdown.md), which is used in property descriptions and advanced labels. Read more about the [Label Property Configuration](../fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/block-editor/label-property-configuration.md). | -| userProfileApp | A user profile app is a component that can be added to the current user view. | - -**Collections** - -| Type | Description | -| ---------------- | -------------------------------------------------------------------------- | -| collection | A collection to show a list of entities (documents, media, members, etc.). | -| collectionAction | A collection action is a button that can be added to a collection view. | -| collectionView | A collection view is a view that can be added to a collection. | - -**Stores and repositories** - -| Type | Description | -| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| repository | A repository is a class that can be used to interact with a data source. It is used either by context classes or elements directly to interact with the data source. It typically holds a `store` instance. Read more about [Repositories](foundation/working-with-data/repositories.md). | -| store | A store is a context instance that is available to repositories. It is used by repositories to store data. Read more about [Stores](foundation/working-with-data/store.md). | -| itemStore | An item store is a store that can be used to store items. It is used by repositories to store items. | -| treeStore | A tree store is a store that can be used to store tree data. It is used by tree repositories to store tree data. | - -**Sections** - -| Type | Description | -| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| section | A section is a section that can be added to the navigation bar of the Backoffice like the "Content" or "Media" sections that are built-in. Read more about [Sections](section-trees/sections/). | -| sectionRoute | A section route is a route that can be added to a section. It is used to define the URL of the view that is displayed in the main content area of the Backoffice. | -| sectionSidebarApp | A section sidebar app that can be added to the section sidebar. Read more about [Section Sidebar Apps](section-trees/sections/section-sidebar.md). | -| sectionView | A section view is a view that can be added to a section. It is displayed in the main content area of the Backoffice. More than one view can be added to a section, and the user can switch between them. In that case, the views are displayed as tabs. Read more about [Section Views](section-trees/sections/section-view.md). | - -**Workspaces** - -| Type | Description | -| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| workspace | A workspace is a component that can be added to an entity type. This is the editor you see, when you edit an entity. Read more about [Workspaces](workspaces/). | -| workspaceActionMenuItem | A workspace action menu item is a button that can be added to the workspace action menu. | -| workspaceAction | A workspace action is a button that can be added to the workspace such as the "Save" button. Read more about [Workspace Actions](workspaces/workspace-editor-actions.md). | -| workspaceContext | A workspace context is a context instance that is available to all components in the workspace. It is used to share state between components and to provide a way to communicate between components. Read more about [Workspace Context](workspaces/workspace-context.md). | -| workspaceFooterApp | A workspace footer app is a component that can be added to the workspace footer. | -| workspaceView | A workspace view is a view that can be added to a workspace. It is displayed in the main content area of the workspace. More than one view can be added to a workspace, and the user can switch between them. In that case, the views are displayed as tabs. Read more about [Workspace Views](workspaces/workspace-editor-views.md). | - -Read more about [Extension Types](broken-reference) in the Backoffice to get a better understanding of the different types of extensions. - -## Package Manifest IntelliSense - -Make your IDE be aware about the opportunities of the `umbraco-package.json` by adding a JSON schema. This gives your code editor abilities to autocomplete and knowledge about the format. This helps to avoid mistakes or errors when editing the `umbraco-package.json` file. - -### Adding inline schema - -Editors like Visual Studio can use the `$schema` notation in your file. - -```json -{ - "$schema": "../../umbraco-package-schema.json", - "name": "" -} -``` - -Hover over any of the properties to see the description of the property. You can also use the `Ctrl + Space` (Windows/Linux) or `CMD + Space` (macOS) shortcut to see the available properties. - -## Load Package Manifest files - -Umbraco scans the `App_Plugins` folder for `umbraco-package.json` files **two levels deep**. When found, the packages are loaded into the system. - -You may need to restart the application, if you add a new file or modify an existing manifest: - -If the runtime mode is `Production`, the manifests are cached for 30 days or until the application is restarted to improve performance. In other runtime modes, the cache is cleared every 10 seconds. - -{% hint style="info" %} -You can implement the interface [IPackageManifestReader](https://apidocs.umbraco.com/v14/csharp/api/Umbraco.Cms.Infrastructure.Manifest.IPackageManifestReader.html) to provide your own package manifest reader. This can be useful if you want to load package manifests from a different location or source. -{% endhint %} - -## Razor Class Library - -Umbraco also supports [Razor Class Library (RCL)](https://learn.microsoft.com/en-us/aspnet/core/razor-pages/ui-class?view=aspnetcore-8.0\&tabs=visual-studio#create-an-rcl-with-static-assets) projects that contain static web assets. The `umbraco-package.json` file can be placed in the `wwwroot` folder of the RCL project. The package will be loaded when the RCL is referenced by the main project. You must map the web path to `App_Plugins` in your `.csproj` file: - -{% code title="MyProject.Assets.csproj" %} -```xml - - App_Plugins/{YourPackageName} - -``` -{% endcode %} - -Read more about getting set up for Backoffice development in the [Customize Backoffice](extend-and-customize-editing-experience.md) section. diff --git a/15/umbraco-cms/customizing/section-trees/README.md b/15/umbraco-cms/customizing/section-trees/README.md deleted file mode 100644 index d4539abd774..00000000000 --- a/15/umbraco-cms/customizing/section-trees/README.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -description: "An explanation on sections and trees in Umbraco" ---- - -# Sections & Trees - -{% hint style="warning" %} -The Section & Trees articles are a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice. -{% endhint %} - -The Umbraco backoffice consists of sections (sometimes referred to as applications) which contain Trees. - -Each section is identified by its name in the top navigation ribbon of the Umbraco Backoffice. - -For example, when you load the backoffice, you'll see that the 'Content' section contains one tree: the content tree. Meanwhile, the 'Settings' section contains a number of trees such as Stylesheets, Document Types, Media Types, etc... - -You can create your own sections and trees to extend Umbraco. - -## [Sections](sections/README.md) - -Describes Umbraco Sections, configuration and APIs. - -## [Trees](trees/) - -Describes Umbraco Trees, configuration, APIs and events. - -## [Searchable Trees (ISearchableTree)](searchable-trees.md) - -Explains how to customise the backoffice search of a Section Tree. diff --git a/15/umbraco-cms/customizing/section-trees/searchable-trees.md b/15/umbraco-cms/customizing/section-trees/searchable-trees.md deleted file mode 100644 index 01cebeb01fd..00000000000 --- a/15/umbraco-cms/customizing/section-trees/searchable-trees.md +++ /dev/null @@ -1,165 +0,0 @@ -# Searchable Trees (ISearchableTree) - -{% hint style="warning" %} -This page is a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice. -{% endhint %} - -When you type a search term into the Umbraco backoffice search field, you'll see search results from all the Section Trees that your user account has permission to access: - -![Content Section Dashboards](<../../../../10/umbraco-cms/extending/section-trees/images/backoffice-search-v8 (1).png>) - -The results are grouped by 'Section Tree' like Content, Media, Document Types. Each 'Tree' has its own associated search mechanism that receives the search term and looks for matches in the tree that is responsible for searching. - -You can create your own search mechanisms for your own custom sections or replace the default search implementation for a particular section tree. - -## Custom Tree Search - -To create a search for your own custom tree you need to create a C# class that implements the interface `Umbraco.Cms.Core.Trees.ISearchableTree`. - -### ISearchableTree - -```csharp -using System.Collections.Generic; -using Umbraco.Cms.Core.Composing; -using Umbraco.Cms.Core.Models.ContentEditing; - -namespace My.Website; - -public interface ISearchableTree : IDiscoverable -{ - /// - /// The alias of the tree that the belongs to - /// - string TreeAlias { get; } - - /// - /// Searches for results based on the entity type - /// - /// The search term used for finding matching results. - /// The number of records to return for a page of results. - /// The 0-based index for retrieving a page of search results. - /// Populated with the total number of results matching the provided search term. - /// - /// The starting point for the search, generally a node ID, but for members this is a member type alias. - /// - /// - Task SearchAsync(string query, int pageSize, long pageIndex, string? searchFrom = null); -} -``` - -Your implementation needs to return an IEnumerable of `SearchResultEntity` items: - -```csharp -public class SearchResultEntity : EntityBasic -{ - public SearchResultEntity() { - /// - /// The score of the search result - /// - [DataMember(Name = "score")] - public float Score { get; set; } - }; - -} -``` - -A `SearchResultEntity` consists of a Score (a Float value) identifying its relevance to the search term, and the set of `EntityBasic` properties that all Umbraco objects share: eg Name, Id, Udi, Icon, Trashed, Key, ParentId, Path, Alias, AdditionalData. - -#### Example implementation of ISearchableTree - -If we have a custom section Tree with the alias 'favouriteThingsAlias' (see the [custom tree example](trees/)) then we could implement searchability by creating the following C# class in our site: - -```csharp -using System; -using System.Collections.Generic; -using System.Linq; -using System.Threading.Tasks; -using Umbraco.Cms.Core; -using Umbraco.Cms.Core.Models.ContentEditing; -using Umbraco.Cms.Core.Trees; - -namespace Umbraco.Docs.Samples.Web.Trees; - -public class FavouriteThingsSearchableTree : ISearchableTree -{ - public string TreeAlias => "favouriteThingsAlias"; - - public async Task SearchAsync(string query, int pageSize, long pageIndex, string searchFrom = null) - { - // your custom search implementation starts here - Dictionary favouriteThings = new Dictionary(); - favouriteThings.Add(1, "Raindrops on Roses"); - favouriteThings.Add(2, "Whiskers on Kittens"); - favouriteThings.Add(3, "Skys full of Stars"); - favouriteThings.Add(4, "Warm Woolen Mittens"); - favouriteThings.Add(5, "Cream coloured Unicorns"); - favouriteThings.Add(6, "Schnitzel with Noodles"); - - var searchResults = new List(); - - var matchingItems = favouriteThings.Where(f => f.Value.StartsWith(query, true, System.Globalization.CultureInfo.CurrentCulture)); - foreach (var matchingItem in matchingItems) - { - // Making up the Id/Udi for this example! - these would normally be different for each search result. - searchResults.Add(new SearchResultEntity() - { - Id = 12345, - Alias = "favouriteThingItem", - Icon = "icon-favorite", - Key = new Guid("325746a0-ec1e-44e8-8f7b-6e7c4aab36d1"), - Name = matchingItem.Value, - ParentId = -1, - Path = "-1,12345", - Score = 1.0F, - Trashed = false, - Udi = Udi.Create("document", new Guid("325746a0-ec1e-44e8-8f7b-6e7c4aab36d1")) - }); - } - // Set number of search results found - var totalFound = matchingItems.Count(); - // Return your results - return new EntitySearchResults(searchResults, totalFound); - } -} -``` - -That's all we need, after an application pool recycle, if we now search in the backoffice we'll see matches from our custom 'Favourite Things' tree: - -![Content Section Dashboards](<../../../../10/umbraco-cms/extending/section-trees/images/favouritethings-search-v8 (1).png>) - -Umbraco automatically finds any implementation of `ISearchableTree` in your site and automatically configures it to be used for the custom section mentioned in the TreeAlias property. Be careful not to accidentally have two `ISearchableTree` implementations trying to search the 'same' TreeAlias, it's _one_ `ISearchableTree` per TreeAlias. - -## Replacing an existing Section Tree Search - -Perhaps you want to change the logic for searching an existing section of the site, (why? - well you might have a 'company name' property on a MemberType in the Member section, and you want searches for that company name to filter the members who work there, the default implementation will only search on Member Name). - -Or perhaps you want to replace Examine search in the backoffice with an external Search Service, e.g. Azure Search. In a cloud-hosted implementation you don't need to build the Examine indexes on each new server as your cloud hosting scales out. - -### Example - -First create your replacement custom `ISearchableTree` implementation, using the same approach as above, but specifying the TreeAlias of the Tree you aim to replace, e.g. 'Member'. - -```csharp -public string TreeAlias => "member"; -``` - -To avoid your custom implementation clashing with the default `ISearchableTree` for a Tree, you need to remove its `ISearchableTree` implementation from the collection of SearchableTrees using an `IComposer` when Umbraco starts up: - -```csharp -using Umbraco.Cms.Core.Composing; -using Umbraco.Cms.Core.DependencyInjection; -using Umbraco.Cms.Web.BackOffice.Trees; - -namespace Umbraco.Docs.Samples.Web.Trees; - -public class RemoveCoreMemberSearchableTreeComposer : IComposer -{ - public void Compose(IUmbracoBuilder builder) - { - // Remove core MemberTreeController - builder.SearchableTrees().Exclude(); - } -} -``` - -This would then allow your custom implementation of `ISearchableTree` with TreeAlias 'member' to be used when searching the Member Section Tree. diff --git a/15/umbraco-cms/customizing/section-trees/sections/README.md b/15/umbraco-cms/customizing/section-trees/sections/README.md deleted file mode 100644 index cdc564956bf..00000000000 --- a/15/umbraco-cms/customizing/section-trees/sections/README.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -description: A guide to creating a section ---- - -# Sections - -{% hint style="warning" %} -This page is a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice. -{% endhint %} - -The Umbraco backoffice consists of Sections. Section is the main division shown in the top navigation. - -For example, when you load the backoffice, you'll see the 'Content' section, 'Settings' section, and so on. - -You can create your own sections to extend Umbraco with room for more features. - -

Section

- -## **Creating a section** - -### **Manifests** - -When creating a new section it's recommended to use a [Entry Point](../../../customizing/extending-overview/extension-types/backoffice-entry-point.md)-extension in your [Umbraco Package Manifest](../../package-manifest.md). This is to get better control over all the additional extensions required for the new section. - -Create a section by defining a manifest for it: - -```typescript -{ - "type": "section", - "alias": "My.Section", - "name": "My Section", - "meta": { - "label": "My.Section", - "pathname": "my-section" - } -} -``` - -Once registered, you will be able to select this action for your User Group Permissions. Once that is permitted, you can view your section. - -

Section

- -#### **Extend with Sidebar, Dashboards and more** - -Once a section is registered, it can be extended like any other section. - -Here is a list of appropriate extensions to append to your section: - -* [Creating a Custom Dashboard](../../../tutorials/creating-a-custom-dashboard/) -* [Section Sidebar](section-sidebar.md) -* [Section View](section-view.md) - -#### **Manifest with empty element** - -If you prefer full control over the content of your section you can choose to define an element for the content of your section. - -{% hint style="warning" %} -This is not recommended as it limits the content of your section to this element. Instead, it is recommended to use a single Dashboard or Section View. -{% endhint %} - -If you like to have full control, you can define an element like this: - -```typescript -const section : ManifestSection = { - type: "section", - alias: "Empty.Section", - name : 'Empty Section', - element : () => import('./empty-section.element.js'), - meta : { - label : 'Empty Section', - pathname : 'empty-section' - } -} -``` - -The element file must have an `element` or `default` export, or specify the element name in the `elementName` field. diff --git a/15/umbraco-cms/customizing/section-trees/sections/section-sidebar.md b/15/umbraco-cms/customizing/section-trees/sections/section-sidebar.md deleted file mode 100644 index ca9355ce648..00000000000 --- a/15/umbraco-cms/customizing/section-trees/sections/section-sidebar.md +++ /dev/null @@ -1,69 +0,0 @@ -# Section Sidebar - -{% hint style="warning" %} -This page is a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice. -{% endhint %} - -

Section Sidebar

- -## Section Sidebar Apps - -

Section Sidebar Apps

- -**Manifest** - -```typescript -{ - "type": "sectionSidebarApp", - "alias": "My.SectionSidebarApp", - "name": "My Section Sidebar App", - "meta": { - "sections": ["My.Section"] - } -} -``` - -**Default Element** - -```typescript -interface UmbSectionSidebarAppElement {} -``` - -## **Menu Sidebar App** - -**Sidebar Menu**: - -* The Backoffice comes with a menu sidebar app that can be used to create a menu in the sidebar. -* To register a new menu sidebar app, add the following to your manifest -* The menu sidebar app will reference a menu that you have registered in the menu with a menu manifest - -

Menu Sidebar App

- -**Manifest** - -```typescript -{ - "type": "menuSectionSidebarApp", - "alias": "My.SectionSidebarApp.MyMenu", - "name": "My Menu Section Sidebar App", - "meta": { - "label": "My Sidebar Menu", - "sections": ["My.Section"], - "menu": "My.Menu" - } -} -``` - -**Default Element** - -```typescript -interface UmbMenuSectionSidebarAppElement {} -``` - -**Adding Items to an existing menu** - -This will make it possible to compose a sidebar menu from multiple Apps: - -

Composed sidebar menu

- -You can read more about this in the [Menu](../../../extending/section-trees/menu/) article. diff --git a/15/umbraco-cms/customizing/section-trees/sections/section-view.md b/15/umbraco-cms/customizing/section-trees/sections/section-view.md deleted file mode 100644 index 3b1d0d1ff90..00000000000 --- a/15/umbraco-cms/customizing/section-trees/sections/section-view.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -description: >- - Append a secondary view for a Section, use it for additional features or - information. ---- - -# Section View - -{% hint style="warning" %} -This page is a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice. -{% endhint %} - -

Section View

- -## Creating a custom Section View - -In this section, you can learn how to register and create a custom Section View for the Umbraco backoffice. - -### Manifest - -The manifest file can be created using either JSON or Typescript. Both methods are shown below. - -{% tabs %} - -{% tab title="Json" %} - -We can create the manifest using json in the `umbraco-package.json`. - -```json -{ - "type": "sectionView", - "alias": "My.SectionView", - "name": "My Section View", - "element": "./my-section.element.js", - "meta": { - "label": "My View", - "icon": "icon-add", - "pathname": "my-view" - }, - "conditions": [ - { - "alias": "Umb.Condition.SectionAlias", - "match": "My.Section", - } - ] -} -``` - -{% endtab %} - -{% tab title="Typescript" %} - - -The manifest can also be written in TypeScript. - -For this typescript example we used a [Backoffice Entry Point](../../extending-overview/extension-types/backoffice-entry-point) extension to register the manifests. - -```typescript -import { ManifestSectionView } from "@umbraco-cms/backoffice/extension-registry"; - -const sectionViews: Array = [ - { - type: "sectionView", - alias: "My.SectionView", - name: "My Section View", - element: () => import('./my-section.element.ts'), - meta: { - label: "My View", - icon: "icon-add", - pathname: "my-view", - }, - conditions: [ - { - alias: 'Umb.Condition.SectionAlias', - match: 'My.Section', - } - ] - } -] -``` - - {% endtab %} - -{% endtabs %} - - -### Lit Element - -Creating the Section View Element using a Lit Element. - - -**my-section.element.ts:** -```typescript -import { UmbLitElement } from "@umbraco-cms/backoffice/lit-element"; -import { css, html, customElement, property } from '@umbraco-cms/backoffice/external/lit'; - -@customElement('my-sectionview-element') -export class MySectionViewElement extends UmbLitElement { - - render() { - return html` - - Sectionview content goes here - - ` - } - - static override styles = [ - css` - :host { - display: block; - padding: 20px; - } - `, - ]; - -} - -export default MySectionViewElement; - -declare global { - interface HTMLElementTagNameMap { - 'my-sectionview-element': MySectionViewElement; - } -} - -``` diff --git a/15/umbraco-cms/customizing/section-trees/trees/README.md b/15/umbraco-cms/customizing/section-trees/trees/README.md deleted file mode 100644 index 705fe19ac59..00000000000 --- a/15/umbraco-cms/customizing/section-trees/trees/README.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -description: A guide to creating a custom tree in Umbraco ---- - -# Trees - -{% hint style="warning" %} -This page is a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice. -{% endhint %} - -The tree is a hierarchical structure of nodes and is registered in the Backoffice extension registry. A tree can be rendered anywhere in the Backoffice with the help of the umb-tree element. - -## Creating trees - -To Create a Tree in a section of the Umbraco backoffice, you need to take multiple steps: - -### Registering a tree - -The backoffice comes with two different tree item kinds out of the box: entity and fileSystem. - -Tree Manifest: - -```typescript -// TODO: add interface -{ - "type": "tree", - "alias": "My.Tree.Alias", - "name": "My Tree", - "meta": { - "repositoryAlias": "My.Repository.Alias" - } -}, -{ - "type": "treeItem", - "kind": "entity", - "alias": "My.TreeItem.Alias", - "name": "My Tree Item", - "conditions": { - "entityType": "my-entity-type", - }, -} -``` - -### Rendering a tree - -```typescript - -``` - -### Render a Custom Tree Item - -#### **The Tree Item Manifest** - -```typescript -{ - "type": "treeItem", - "alias": "Umb.TreeItem.Alias", - "name": "My Tree Item", - "element": "./my-tree-item.element.js", - "conditions": { - "entityType": "my-entity-type", - }, -}; -``` - -#### The Tree Item Element - -```typescript -import { css, html, nothing } from 'lit'; -import { customElement, property } from 'lit/decorators.js'; -import { UmbElementMixin } from '@umbraco-cms/backoffice/element-api'; -import { UmbMyTreeItemContext, MyTreeItemDataModel } from './my-tree-item.context'; - -@customElement('my-tree-item') -export class MyTreeItemElement extends UmbElementMixin(LitElement) { - private _item?: MyTreeItemDataModel; - @property({ type: Object, attribute: false }) - public get item() { - return this._item; - } - public set item(value: MyTreeItemDataModel | undefined) { - this._item = value; - this.#context.setTreeItem(value); - } - - #context = new UmbMyTreeItemContext(this); - - render() { - if (!this.item) return nothing; - return html` Some custom markup `; - } -} - -export default MyTreeItemElement; -``` - -#### The Tree Item Context - -```typescript -// TODO: auto-generate this from the interface -export interface UmbTreeItemContext { - host: UmbControllerHostElement; - unique?: string; - type?: string; - - treeItem: Observable; - hasChildren: Observable; - isLoading: Observable; - isSelectable: Observable; - isSelected: Observable; - isActive: Observable; - hasActions: Observable; - path: Observable; - - setTreeItem(treeItem: T | undefined): void; - - requestChildren(): Promise<{ - data: PagedResponse | undefined; - error: ProblemDetails | undefined; - asObservable?: () => Observable; - }>; - toggleContextMenu(): void; - select(): void; - deselect(): void; - constructPath(pathname: string, entityType: string, unique: string): string; -} -``` - -#### Extending the Tree Item Context base - -We provide a base class for the tree item context. This class provides some default implementations for the context. You can extend this class to overwrite any of the default implementations. - -```typescript -export class UmbMyTreeItemContext extends UmbTreeItemContextBase { - constructor(host: UmbControllerHostElement) { - super(host, (x: MyTreeItemDataModel) => x.unique); - } - - // overwrite any methods or properties here if needed -} -``` diff --git a/15/umbraco-cms/customizing/section-trees/trees/entity-actions.md b/15/umbraco-cms/customizing/section-trees/trees/entity-actions.md deleted file mode 100644 index b91de56a43c..00000000000 --- a/15/umbraco-cms/customizing/section-trees/trees/entity-actions.md +++ /dev/null @@ -1,216 +0,0 @@ ---- -description: Entity Actions perform an action on a specific item ---- - -# Entity Actions - -{% hint style="warning" %} -This page is a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice. -{% endhint %} - -{% hint style="info" %} -Entity Actions was previously called Tree Actions. -{% endhint %} - -Entity Actions is a feature that provides a generic place for secondary or additional functionality for an entity type. An entity type can be a media, document and so on. - -Items in an Umbraco Tree can have associated Actions. The actions visible to the currently logged in user can be controlled via User Permissions. - -You can set a User's permissions for each item in the Umbraco Content tree from the User Section of the Umbraco Backoffice. - -If you are developing a custom section or a custom Dashboard, you might want to display some different options. This depends on a User's permission set on a particular item. - -## Entity Actions in the UI - -
- -

Sidebar Context Menu

- - - -

Workspace Entity Action Menu

- -
- -
- -

Collection

- - - -

Pickers

- -
- -### Sidebar Context Menu - -Sidebar Context Menu is an entity action that can be performed on a menu item. For example in the content section you can perform some extra actions on the content such as sorting, moving, etc. - -

Default Entity Action in the Content Section

- -## Registering an Entity Action - -```typescript -import { extensionRegistry } from '@umbraco-cms/extension-registry'; -import { MyEntityAction } from './entity-action'; - -const manifest = { - type: 'entityAction', - alias: 'My.EntityAction', - name: 'My Entity Action', - weight: 10, - api: MyEntityAction, - forEntityTypes: ['my-entity'], - meta: { - icon: 'icon-add', - label: 'My Entity Action', - repositoryAlias: 'My.Repository', - }, -}; - -extensionRegistry.register(manifest); -``` - -**Default Element** - -```typescript -interface UmbEntityActionElement {} -``` - -### The Entity Action Class - -As part of the Extension Manifest you can attach a class that will be instanciated as part of the action. It will have access to the host element, a repository with the given alias and the unique (key etc) of the entity. - -The class either provides a getHref method, or an execute method. If the getHref method is provided, the action will use the link. Otherwise the `execute` method will be used. When the action is clicked the `execute` method on the api class will be run. When the action is completed, an event on the host element will be dispatched to notify any surrounding elements. - -Example of providing a `getHref` method: - -```typescript -import { UmbEntityActionBase } from '@umbraco-cms/backoffice/entity-action'; -import { UmbControllerHostElement } from '@umbraco-cms/backoffice/controller-api'; -import type { MyRepository } from './my-repository'; - -export class MyEntityAction extends UmbEntityActionBase { - constructor(host: UmbControllerHostElement, repositoryAlias: string, unique: string) { - super(host, repositoryAlias, unique); - } - - async getHref() { - return 'my-link/path-to-something'; - } -} -``` - -Example of providing a `execute` method: - -```typescript -import { UmbEntityActionBase } from '@umbraco-cms/backoffice/entity-action'; -import { UmbControllerHostElement } from '@umbraco-cms/backoffice/controller-api'; -import type { MyRepository } from './my-repository'; - -export class MyEntityAction extends UmbEntityActionBase { - constructor(host: UmbControllerHostElement, repositoryAlias: string, unique: string) { - super(host, repositoryAlias, unique); - } - - async execute() { - await this.repository.myAction(this.unique); - } -} -``` - -If any additional contexts are needed, these can be consumed from the host element: - -```typescript -import { UmbEntityActionBase } from '@umbraco-cms/backoffice/entity-action'; -import { UmbContextConsumerController } from '@umbraco-cms/controller'; -import { UMB_MODAL_SERVICE_CONTEXT } from '@umbraco-cms/modal'; -import { MyRepository } from './my-repository'; - -export class MyEntityAction extends UmbEntityActionBase { - constructor(host: UmbControllerHostElement, repositoryAlias: string, unique: string) { - super(host, repositoryAlias, unique); - - new UmbContextConsumerController(this.host, UMB_MODAL_SERVICE_CONTEXT, (instance) => { - this.#modalService = instance; - }); - } - ... -} -``` - -We currently have a couple of generic actions that can be used across silos, so we don't have to write the same logic again. These actions include copy, move, trash, delete, etc. We can add more as we discover the needs. - -## User Permission Codes - -Here is a list of the entity actions and associated user permission codes shipped by Umbraco CMS and add-on projects, such as Umbraco Deploy. This list also includes codes used by some community packages. - -If you are building a package or adding custom entity actions to your solution, it's important to pick a permission letter. Ensure that it doesn't clash with one of these. - -If you have created a package using a custom entity action, please consider providing an update to this documentation page. You can do this via a PR to the [documentation repository](https://github.com/umbraco/UmbracoDocs). This will allow other developers to discover and avoid using the same permission letter. - -Currently, we allow two extension points on the client for user permissions: - -* **Entity User Permissions** - Relates to an entity (example document). - -

Entity User Permissions UI

- -* **Granular User Permission** - Relates to a $type server schemaType. - -

Granular User Permission UI

- -Each permission comes with a set of verbs, that will be checked against client and server-side. - -The Core currently ships with entity user permission for documents. The permissions are as follows: - -| Current Backoffice Letter | Verb | -| ------------------------- | -------------------------------- | -| C | Umb.Document.Create | -| F | Umb.Document.Read | -| A | Umb.Document.Update | -| D | Umb.Document.Delete | -| I | Umb.Document.CreateBlueprint | -| N | Umb.Document.Notifications | -| U | Umb.Document.Publish | -| R | Umb.Document.Permissions | -| Z | Umb.Document.Unpublish | -| O | Umb.Document.Duplicate | -| M | Umb.Document.Move | -| S | Umb.Document.Sort | -| I | Umb.Document.CultureAndHostnames | -| P | Umb.Document.PublicAccess | -| K | Umb.Document.Rollback | -| V | Umb.DocumentRecycleBin.Restore | - -**Entity User Permissions** will be registered in the extension registry with a manifest with the following type. Example: - -```typescript -{ - "type": "entityUserPermission", - "alias": "Umb.UserPermission.Document.Rollback", - "name": "Document Rollback User Permission", - "meta": { - "entityType": "document", - "verbs": ["Umb.Document.Rollback"], - "labelKey": "actions_rollback", - "descriptionKey": "actionDescriptions_rollback", - "group": "administration", - }, - }, -``` - -**Granular permissions** will also be registered. It is possible to provide a custom element to build the needed UX for that type of permission: - -```typescript -{ - "type": "userGranularPermission", - "alias": "Umb.UserGranularPermission.Document", - "name": "Document Granular User Permission", - "element": "element.js", - "meta": { - "schemaType": "DocumentPermissionPresentationModel", - "label": "Documents", - "description": "Assign permissions to specific documents", - }, - }, -``` diff --git a/15/umbraco-cms/customizing/section-trees/trees/entity-bulk-actions.md b/15/umbraco-cms/customizing/section-trees/trees/entity-bulk-actions.md deleted file mode 100644 index 797b5aebc15..00000000000 --- a/15/umbraco-cms/customizing/section-trees/trees/entity-bulk-actions.md +++ /dev/null @@ -1,57 +0,0 @@ -# Entity Bulk Actions - -{% hint style="warning" %} -This page is a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice. -{% endhint %} - -**Entity Bulk Action:** Relates to an entity type: document, media, etc. Performs the action on a selection of items. - -

Entity Bulk Collection

- -## Registering an Entity Bulk Action - -```typescript -import { extensionRegistry } from '@umbraco-cms/extension-registry'; -import { MyEntityBulkAction } from './entity-bulk-action'; - -const manifest = { - type: 'entityBulkAction', - alias: 'My.EntityBulkAction', - name: 'My Entity Bulk Action', - weight: 10, - api: MyEntityBulkAction, - meta: { - icon: 'icon-add', - label: 'My Entity Bulk Action', - repositoryAlias: 'My.Repository', - }, - conditions: [ - { - alias: 'Umb.Condition.CollectionAlias', - match: 'my-collection-alias', - }, - ], -}; - -extensionRegistry.register(manifest); -``` - -## The Entity Bulk Action Class - -As part of the Extension Manifest you can attach a class that will be instantiated as part of the action. It will have access to the host element, a repository with the given alias and the unique (key etc) of the entity. When the action is clicked the `execute` method on the api class will be run. When the action is completed, an event on the host element will be dispatched to notify any surrounding elements. - -```typescript -import { UmbEntityBulkActionBase } from '@umbraco-cms/entity-action'; -import { UmbControllerHostElement } from '@umbraco-cms/backoffice/controller-api'; -import { MyRepository } from './my-repository'; - -export class MyEntityBulkAction extends UmbEntityBulkActionBase { - constructor(host: UmbControllerHostElement, repositoryAlias: string, selection: Array) { - super(host, repositoryAlias, selection); - } - - async execute() { - await this.repository?.myBulkAction(this.selection); - } -} -``` diff --git a/15/umbraco-cms/customizing/terminology.md b/15/umbraco-cms/customizing/terminology.md deleted file mode 100644 index 6fab899989a..00000000000 --- a/15/umbraco-cms/customizing/terminology.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -description: A list of some of the key concepts with working the Umbraco Backoffice. ---- - -# Terminology - -Understanding certain key concepts is essential when customizing the backoffice. These terminologies can help you decode the purpose of code effectively: - -* **Resource:** An API enables communication with a server. -* **Store:** An API representing data, generally coming from the server. Most stores would talk with one or more resources. You can read more about this in the [Store](foundation/working-with-data/store.md) article. -* **State:** A reactive container holding data, when data is changed all its Observables will be notified. You can read more about state and observables in the [States](foundation/working-with-data/states.md) article. - * **Observable:** An observable is the hook for others to subscribe to the data of a State. - * **Observe:** Observe describes what we do when subscribing to an Observable. -* **Context-API:** The name used to serve APIs (instances/classes) for a certain context in the DOM. An API that is served via the Context-API is called a Context. You can read more about this in the [Context API](foundation/working-with-data/context-api.md) article. - * **Context Provider:** One that provides a class instance as a Context API. - * **Context Consumer:** One that consumer subscribes to a class instance as a Context API. -* **Controller:** An abstract term for a thing that hooks into the lifecycle of an element. Many things in our system are Controllers. -* **Umbraco Controller:** Enables hosting controllers. Additionally, it provides a few shortcut methods for initializing core Umbraco Controllers. You can read more about this in the [Controllers](foundation/umbraco-element/controllers/) article. - * **Controller Host:** A class that can host controllers. - * **Controller Host Element:** The element that can host controllers. -* **Umbraco Element:** The `UmbLitElement` or `UmbElemenMixin` enables hosting controllers. Additionally, it provides a few shortcut methods for initializing core Umbraco Controllers. You can read more about this in the [Umbraco Element](foundation/umbraco-element/) article. - -Read more about various ways how to get started with extending the backoffice in the [Backoffice Setup](extending-overview/) article. diff --git a/15/umbraco-cms/customizing/ui-documentation.md b/15/umbraco-cms/customizing/ui-documentation.md deleted file mode 100644 index 2cea2d57f76..00000000000 --- a/15/umbraco-cms/customizing/ui-documentation.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -description: Find out more about Umbraco UI Library, UI API and Storybook. ---- - -# UI Documentation - -## UI Library and UI API - -With the UI Library, you get a collection of visual building blocks that consists of pieces to build any UI in Umbraco. Each component is a building block updating its display according to the data passed to it. - -{% hint style="info" %} -**Are you looking for the AngularJS documentation?** - -With Umbraco 14 the Umbraco backoffice has been rebuilt using Vite, Lit and Typescript. This means that AngularJS is no longer being used in Umbraco CMS, hence the removal of the corresponding documentation. -{% endhint %} - -With the UI API, you get a set of collections related to modules export, interfaces, and hierarchy. This includes code examples and much more that you can use to extend the backoffice. - -
Backoffice UI LibrarySee, test, and get a feel for the familiar backoffice components built using the new UI components.https://apidocs.umbraco.com/v14/ui/Documentations Icons_Umbraco_CMS_Fundamentals_Backoffice (1) (2).png
Backoffice UI APISee what all of the modules export, interfaces, hierarchy, code examples, and much more.https://apidocs.umbraco.com/v14/ui-api/index.htmlDocumentations Icons_Umbraco_CMS_Tutorials_the_Starter_Kit (1).png
- -## UI Icons - -The icons from the Umbraco backoffice are based on [Lucide Icons](https://lucide.dev/). The syntax for getting the icons starts with`icon-`. You can find the list of all icons in the [Icon registry list on Github](https://github.com/umbraco/Umbraco.CMS.Backoffice/tree/762e43b2f49ca483df9cfe28de20f31ca07bb22b/src/packages/core/icon-registry/icons). - -## UI Library Storybook - -The Umbraco UI Library is a set of web components that can be used to build Umbraco User Interfaces. The UI Library separates the user interface from Umbraco’s business logic and creates a unified user experience. This is done with coherent styling and naming, across all the Umbraco platforms and projects including the ones developed by you. - -[Storybook](https://uui.umbraco.com/) is an application that gathers all the components together of the UI Library. It holds the documentation for the components and showcases different use case scenarios. You can explore all the components through stories reflecting their use cases. - -Each story has interactive controls that allow you to change the state of the component in real time. Every publicly available property is editable in Storybook, so you can test out custom configurations and use cases. - -You can also modify the custom properties in the stylesheet to see how the component will look. Every story has a code example that you can copy and paste into your project. This will allow you to implement the components in your own packages and extensions. - -### Getting Started with the UI Library - -The [Storybook](https://uui.umbraco.com/) is the starting point for working with the Umbraco UI Library. The Storybook contains two tabs: - -1. Canvas - The Canvas tab allows to use the interactive controls. - -
-2. Docs - Here, you can find code examples for all the stories and use them in your markup. You can look it up by tag name or head to the project repository, where, in the packages folder, you will find all the component packages with all the necessary scripts and examples in the readme files. - -
- -### Install the UI Library Components - -You can download the UI Library package from [Github](https://github.com/umbraco/Umbraco.UI/tree/v1/contrib/packages). - -If you are installing a component via npm, there are two ways to import it: - -1. To import a specific component and register it at the same time, use the following command: - -```sql -import { UUIButtonElement } from '@umbraco-ui/uui-button'; -``` - -2. To build on top of the components functionality, you can extend its class: - -```sql -import { UUIButtonElement } from '@umbraco-ui/uui-button/lib/uui-button.element'; -``` - -For more information on installation, Content Delivery Networks (CDN), or included components, see the[Readme file in the Github](https://github.com/umbraco/Umbraco.UI#readme)project. - -### Import UI Library Components - -You can also work with the components on a code level. If you want to do so here is how you import it: - -```typescript -import { UUIButtonElement } from '@umbraco-cms/backoffice/external/uui'; -``` - -This requires that your Package has the `@umbraco-cms/backoffice` dependency. diff --git a/15/umbraco-cms/customizing/ui-localization.md b/15/umbraco-cms/customizing/ui-localization.md deleted file mode 100644 index bfb69d76144..00000000000 --- a/15/umbraco-cms/customizing/ui-localization.md +++ /dev/null @@ -1,235 +0,0 @@ ---- -description: Learn how to manage and use the Backoffice UI Localization files. ---- - -# Backoffice Localization - -This article describes how you can translate the Umbraco Backoffice UI into different languages. You can use the existing localizations from Umbraco or register your own localizations. You can also use the localization in your custom elements and controllers. - -## Registering Localization - -To register localizations to a language, you must add a new manifest to the Extension API. The manifest can be added through the `umbraco-package.json` file. Usually, the localization keys are provided through a JavaScript module. In this example, we will use a file named `en.js`: - -{% code title="umbraco-package.json" %} -```json -{ - "name": "MyPackage", - "extensions": [ - { - "type": "localization", - "alias": "MyPackage.Localize.EnUS", - "name": "English", - "meta": { - "culture": "en" - }, - "js": "/App_Plugins/MyPackage/Localization/en.js" - } - ] -} -``` -{% endcode %} - -{% hint style="info" %} -Read more about extensions in the [Package Manifest](package-manifest.md) article. -{% endhint %} - -### Layout of the Localization Files - -The localization files for the UI are JavaScript modules with a default export containing a key-value structure organized in sections. - -{% code title="/App_Plugins/MyPackage/Localization/en.js" %} -```js -export default { - section: { - key1: 'value1', - key2: 'value2', - }, -}; -``` -{% endcode %} - -The sections and keys will be formatted into a map in Umbraco with the format `section_key1` and `section_key2.` These form the unique key they are requested. - -If you do not have many translations, you can also choose to include them directly in the meta-object: - -{% code title="umbraco-package.json" lineNumbers="true" %} -```json -{ - "name": "MyPackage", - "extensions": [ - { - "type": "localization", - "alias": "MyPackage.Localize.EnUS", - "name": "English", - "meta": { - "culture": "en", - "translations": { - "section": { - "key1": "value1", - "key2": "value2" - } - } - }, - } - ] -} -``` -{% endcode %} - -In this case, the `en.js` file is not needed and we can remove the "js" property from the manifest. Only strings can be used in the meta-object. - -### Missing Localization Keys - -As Umbraco is an evolving product, new text is regularly added to the English version of these files. Therefore, some of the languages may no longer be up-to-date. - -If a key is not found in the current language, the fallback language will be used. The fallback language is **English** with the culture code **en**. - -If a translation is missing, the default value within `umb-localize` will be shown in the user interface: - -```html -Default value -``` - -Instead of showing the default value we can show the key alias if we set `debug="true"`: - -```html - -``` - -## Using the Localizations - -### Localize Element - -The following example shows how you can display localized text with the `umb-localize` element: - -```html - -``` - -{% hint style="info" %} -You can have a look and try out the element in the [UI API Docs](https://apidocs.umbraco.com/v14/ui/?path=/docs/api-localization-umblocalizeelement--docs). -{% endhint %} - -### **Localize Controller** - -In some situations, you need the localization as a variable that can be parsed. In this case, the Localization Controller can be used in your `element.ts` file. This can be setup in two ways: - -* Using [Umbraco Element](ui-localization.md#umbraco-element) -* Using [Umbraco Controller](ui-localization.md#umbraco-controller) - -#### Umbraco Element - -When using an [**Umbraco Element**](../extending/umbraco-element/)**,** the **Localization Controller** is already initialized on the `localize` property via the `UmbElementMixin`. - -```typescript -import { LitElement, css, html } from "lit"; -import { customElement } from "@umbraco-cms/backoffice/external/lit"; -import { UmbElementMixin } from "@umbraco-cms/backoffice/element-api"; - -export default class MyElement extends UmbElementMixin(LitElement) { - render() { - return html` - `; - } -} -``` - -The arguments will be passed to the function in the localization file if it is a function. - -#### Umbraco Controller - -If you are working with an Umbraco Controller, then you need to initialize the Localization Controller on your own via the `UmbLocalizationController`: - -```typescript -import { UmbControllerBase } from '@umbraco-cms/backoffice/class-api'; -import { UmbLocalizationController } from '@umbraco-cms/backoffice/localization-api'; - -export class MyController extends UmbControllerBase { - // Create a new instance of the controller and attach it to the element - #localize = new UmbLocalizationController(this); - - render() { - return html` `; - } -} -``` - -## Using arguments - -Sometimes you need to pass arguments to the localization to return different values based on the arguments. A localization value can be either a string or a function. Given a localization file like this, we can return different values based on the number of items: - -```javascript -export default { - section: { - numberOfItems: (count) => { - count = parseInt(count, 10); - if (count === 0) return 'Showing nothing'; - if (count === 1) return 'Showing only one item'; - return `Showing ${count} items`; - }, - }, -}; -``` - -{% hint style="info" %} -You can try out the arguments feature in the [UI API Docs](https://apidocs.umbraco.com/v14/ui/?path=/story/api-localization-umblocalizeelement--with-arguments). -{% endhint %} - -**Using the Localize Element** - -You can pass arguments to the localization by adding them as additional attributes: - -```html - -Showing items -``` - -The arguments will be passed to the function in the localization file if it is a function. The `args` attribute must be JSON-serializable and each array value will be passed to the function as an extra argument. - -**Using the Localize Controller** - -You can pass arguments to the localization by calling the `term` method with the arguments: - -```typescript -// Outputs: Showing 5 items -this.localize.term('section_numberOfItems', 5); -``` - -The arguments will be passed to the function in the localization file if it is a function. Each argument of `term` will be passed to the function as an extra argument. - -### Using placeholders - -You can also use placeholders in the localization keys to replace parts of the string with dynamic values. Placeholders are defined by curly braces `{0}` or percentage signs `%0%` in the localization key. The placeholders will be replaced one-to-one with the arguments passed to the localization. It works the same as the arguments feature, except you cannot calculate the value based on the arguments. - -Given a localization file like this: - -{% code title="en.js" %} -```javascript -export default { - section: { - numberOfItems: 'Showing {0} items', - }, -}; -``` -{% endcode %} - -You can use the same `args` attribute to pass the arguments: - -```html - - -``` - -## Examples - -You can add your own localization keys using the principles you have learned, and apply them in a number of ways: - -### Using localization in a custom element - -You can find a localization example in the [Adding localization to the dashboard](../tutorials/creating-a-custom-dashboard/adding-localization-to-the-dashboard.md) article. This will get you started with using localization in your custom elements. You can apply the same principles to all extensions. - -### Using localization in property descriptions and labels - -Property descriptions and labels can also be localized. They are formatted as Markdown and can contain localization keys using the built-in [Umbraco Flavored Markdown](../reference/umbraco-flavored-markdown.md) syntax. diff --git a/15/umbraco-cms/customizing/workspaces/README.md b/15/umbraco-cms/customizing/workspaces/README.md deleted file mode 100644 index da6f95eecaa..00000000000 --- a/15/umbraco-cms/customizing/workspaces/README.md +++ /dev/null @@ -1,24 +0,0 @@ -# Workspaces - -{% hint style="warning" %} -This page is a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice. -{% endhint %} - -A Workspace is the editor for a specific entity type. It can either be a simple view of data or a complex editor with multiple views. - -* A workspace is based on an entity type (e.g. content, media, member, etc.) and a unique string (ex: key). -* Most workspaces hold a draft state of an entity. It is a copy of the entity data that can be modified at runtime and sent to the server to be saved. -* A workspace can be a single view or consist of multiple views. -* A workspace should host a workspace context, with which anything within can communicate. - -

Workspace

- -```ts -interface UmbWorkspaceElement {} -``` - -## [Workspace Context](workspace-context.md) - -## [Workspace Views](workspace-editor-views.md) - -## [Workspace Actions](workspace-editor-actions.md) diff --git a/15/umbraco-cms/customizing/workspaces/workspace-context.md b/15/umbraco-cms/customizing/workspaces/workspace-context.md deleted file mode 100644 index b067667a3e0..00000000000 --- a/15/umbraco-cms/customizing/workspaces/workspace-context.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -description: Establish an extension to communicate across the application. ---- - -# Workspace Context - -{% hint style="warning" %} -This page is a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice. -{% endhint %} - -A Workspace context is a container for the data of a workspace. It is a wrapper around the data of the entity that the workspace is working on. It is responsible for loading and saving the data to the server. Workspace Contexts are used to bring additional context alongside the default context of a workspace. - -* A workspace context knows about its entity type (for example content, media, member, etc.) and holds its unique string (for example: key). -* Most workspace contexts hold a draft state of its entity data. It is a copy of the entity data that can be modified at runtime and sent to the server to be saved. - -If a workspace wants to utilize Property Editor UIs, then it must provide a variant context for the property editors. The variant-context is the generic interface between workspace and property editors. - -```ts -interface UmbWorkspaceContext {} -``` - -## Example of Workspace - -## Example of Workspace Context - -The API will be initiated with the same host as the default Workspace Context. - -```typescript -{ - type: 'workspaceContext', - alias: 'My.WorkspaceContext.Counter', - name: 'My Counter Context', - api: 'my-workspace-counter.context.js', - conditions: [ - { - alias: 'Umb.Condition.WorkspaceAlias', - match: 'Umb.Workspace.Document', - } - ] -} -``` - -The code of such an API file could look like this: - -```typescript -import { - UmbController, - UmbControllerHost, -} from "@umbraco-cms/backoffice/controller-api"; -import { UmbContextToken } from "@umbraco-cms/backoffice/context-api"; -import { UmbNumberState } from "@umbraco-cms/backoffice/observable-api"; - -export class MyContextApi extends UmbController { - #counter = new UmbNumberState(0); - readonly counter = this.#counter.asObservable(); - - constructor(host: UmbControllerHost) { - super(host); - this.provideContext(UMB_APP_CONTEXT, this); - } - - increment() { - this.#counter.next(this.#counter.value + 1); - } -} - -export const api = MyContextCounterApi; -``` - -{% hint style="info" %} -Context APIs have to be self-providing. To do so it has to be an Umbraco Controller. -{% endhint %} - -A Context Token for a Workspace Context Extension should look like this: - -```typescript -export const UMB_APP_CONTEXT = new UmbContextToken( - "UmbWorkspaceContext", - "My.WorkspaceContext.Counter" -); -``` - -We recommend using `UmbWorkspaceContext` as the Context Alias for your Context Token. This will ensure that the requester only retrieves this Context if it's present at their nearest Workspace Context. Use the Extension Manifest Alias as the API Alias for your Context Token. For more information, see the [Context API](../foundation/working-with-data/context-api.md) article. diff --git a/15/umbraco-cms/customizing/workspaces/workspace-editor-actions.md b/15/umbraco-cms/customizing/workspaces/workspace-editor-actions.md deleted file mode 100644 index 526ffa29c59..00000000000 --- a/15/umbraco-cms/customizing/workspaces/workspace-editor-actions.md +++ /dev/null @@ -1,55 +0,0 @@ -# Workspace Actions - -{% hint style="warning" %} -This page is a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice. -{% endhint %} - -Workspace actions are a set of functionalities or operations that can be performed within a workspace. These actions involve creating documents within the workspace, organizing and categorizing documents, publishing content and so on. - -Workspace action relates to a workspace alias (Umb.Workspace.Document) and has Access to the workspace context. - -

Workspace Actions

- -**JavaScript Manifest example** - -
import { extensionRegistry } from '@umbraco-cms/extension-registry';
-import { MyWorkspaceAction } from './my-workspace-action';
-
-const manifest = {
- type: 'workspaceAction',
- alias: 'My.WorkspaceAction',
- name: 'My Workspace Action',
- meta: {
-  label: 'My Action',
-  api: MyWorkspaceAction,
- },
- conditions: [
-  {
-   alias: 'Umb.Condition.WorkspaceAlias',
-   match: 'My.Workspace',
-  },
- ],
-};
-
-extensionRegistry.register(manifest);
-
- -## The Workspace Action Class - -As part of the Extension Manifest you can attach a class that will be instantiated as part of the action. It will have access to the host element and the Workspace Context. When the action is clicked the `execute` method on the API class will be run. When the action is completed, an event on the host element will be dispatched to notify any surrounding elements. - -```ts -import { UmbWorkspaceActionBase } from '@umbraco-cms/backoffice/workspace'; - -export class MyWorkspaceAction extends UmbWorkspaceActionBase { - execute() { - this.workspaceContext.myAction(this.selection); - } -} -``` - -**Default Element** - -```typescript -interface UmbWorkspaceActionElement {} -``` diff --git a/15/umbraco-cms/customizing/workspaces/workspace-editor-views.md b/15/umbraco-cms/customizing/workspaces/workspace-editor-views.md deleted file mode 100644 index 0a20a6245bd..00000000000 --- a/15/umbraco-cms/customizing/workspaces/workspace-editor-views.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -description: Append a view to any Workspace ---- - -# Workspace Views - -{% hint style="warning" %} -This page is a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice. -{% endhint %} - -{% hint style="info" %} -Workspace Views was previously called Content Apps. -{% endhint %} - -Workspace Views are customizable companion **tabs** with the ability to take place in any workspace. - -

Workspace Views

- -**In Content Section** - -With Workspace Views, editors can switch from editing 'Content' to accessing contextual information related to the item they are editing. - -The default workspace view is **'Info'** - displaying Links, History and Status of the current content item. - -## Example of a Workspace View - -1. Follow the [Vite Package Setup](../development-flow/vite-package-setup.md) by creating a new project folder called "`workspaceview`" in `App_Plugins`. -2. Create a manifest file named `umbraco-package.json` at the root of the `welcome-dashboard` folder. Here we define and configure our dashboard. -3. Add the following code to `umbraco-package.json`: - -{% code title="umbraco-package.json" lineNumbers="true" %} -```json -{ - "$schema": "../../umbraco-package-schema.json", - "name": "My workspace", - "version": "0.1.0", - "extensions": [ - { - "type": "workspaceView", - "alias": "My.WorkspaceView", - "name": "My Workspace View", - "element": "/App_Plugins/workspaceview/dist/workspaceview.js", - "meta": { - "label": "My Workspace View", - "pathname": "/my-workspace-view", - "icon": "icon-add" - }, - "conditions": [ - { - "alias": "Umb.Condition.WorkspaceAlias", - "match": "Umb.Workspace.Document" - } - ] - } - ] -} -``` -{% endcode %} - -4. Add the following code to the existing `my-element.ts` from the `src`folder: - -{% code title="my-element.ts" lineNumbers="true" %} -```typescript -import { LitElement, html, customElement, css } from "@umbraco-cms/backoffice/external/lit"; -import { UmbElementMixin } from "@umbraco-cms/backoffice/element-api"; - -@customElement('my-workspaceview') -export default class MyWorspaceViewElement extends UmbElementMixin(LitElement) { - - render() { - return html` - - Welcome to my newly created workspace view. - - ` - } - - static styles = css` - uui-box { - margin: 20px; - } - ` -} - -declare global { - interface HTMLElementTagNameMap { - 'my-workspaceview': MyWorspaceViewElement - } -} - -``` -{% endcode %} - -In the `workspaceview` folder run `npm run build` and then run the project. Then in the content section of the Backoffice you will see our new Workspace View: - -

Workspace View Example

- -{% hint style="info" %} -To see the Workspace View that we have created in the content section, first you will need to have some content created. -{% endhint %}