Skip to content

Commit 9ed2f75

Browse files
bszymanbszyman
committed
Revamp documentation for 'Header Apps' in Umbraco, simplifying explanations, restructuring content, and providing updated examples using both manifest and TypeScript approaches. Added a new section on interactive header apps and included a custom example.
1 parent 1403423 commit 9ed2f75

File tree

2 files changed

+87
-53
lines changed

2 files changed

+87
-53
lines changed

‎16/umbraco-cms/.gitbook/assets/header-apps-custom.png‎

90.1 KB
Loading

‎16/umbraco-cms/customizing/extending-overview/extension-types/header-apps.md‎

Lines changed: 87 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,25 @@
11
---
2-
description: Example how to work with extension registry
2+
description: Place single-purpose extensions in the top-level navigation bar, next to the user profile avatar.
33
---
44

55
# Header Apps
66

7-
{% hint style="warning" %}
8-
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.
9-
{% endhint %}
7+
Header apps appear next to the user profile and the global search icon in the top right of Umbraco’s Backoffice. Extension authors can create custom header apps to add globally accessible functionality to the Backoffice.
108

11-
A header app appears next to the user profile and global search icon on the top-right corner of Umbraco's backoffice.
12-
13-
In this article, you can find an example of an extension registry. This example details the creation of a Header App in two ways, similar to how the extension registry can be created:
9+
<figure><img src="../../../.gitbook/assets/header-apps.svg" alt=""><figcaption><p>Header Apps</p></figcaption></figure>
1410

