This page is a work in progress. It will be updated as the software evolves.
Most of BackOffice is based on Extensions making it crucial to understand how to register your own extensions. This introduction will give you an outline of the abilities of the extension registry.
The extension registry is a global registry that can be accessed and changed at anytime while Backoffice is running.
To provide new UI to backoffice, you need to register them via an extension manifest. This has to initially happen on the server, via a JSON Package Manifest. This will enable you to register one or more extensions.
The abilities of the extensions rely on the specific extension type. The Type sets the scene for what the extension can do and what it needs to be utilized.
Some extension types rely on a reference to other extensions.
Most extension types support conditions. Defining conditions enables you to control when and where the extension is available.
The kinds feature enables you to base your extension registration on a preset. A kind provides the base manifest that you like to extend.
A Package is declared via an Umbraco Package Manifest. This describes the Package and declares one or more UI Extensions.
This page is a work in progress. It will be updated as the software evolves.
An extensions registry is a registration of an UI extension. It can be manipulated at any time, meaning we can add or remove extensions at run-time.
Declaring a new extension is done using an extension manifest depending where you are declaring it:
Via a manifest JSON file on the server.
In JavaScript/TypeScript file.
These two options can be combined by defining a small extension in a JSON Manifest. This uses the extension type backofficeEntryPoint
or bundle
to register a JS file, which then registers the rest of the extensions.
The necessary properties that any extension manifest needs are:
type
- The type defines the type and purpose of the extension. It is used to determine where the extension will be used and defines the data needed for this manifest.
alias
- The alias is used to identify the extension. This has to be unique for each extension.
name
- The name of the extension. This is used to identify the extension in the UI.
Extension conditions are used to determine if an extension should be used or not. Many of the Extension Types support conditions, but not all of them.
This page is a work in progress. It will be updated as the software evolves.
All given conditions for an extension must be valid for an extension to be utilized.
In the following example we define the manifest for a Workspace Action, this action will only be available in the workspace with the alias My.Example.Workspace
.
The conditions are defined as an array of conditions. Each condition is an object with the following properties:
alias
- The alias of the condition to utilize.
...
- The rest of the properties of the object are specific to the condition.
In the above example the Umb.Condition.SectionAlias
condition is used, this condition takes a property match
which must be set to the alias of the section to match.
The following conditions are available out of the box, for all extension types that support conditions.
Umb.Condition.SectionAlias
- Checks if the current section alias matches the one specified.
Umb.Condition.WorkspaceAlias
- Checks if the current workspace alias matches the one specified.
You can make your own conditions by creating a class that implements the UmbExtensionCondition
interface.
This has to be registered in the extension registry, like this:
TODO: Make an example that will work from JSON (not a direct reference to the class).
A kind extension provides the preset for other extensions to use
This page is a work in progress. It will be updated as the software evolves.
A kind is matched with a specific type. When another extension uses that type and kind it will inherit the preset manifest of the kind extension.
The registration of Kinds is done in the same manner as the registration of other extensions. But the format of it is different. Let's take a look at an example of how to implement the Kind registration
for a Header App Button Kind.
In the following example, a kind is registered. This kind provides a default element for extensions utilizing this kind.
This enables other extensions to use this kind and inherit the manifest properties defined in the kind.
In this example a Header App is registered without defining an element, this is possible because the registration inherits the elementName from the kind.
The root properties of this object define the Kind registration
. Then the manifest property holds the preset for the extension using this kind to be based upon. This object can hold the property values that make sense for the Kind.
For the kind to be used, it needs to match up with the registration of the extension using it. This happens when the extension uses a type, which matches the value of matchType
of the Kind. As well the extension has to utilize that kind, by setting the value of kind
to the value of matchKind
the Kind.
This page is a work in progress. It will be updated as the software evolves.
The backofficeEntryPoint
extension type can be used to run some JavaScript code at startup.
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.
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.
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.
Register an entry point in a JSON manifest
Register additional UI extensions in the entry point file
This page is a work in progress. It will be updated as the software evolves.
The bundle
extension type enables you to gather many extension manifests into one.
Its points to a single JavaScript file that via JavaScript Modules, exports or re-exports Extension Manifests written in JavaScript.
This means that it can be used as the entry point for a package.