Skip to content

Commit 4bb7fb2

Browse files
iOvergaardiOvergaard
authored
V15: Backoffice Entry Points (#6963)
* docs: adds a description to the article * docs: renames article and removes a duplicated paragraph * docs: adds more info on backoffice entry points and corrects many mistakes * docs: adds info about app entry points * docs: fix typo in reference to backofficeEntryPoint * docs: adds reference from backoffice entry point to bundle * docs: correct content-ref links
1 parent 663fb37 commit 4bb7fb2

File tree

6 files changed

+157
-25
lines changed

6 files changed

+157
-25
lines changed

‎15/umbraco-cms/SUMMARY.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -174,6 +174,7 @@
174174
* [Block Custom View](customizing/extending-overview/extension-types/block-custom-view.md)
175175
* [Bundle](customizing/extending-overview/extension-types/bundle.md)
176176
* [Kind](customizing/extending-overview/extension-types/kind.md)
177+
* [App Entry Point](customizing/extending-overview/extension-types/app-entry-point.md)
177178
* [Backoffice Entry Point](customizing/extending-overview/extension-types/backoffice-entry-point.md)
178179
* [Extension Conditions](customizing/extending-overview/extension-types/condition.md)
179180
* [Dashboards](customizing/extending-overview/extension-types/dashboard.md)

‎15/umbraco-cms/customizing/extending-overview/extension-registry/extension-manifest.md‎

Lines changed: 11 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -80,22 +80,26 @@ Read more about the `backofficeEntryPoint` extension type in the [Entry Point](e
8080

8181
Similar as `appEntryPoint` this runs as startup, the difference is that this runs before the user is logged in. Use this to initiate things before the user is logged in or to provide things for the Login screen.
8282

83+
Read more about the `appEntryPoint` extension type in the [App Entry Point](../extension-types/app-entry-point.md) article.
84+
8385
## Type intellisense
8486

8587
It is recommend to make use of the Type intellisense that we provide.
8688

8789
When writing your Manifest in TypeScript you should use the Type `UmbExtensionManifest`, see the [TypeScript setup](../../development-flow/typescript-setup.md) article to make sure you have Types correctly configured.
8890

89-
<pre class="language-typescript"><code class="lang-typescript">export const manifests: Array&#x3C;UmbExtensionManifest> = [
90-
<strong> {
91-
</strong> type: '...',
91+
{% code title="manifests.ts" %}
92+
```typescript
93+
export const manifests: Array<UmbExtensionManifest> = [
94+
{
95+
type: '...',
9296
alias: 'my.customization',
9397
name: 'My customization'
9498
...
95-
},
96-
...
97-
];
98-
</code></pre>
99+
}
100+
]
101+
```
102+
{% endcode %}
99103

100104
When writing the Umbraco Package Manifest you can use the JSON Schema located in the root of your Umbraco project called `umbraco-package-schema.json`
101105

‎15/umbraco-cms/customizing/extending-overview/extension-types/README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,9 +18,9 @@ The system provides Extension Types for certain needs and then there is a few th
1818

1919
The `bundle` type enables you to gather many extension manifests into one. These will be registered at startup.
2020

21-
### [Entry Point](backoffice-entry-point.md) <a href="#entry-point" id="entry-point"></a>
21+
### [Backoffice Entry Point](backoffice-entry-point.md) <a href="#entry-point" id="entry-point"></a>
2222

23-
The `Entry Point` type is used to execute the method of a JavaScript file when the backoffice is initialized. This file can be used to do anything, this enables more complex logic to take place on startup.
23+
The `backofficeEntryPoint` type is used to execute the method of a JavaScript file when the backoffice is initialized. This file can be used to do anything, this enables more complex logic to take place on startup.
2424

2525
### [Extension Conditions](condition.md) <a href="#conditions" id="conditions"></a>
2626

‎15/umbraco-cms/customizing/extending-overview/extension-types/app-entry-point.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
description: The App Entry Point extension type is used to run some JavaScript code before the user is logged in.
3+
---
4+
5+
# App Entry Point
6+
7+
This manifest declares a single JavaScript file that will be loaded and run when the Backoffice starts. Additionally, the code will also run on the login screen.
8+
9+
It performs the same function as the `backofficeEntryPoint` extension type, but the difference is that this runs before the user is logged in. Use this to initiate things before the user is logged in or to provide things for the Login screen.
10+
11+
Read more about `backofficeEntryPoint` to learn how to use it:
12+
13+
{% content-ref url="./backoffice-entry-point.md" %} . {% endcontent-ref %}

‎15/umbraco-cms/customizing/extending-overview/extension-types/backoffice-entry-point.md‎

Lines changed: 129 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,24 @@
1-
# Entry Point
1+
---
2+
description: The Backoffice Entry Point extension type is used to run some JavaScript code at startup.
3+
---
24

3-
{% hint style="warning" %}
4-
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.
5-
{% endhint %}
5+
# Backoffice Entry Point
66

7-
The `backofficeEntryPoint` extension type can be used to run some JavaScript code at startup.\
8-
The entry point declares a single JavaScript file that will be loaded and run when the Backoffice starts. In other words this can be used as an entry point for a package.
7+
This manifest declares a single JavaScript file that will be loaded and run when the Backoffice starts. In other words this can be used as an entry point for a package.
98

109
The `backofficeEntryPoint` extension is also the way to go if you want to load in external libraries such as jQuery, Angular, React, etc. You can use the `backofficeEntryPoint` to load in the external libraries to be shared by all your extensions. Additionally, **global CSS files** can also be used in the `backofficeEntryPoint` extension.
1110

12-
The Entry Point manifest type is used to register an entry point for the backoffice. An entry point is a single JavaScript file that is loaded when the backoffice is initialized. This file can be used to do anything, this enables more complex logic to take place on startup.
11+
{% hint style="info" %}
12+
See also the [App Entry Point](./app-entry-point.md) article for a similar extension type that runs before the user is logged in.
13+
{% endhint %}
1314

14-
**Register an entry point in the `umbraco-package.json` manifest**
15+
**Register a Backoffice Entry Point in the `umbraco-package.json` manifest**
1516

17+
{% code title="umbraco-package.json" %}
1618
```json
1719
{
1820
"name": "Name of your package",
21+
"alias": "My.Package",
1922
"extensions": [
2023
{
2124
"type": "backofficeEntryPoint",
@@ -25,23 +28,134 @@ The Entry Point manifest type is used to register an entry point for the backoff
2528
]
2629
}
2730
```
31+
{% endcode %}
32+
33+
**Base structure of the entry point file**
2834

29-
**Register additional UI extensions in the entry point file**
35+
{% hint style="info" %}
36+
All examples are in TypeScript, but you can use JavaScript as well. Make sure to use a bundler such as [Vite](../../development-flow/vite-package-setup.md) to compile your TypeScript to JavaScript.
37+
{% endhint %}
3038

39+
{% code title="index.ts" %}
3140
```typescript
32-
import { extensionRegistry } from "@umbraco-cms/extension-registry"
41+
import type { UmbEntryPointOnInit } from '@umbraco-cms/backoffice/extension-api';
42+
43+
/**
44+
* Perform any initialization logic when the Backoffice starts
45+
*/
46+
export const onInit: UmbEntryPointOnInit = (host, extensionsRegistry) => {
47+
// Your initialization logic here
48+
}
49+
50+
/**
51+
* Perform any cleanup logic when the Backoffice and/or the package is unloaded
52+
*/
53+
export const onUnload: UmbEntryPointOnUnload = (host, extensionsRegistry) => {
54+
// Your cleanup logic here
55+
}
56+
```
57+
{% endcode %}
58+
59+
{% hint style="info" %}
60+
The `onUnload` function is optional and can be used to perform cleanup logic when the Backoffice and/or the package is unloaded.
61+
{% endhint %}
62+
63+
## Examples
3364

34-
const manifest = {
35-
{
65+
### Register additional UI extensions in the entry point file
66+
67+
{% code title="index.ts" %}
68+
```typescript
69+
import type { UmbEntryPointOnInit } from '@umbraco-cms/backoffice/extension-api';
70+
71+
const manifest: UmbExtensionManifest = {
3672
type: '', // type of extension
3773
alias: '', // unique alias for the extension
3874
elementName: '', // unique name of the custom element
3975
js: '', // path to the javascript resource
4076
meta: {
41-
// additional props for the extension type
77+
// additional props for the extension type
4278
}
43-
}
4479
};
4580

46-
extensionRegistry.register(extension);
81+
export const onInit: UmbEntryPointOnInit = (host, extensionsRegistry) => {
82+
// Register the extension
83+
extensionRegistry.register(manifest);
84+
}
85+
86+
export const onUnload: UmbEntryPointOnUnload = (host, extensionsRegistry) => {
87+
// Unregister the extension (optional)
88+
extension.unregister(manifest);
89+
}
4790
```
91+
{% endcode %}
92+
93+
{% hint style="info" %}
94+
If you only need to register extensions, then consider using a [bundle](./bundle.md) type instead.
95+
{% endhint %}
96+
97+
### Register global CSS
98+
99+
An entry point is a good place to load global CSS files for the whole application. You can do this by creating a link element and appending it to the head of the document:
100+
101+
{% code title="index.ts" %}
102+
```typescript
103+
import type { UmbEntryPointOnInit } from '@umbraco-cms/backoffice/extension-api';
104+
105+
export const onInit: UmbEntryPointOnInit = (host, extensionsRegistry) => {
106+
const css = document.createElement('link');
107+
css.rel = 'stylesheet';
108+
css.href = '/App_Plugins/YourFolder/global.css';
109+
document.head.appendChild(css);
110+
}
111+
```
112+
{% endcode %}
113+
114+
Alternatively, you can import the CSS file directly in your JavaScript file:
115+
116+
{% code title="index.ts" %}
117+
```typescript
118+
import '/App_Plugins/YourFolder/global.css';
119+
```
120+
{% endcode %}
121+
122+
## Type IntelliSense
123+
124+
It is recommended to make use of the Type intellisense that we provide.
125+
126+
When writing your Manifest in TypeScript you should use the Type `UmbExtensionManifest`, see the [TypeScript setup](../../development-flow/typescript-setup.md) article to make sure you have Types correctly configured.
127+
128+
{% code title="index.ts" %}
129+
```typescript
130+
import type { UmbEntryPointOnInit } from '@umbraco-cms/backoffice/extension-api';
131+
132+
const manifests: Array<UmbExtensionManifest> = [
133+
{
134+
type: '...',
135+
alias: 'my.customization',
136+
name: 'My customization'
137+
...
138+
},
139+
...
140+
];
141+
142+
export const onInit: UmbEntryPointOnInit = (host, extensionsRegistry) => {
143+
// Register the extensions
144+
extensionRegistry.registerMany(manifests);
145+
}
146+
```
147+
{% endcode %}
148+
149+
## What's next?
150+
151+
See the Extension Types article for more information about all the different extension types available in Umbraco:
152+
153+
{% content-ref url="./" %}
154+
[README](./)
155+
{% endcontent-ref %}
156+
157+
Read about running code before log in using an `appEntryPoint`:
158+
159+
{% content-ref url="./app-entry-point.md" %}
160+
[App Entry Point](./app-entry-point.md)
161+
{% endcontent-ref %}

‎15/umbraco-cms/customizing/umbraco-package.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -130,7 +130,7 @@ These are the current types of UI Extensions:
130130
| Type | Description |
131131
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
132132
| authProvider | An authentication provider for [external login](../reference/security/external-login-providers.md). |
133-
| 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/backoffice-entry-point.md). |
133+
| 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/app-entry-point.md). |
134134
| 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/backoffice-entry-point.md). |
135135
| blockEditorCustomView | A custom view for a block in the block editor. |
136136
| 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. |

0 commit comments

Comments
 (0)