Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Layout selector (<umbLayoutSelector />)
Load indicator (<umbLoadIndicator />)
Property (<umbProperty />)
The Umbraco backoffice is built using AngularJS. The implementation is made up of many directives and services.
As of Umbraco 10, this section will no longer be updated.
Please refer to the article instead.
For any questions regarding the above, feel free to reach out at .
This section will be removed on Umbraco 14.
Generally, you can find information about these via the Backoffice UI API documentation. This part of the documentation is auto-generated from the Umbraco source code.
Below you can find more in-depth descriptions and examples of AngularJS directives and services.
Layout selector (<umbLayoutSelector />)
Load indicator (<umbLoadIndicator />)
Property (<umbProperty />)
When you have a list of items, you can use the umb-layout-selector directive to let users toggle between different layouts. For instance, in Umbraco's media archive, users can select between a grid-based layout (thumbnails) and a list-based layout (table).
The directive has three attributes:
layouts is used to indicate the available layouts that the user should be able to select.
active-layout is a reference to the layout currently being used.
on-layout-select is a callback function triggered when the user chooses another layout.
For a view utilizing this directive:
The HTML could look something like this:
You'd also need a controller for initializing the different values to be used for the directive:
For each layout:
name property indicates the visual name of the layout (eg. used when hovering over the layout in the selector)
icon is the CSS selector for the icon of the layout.
path attribute indicates a sort of alias, and is used internally for comparing the layouts.
Many web sites and web applications use a form of load indicator to indicate a busy state to the user. Throughout the backoffice, Umbraco uses three animated circles as a load indicator - eg. as shown below:
Umbraco internally does this via the <umb-load-indicator /> directive, which you can also use in your own views for the backoffice.
The directive doesn't have any parameters on it's own. Since you most likely only wish to show the load indicator during certain states of your code, you can control this either through ng-if or ng-show
Each layout should also have a selected property indicating whether a particular layout is enabled, and thereby visible in the selector.
For instance if your controller sets the loading variable to true during busy states:
The directive uses CSS and absolute position to center it self in. For instance, if you're also using the <umb-box-content /> directive, you can set it's position to relative:
As seen on the animation in the beginning of this page, the load indicator is centered in the white box.
<umb-load-indicator ng-if="vm.loading"></umb-load-indicator><div ng-controller="myController">
<umb-layout-selector layouts="layouts"
active-layout="activeLayout"
on-layout-select="selectLayout(layout)">
</umb-layout-selector>
</div>angular.module("umbraco").controller("myController", function ($scope) {
// Declare the available layouts
$scope.layouts = [
{
name: "Grid",
icon: "icon-thumbnails-small",
path: "gridpath",
selected : true
},
{
name: "List",
icon: "icon-list",
path: "listpath",
selected: true
}
];
// Declare the function called by the directive when user chooses another layout
$scope.selectLayout = function(layout) {
$scope.activeLayout = layout;
$scope.layouts.forEach(element => element.active = false);
layout.active = true;
};
// Select the first layout
$scope.selectLayout($scope.layouts[0]);
});<umb-box>
<umb-box-content style="height: 250px; position: relative;">
<umb-load-indicator />
</umb-box-content>
</umb-box>The umb-property directive can along with umb-property-editor be used for rendering property editors in the backoffice.
The two directives are typically used together. For instance, if your Angular model has an array of properties, your view could look something like:
<umb-property property="property" ng-repeat="property in properties">
<umb-property-editor model="property"></umb-property-editor>
</umb-property>Properties contains the model for each property. ng-repeat can be used to iterate over each property, passing them to the two directives via property and model attributes.
For a basic property with a textbox, the model for the property can be defined as:
var property = {
alias: "myProperty",
label: "My property",
description: "This is my property.",
value: "Cupcake ipsum dolor sit amet oat cake marzipan...",
view: "textbox"
};The view property specifies the URL to the property editor that should be used for this property. To use one of the built-in property editors in Umbraco, you can specify the alias (eg. textbox) rather than the full URL to the view (eg. /umbraco/Views/propertyeditors/textbox/textbox.html).
You can see a list of all the built-in property editors in the .
Editor service Service for opening and working with editors and overlays.
Events service Service for listening and sending broadcasts.
The Angular editorService service is the primary resource used for opening overlays and handling infinite editing. Besides the open and close functions, the service also contains functions for opening specialized overlays/editors - eg. contentPicker or mediaPicker.
The contentPicker function opens a Content Picker in infinite editing. Depending on the options, it may be used for picking a single content item or a set of content items. Options for the function is as following:
The Content Picker could be opened as:
This example snippet will open a new Multi Content Picker. If the user submits one or more content items, the name of each content item will be printed to the console. The user may also close the Content Picker without selecting any content items, in which case the close callback function is invoked.
The documentTypeEditor function of the editor service can be used for opening a new overlay for creating a new Document Type. It can also be used for editing an existing Document Type.
The function supports the following options:
An overlay for creating a new Document Type may be opened as:
Notice that both the id and create options must be specified. When the overlay submits, you'll be able to get the alias of the created Document Type through model.documentTypeAlias.
Opening an overlay for editing an existing Document Type can be opened as:
Setting the title of the page the user is working on is important for accessibility purposes. People using assistive technology need to know what they are maintaining. By setting the page title, people who work with multiple tabs will also find the page they were working on.
To use the directive call:
When the user navigates through the site there is some logic which sets the default page title this is based on:
The current section the user is in
The deployment environment
multiPicker
Indicates a boolean value for whether the editor should work as a single Content Picker (false) or a Multi Content Picker (true).
submit
Is a callback function when the user selects and submits one or more content items.
close
Is a callback function when the close button is clicked.
id
Indicates the numeric ID of the Document Type which should be opened for editing.
create
A boolean value indicating whether the overlay should be used for creating a new Document Type (opposed to editing an existing Document Type).
noTemplate
When part of a create-overlay, this option specifies whether the Document Type should be created without a corresponding Template.
submit
A callback function for when the user submits/saves the Document Type.
close
A callback function for when the close button is clicked.
editorService.contentPicker({
multiPicker: true,
submit: function(model) {
model.selection.forEach(item, function() {
console.log(item.name);
});
editorService.close();
},
close: function() {
editorService.close();
}
});editorService.documentTypeEditor({
id: -1,
create: true,
submit: function (model) {
console.log(model.documentTypeAlias);
editorService.close();
},
close: function () {
editorService.close();
}
});editorService.documentTypeEditor({
id: 1103,
submit: function (model) {
console.log(model.documentTypeAlias);
editorService.close();
},
close: function () {
editorService.close();
}
});The original title of the page is based on the section being edited and the host name.
The title to use will then be prefixed to the original title of the page.
To remove the title displayed and revert to the default title, pass in an empty string.
$scope.$emit("$changeTitle", title);
The events service allows different components in Umbraco to broadcast and listen for global events.
To broadcast an event, you can use the emit function. It takes two arguments, where the first is the name of the event - eg. featured.updated, and the second argument is an object or similar describing the event.
The second argument is optional, so if your use case doesn't need this, feel free to skip this argument.
The illustrate this function, you could have a controller with an updated function that is triggered by the view. In this dummy example, the function will increment the value of a property editor, and then use the events service to broadcast that the value was updated:
Another controller could then listen for broadcasts of your feature.updated event via the events service's on function, which takes the name of the event as the first argument, and a callback function as the second argument.
Then in the callback function, the first argument is the event it self, and the second argument is the object we pass on to the emit function when we're broadcasting:
Controllers are typically used by a specific component, so the controller will only be executed when such a component is inserted into the DOM. The controller will be executed for each component, so you may end of with multiple instances listening for the same event.
If you need to listen for events on a more global level, you can hook into the application startup using app.run(...):
Notice how the result of the on function is saved in an unsubscribe variable. When we add a listener via the on function, it's important to clean up after our selves when our component (here a controller) no longer exists - eg. when removed from the DOM.
In Angular, we can listen for the $destroy event in the current scope, and then unsubscribe from the events service by calling the unsubscribe variable as a function.
Alternatively, we could replace unsubscribe() with eventsService.unsubscribe(unsubscribe), but it does the same thing - so calling the variable as a function directly may be preferred as it's shorter.
Below you'll find a list of events broadcasted by the Umbraco codebase. The list may not be complete, so kindly help updating the list should you find an event that isn't listed.
When the Umbraco application is ready
When Umbraco our your custom code makes a request to the server via the $http service, Umbraco listens for the x-umb-user-modified header in the response. In can be used to tell the Umbraco backoffice that the current user has been modified, in which case Umbraco knows that it should refetch the user data.
When the clipboard in local storage is updated
When an editor is opened
When an editor is closed
When all editors are closed
When the language resource file is loaded from the server
When an overlay is opened
When an overlay is closed
When upload of a file starts
When upload of a file ends
When the user presses CTRL + S
When tours are loaded
When user starts a tour
When user ends a tour
When a tour is disabled
When user completes a tour
When loading a tree node fails
When a tree node is removed
When the user is logged out
When user is trying to log in, but have not start nodes
When user is successfully authenticated
When user data is refetched from the server
When the app is initialized
When the toggle is initialized
When the toggle is clicked
When a new row is added
When a new control is added
When the grid is initializing
When the grid is initialized
When a language is deleted
Setting the page title
Available from 8.4.0
For more information see
angular.module("umbraco").controller("MyController", function($scope, eventsService) {
$scope.updated = function() {
$scope.model.value++;
eventsService.emit("feature.updated", { value: $scope.model.value });
};
});angular.module("umbraco").controller("MyOtherController", function($scope, eventsService) {
$scope.count = 0;
// Subscribe to the event
var unsubscribe = eventsService.on("feature.updated", function(event, args) {
$scope.count = args.value;
});
// When the scope is destroyed we need to unsubscribe
$scope.$on("$destroy", function () {
unsubscribe();
});
});app.run(function (eventsService) {
$scope.count = 0;
// Subscribe to the event
var unsubscribe = eventsService.on("feature.updated", function(event, args) {
$scope.count = args.value;
});
});eventsService.emit("app.ready", data);if (headers["x-umb-user-modified"]) {
eventsService.emit("app.userRefresh");
}eventsService.emit("clipboardService.storageUpdate");var args = {
editors: editors,
editor: editor
};
eventsService.emit("appState.editors.open", args);var args = {
editors: editors,
editor: closedEditor
};
// emit event to let components know an editor has been removed
eventsService.emit("appState.editors.close", args);var args = {
editors: editors,
editor: null
};
eventsService.emit("appState.editors.close", args);eventsService.emit("editorState.changed", { entity: entity });eventsService.emit("localizationService.updated", response.data);eventsService.emit("appState.overlay", overlay);eventsService.emit("appState.overlay", null);eventsService.emit("rte.file.uploading");eventsService.emit("rte.file.uploaded");eventsService.emit("rte.shortcut.save");eventsService.emit("appState.tour.updatedTours", tours);eventsService.emit("appState.tour.start", tour);eventsService.emit("appState.tour.end", tour);eventsService.emit("appState.tour.end", tour);eventsService.emit("appState.tour.complete", tour);eventsService.emit("treeService.treeNodeLoadError", { error: reason });eventsService.emit("treeService.removeNode", { node: treeNode });const args = { isTimedOut: isTimedOut };
eventsService.emit("app.notAuthenticated", args);var result = { errorMsg: errorMsg, user: data, authenticated: false, lastUserId: lastUserId, loginType: "credentials" };
eventsService.emit("app.notAuthenticated", result);var result = { user: data, authenticated: true, lastUserId: lastUserId, loginType: "credentials" };
eventsService.emit("app.authenticated", result);if (args && args.broadcastEvent) {
//broadcast a global event, will inform listening controllers to load in the user specific data
eventsService.emit("app.authenticated", result);
}eventsService.emit("app.reInitialize");eventsService.emit("toggleValue", { value: scope.checked });eventsService.emit("toggleValue", { value: !scope.checked });eventsService.emit("grid.rowAdded", { scope: $scope, element: $element, row: row });eventsService.emit("grid.itemAdded", { scope: $scope, element: $element, cell: cell, item: newControl });eventsService.emit("grid.initializing", { scope: $scope, element: $element });eventsService.emit("grid.initialized", { scope: $scope, element: $element });eventsService.emit("editors.languages.languageDeleted", args);$scope.$emit("$changeTitle", title);