15-
1. [Using a manifest file](header-apps.md#button-header-app-with-manifest).
16-
2. [Using the JavaScript/TypeScript file](header-apps.md#button-header-app-with-js-ts).
11+
## Button Header App as a link
1712

18-
<figure><img src="../../../.gitbook/assets/header-apps.svg" alt=""><figcaption><p>Header Apps</p></figcaption></figure>
13+
## Registering a header app using a manifest
1914

20-
## **Button Header App with Manifest**
15+
Extension authors can create header apps that link to resource both inside and outside the backoffice. Header apps can be created using a manifest or using TypeScript.
2116

22-
Below you can find an example of how to setup a Header App using the manifest file.
17+
To create a link-style header app, define a `headerApp` extension in the `umbraco-package.json` file. Be sure to include `meta.label` and `meta.icon` so that your header app appears when you reload the backoffice.
2318

24-
1. Follow the [Vite Package Setup](../../development-flow/vite-package-setup.md) to create a header app and name it "`header-app`" when using the guide.
25-
2. Create a manifest file named `umbraco-package.json` at the root of the `header-app` folder. Here we define and configure our dashboard.
26-
3. Add the following code to `umbraco-package.json`:
19+
If `meta.href` is defined, the header app will function as a link. The link will open in a new tab if the href value is a full url (complete with a protocol scheme, ex: https://), otherwise it will open in the same tab.
2720

2821
{% code title="umbraco-package.json" lineNumbers="true" %}
29-
```typescript
22+
```json
3023
{
3124
"$schema": "../../umbraco-package-schema.json",
3225
"name": "My Header App",
@@ -37,7 +30,7 @@ Below you can find an example of how to setup a Header App using the manifest fi
3730
"alias": "My.HeaderApp",
3831
"name": "My Header App",
3932
"kind": "button",
40-
33+
"element": "/App_Plugins/header-app/dist/header-app.js",
4134
"meta": {
4235
"label": "Hello Umbraco",
4336
"icon": "icon-hearts",
@@ -49,24 +42,48 @@ Below you can find an example of how to setup a Header App using the manifest fi
4942
```
5043
{% endcode %}
5144

52-
* First we define the type which is a `headerApp`. Then we add a unique alias and a name to define the extension UI.
53-
* Then we can define what kind of extension it is, where in this case we can use a pre-defined element called button.
54-
* The button requires some metadata: an icon, label of the button (name of the button) and a link which opens once clicked.
45+
### Registering the header app using TypeScript
46+
47+
Header app extensions can also be registered using TypeScript.
48+
49+
Create an object that implements the `UmbExtensionManifest` interface, then register the extension with the `umbExtensionsRegistry` service.
50+
51+
{% code title="my-element.ts" lineNumbers="true" %}
52+
```typescript
53+
import { umbExtensionsRegistry } from '@umbraco-cms/backoffice/extension-registry';
54+
55+
const manifest: UmbExtensionManifest = {
56+
type: "headerApp",
57+
alias: "My.HeaderApp.Documentation",
58+
name: "My Header App Documentation",
59+
kind: "button",
60+
meta: {
61+
label: "Hello Documentation",
62+
icon: "icon-addressbook",
63+
href: "https://docs.umbraco.com/"
64+
}
65+
};
66+
67+
umbExtensionsRegistry.register(manifest);
68+
```
69+
{% endcode %}
5570

56-
4. In the `header-app` folder run `npm run build` and then run the project. Then in the backoffice you will see our new Header App extension with **heart icon**:
71+
## Button Header App with deeper interactivity
5772

58-
<figure><img src="../../../.gitbook/assets/header-app-example.png" alt=""><figcaption><p>Header App in the Backoffice registered via Manifest File</p></figcaption></figure>
73+
Extension authors can also create header apps that have more interactivity than a simple link.
5974

60-
## **Button Header App with JS/TS**
75+
By creating a custom component, extension authors can control how the button renders itself and how it behaves when clicked. This allows header apps to control navigation, open modals, or perform other actions.
6176

62-
Below you can find an example of how to setup a Header App using the TypeScript file.
77+
For example, this is how the current user header app is able to present a modal when clicked.
6378

64-
This is a continuation of the above steps from the **Button Header App with Manifest** example. We will register a new Header App directly from the .ts file.
79+
<figure><img src="../../../.gitbook/assets/header-apps-custom.png" alt=""><figcaption><p>The current user modal is presented from a header app</p></figcaption></figure>
6580

66-
1. Add a reference to the .js file. Update the `umbraco-package.json` with the following:
81+
In order for a header app to have some functionality, extension authors will need to define behavior by creating a JavaScript or TypeScript component. Once the component has been created, it will need to be registered in the header app's `element` property.
6782

83+
{% tabs %}
84+
{% tab title="Package Manifest" %}
6885
{% code title="umbraco-package.json" lineNumbers="true" %}
69-
```typescript
86+
```json
7087
{
7188
"$schema": "../../umbraco-package-schema.json",
7289
"name": "My Header App",
@@ -77,40 +94,57 @@ This is a continuation of the above steps from the **Button Header App with Mani
7794
"alias": "My.HeaderApp",
7895
"name": "My Header App",
7996
"kind": "button",
80-
"element": "/App_Plugins/header-app/dist/header-app.js",
81-
"meta": {
82-
"label": "Hello Umbraco",
83-
"icon": "icon-hearts",
84-
"href": "https://umbraco.com/"
85-
}
97+
"element": "/App_Plugins/MyPackage/server-services-header-app.js"
8698
}
8799
]
88100
}
89101
```
90102
{% endcode %}
91-
92-
2. Replace the content of the `src/my-element.ts file` with the following:
93-
94-
{% code title="my-element.ts" lineNumbers="true" %}
103+
{% endtab %}
104+
{% tab title="TypeScript" %}
105+
{% code title="src/server-services-header.ts" lineNumbers="true" %}
95106
```typescript
96-
import { umbExtensionsRegistry } from '@umbraco-cms/backoffice/extension-registry';
107+
import { html, customElement } from "@umbraco-cms/backoffice/external/lit";
108+
import { UmbHeaderAppButtonElement } from "@umbraco-cms/backoffice/components";
109+
import { umbOpenModal, UMB_CONFIRM_MODAL } from "@umbraco-cms/backoffice/modal";
110+
111+
@customElement("server-services-header-app")
112+
export class ServerServicesHeaderAppElement extends UmbHeaderAppButtonElement {
113+
async #handleUserClick() {
114+
umbOpenModal(this, UMB_CONFIRM_MODAL, {
115+
data: {
116+
headline: "Would you like to disable all Server Services?",
117+
content:
118+
"This action can be undone, but only after all services have stopped.",
119+
color: "danger",
120+
confirmLabel: "Disable all services",
121+
},
122+
})
123+
.then(() => {
124+
console.log("User has approved");
125+
})
126+
.catch(() => {
127+
console.log("User has rejected");
128+
});
129+
}
97130

98-
const manifest: UmbExtensionManifest = {
99-
type: "headerApp",
100-
alias: "My.HeaderApp.Documentation",
101-
name: "My Header App Documentation",
102-
kind: "button",
103-
meta: {
104-
label: "Hello Documentation",
105-
icon: "icon-addressbook",
106-
href: "https://docs.umbraco.com/"
131+
override render() {
132+
return html`
133+
<uui-button
134+
@click=${this.#handleUserClick}
135+
look="primary"
136+
label="Server Services"
137+
compact
138+
>
139+
<uui-icon name="icon-server"></uui-icon>
140+
</uui-button>
141+
`;
107142
}
108-
};
143+
}
109144

110-
umbExtensionsRegistry.register(manifest);
145+
export default ServerServicesHeaderAppElement;
111146
```
112147
{% endcode %}
113-
114-
3. In the `header-app` folder run `npm run build` and then run the project. Then in the backoffice you will see our new Header App extension with **address book** **icon**:
115-
116-
<figure><img src="../../../.gitbook/assets/header-app-example-ts.png" alt=""><figcaption><p>Header App in Backoffice registered via ts File</p></figcaption></figure>
148+
*This example assumes that the extension author has transpiled the above TypeScript code into a JavaScript file. The name and location of this file should match the `element` property in the manifest.*
149+
{% endtab %}
150+
{% endtabs %}

0 commit comments

Comments
 (0)