Skip to content

Commit 89fc4fa

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 89fc4fa

File tree

2 files changed

+89
-54
lines changed

2 files changed

+89
-54
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: 89 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,27 @@
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 %}
10-
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:
14-
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).
7+
Header App extensions 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.
178

189
<figure><img src="../../../.gitbook/assets/header-apps.svg" alt=""><figcaption><p>Header Apps</p></figcaption></figure>
1910

20-
## **Button Header App with Manifest**
11+
## Button Header App as a link
12+
## Registering a header app using a manifest
13+
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.
14+
15+
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.
2116

22-
Below you can find an example of how to setup a Header App using the manifest file.
17+
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.
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+
Header Apps can also be created using TypeScript. Examples of both approaches are shown below.
2720

21+
{% tabs %}
22+
{% tab title="Using the Package Manifest" %}
2823
{% code title="umbraco-package.json" lineNumbers="true" %}
29-
```typescript
24+
```json
3025
{
3126
"$schema": "../../umbraco-package-schema.json",
3227
"name": "My Header App",
@@ -37,7 +32,7 @@ Below you can find an example of how to setup a Header App using the manifest fi
3732
"alias": "My.HeaderApp",
3833
"name": "My Header App",
3934
"kind": "button",
40-
35+
"element": "/App_Plugins/header-app/dist/header-app.js",
4136
"meta": {
4237
"label": "Hello Umbraco",
4338
"icon": "icon-hearts",
@@ -48,25 +43,48 @@ Below you can find an example of how to setup a Header App using the manifest fi
4843
}
4944
```
5045
{% endcode %}
46+
{% endtab %}
47+
{% tab title="Using TypeScript" %}
48+
{% code title="my-element.ts" lineNumbers="true" %}
49+
Create an object that implements the `UmbExtensionManifest` interface, then register the extension with the `umbExtensionsRegistry` service.
50+
51+
```typescript
52+
import { umbExtensionsRegistry } from '@umbraco-cms/backoffice/extension-registry';
53+
54+
const manifest: UmbExtensionManifest = {
55+
type: "headerApp",
56+
alias: "My.HeaderApp.Documentation",
57+
name: "My Header App Documentation",
58+
kind: "button",
59+
meta: {
60+
label: "Hello Documentation",
61+
icon: "icon-addressbook",
62+
href: "https://docs.umbraco.com/"
63+
}
64+
};
5165

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.
66+
umbExtensionsRegistry.register(manifest);
67+
```
68+
{% endcode %}
69+
{% endtab %}
70+
{% endtabs %}
5571

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**:
72+
## Button Header App with deeper interactivity
5773

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>
74+
Extension authors can also create header apps that have more interactivity than a simple link.
5975

60-
## **Button Header App with JS/TS**
76+
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.
6177

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

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.
80+
<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>
6581

66-
1. Add a reference to the .js file. Update the `umbraco-package.json` with the following:
82+
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.
6783

84+
{% tabs %}
85+
{% tab title="Package Manifest" %}
6886
{% code title="umbraco-package.json" lineNumbers="true" %}
69-
```typescript
87+
```json
7088
{
7189
"$schema": "../../umbraco-package-schema.json",
7290
"name": "My Header App",
@@ -77,40 +95,57 @@ This is a continuation of the above steps from the **Button Header App with Mani
7795
"alias": "My.HeaderApp",
7896
"name": "My Header App",
7997
"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-
}
98+
"element": "/App_Plugins/MyPackage/server-services-header-app.js"
8699
}
87100
]
88101
}
89102
```
90103
{% 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" %}
104+
{% endtab %}
105+
{% tab title="TypeScript" %}
106+
{% code title="src/server-services-header.ts" lineNumbers="true" %}
107+
*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.*
95108
```typescript
96-
import { umbExtensionsRegistry } from '@umbraco-cms/backoffice/extension-registry';
109+
import { html, customElement } from "@umbraco-cms/backoffice/external/lit";
110+
import { UmbHeaderAppButtonElement } from "@umbraco-cms/backoffice/components";
111+
import { umbOpenModal, UMB_CONFIRM_MODAL } from "@umbraco-cms/backoffice/modal";
112+
113+
@customElement("server-services-header-app")
114+
export class ServerServicesHeaderAppElement extends UmbHeaderAppButtonElement {
115+
async #handleUserClick() {
116+
umbOpenModal(this, UMB_CONFIRM_MODAL, {
117+
data: {
118+
headline: "Would you like to disable all Server Services?",
119+
content:
120+
"This action can be undone, but only after all services have stopped.",
121+
color: "danger",
122+
confirmLabel: "Disable all services",
123+
},
124+
})
125+
.then(() => {
126+
console.log("User has approved");
127+
})
128+
.catch(() => {
129+
console.log("User has rejected");
130+
});
131+
}
97132

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/"
133+
override render() {
134+
return html`
135+
<uui-button
136+
@click=${this.#handleUserClick}
137+
look="primary"
138+
label="Server Services"
139+
compact
140+
>
141+
<uui-icon name="icon-server"></uui-icon>
142+
</uui-button>
143+
`;
107144
}
108-
};
145+
}
109146

110-
umbExtensionsRegistry.register(manifest);
147+
export default ServerServicesHeaderAppElement;
111148
```
112149
{% 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>
150+
{% endtab %}
151+
{% endtabs %}

0 commit comments

Comments
 (0)