The events service allows different components in Umbraco to broadcast and listen for global events.

Using the events service in your custom code

Broadcasting an event

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:

angular.module("umbraco").controller("MyController", function($scope, eventsService) {

    $scope.updated = function() {
        $scope.model.value++;
        eventsService.emit("feature.updated", { value: $scope.model.value });
    };

});

Listening for an event

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:

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();
    });

});

Listening for events globally

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(...):

app.run(function (eventsService) {

    $scope.count = 0;

    // Subscribe to the event
    var unsubscribe = eventsService.on("feature.updated", function(event, args) {
        $scope.count = args.value;
    });

});

Unsubscribing from an event

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.

Events in Umbraco

Below you'll find a list of events broadcasted by the Umbraco codebase. The list may not be complete, so please help updating the list should you find an event that isn't listed.

Umbraco application

Init

When the Umbraco application is ready

eventsService.emit("app.ready", data);

Security interceptor

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.

if (headers["x-umb-user-modified"]) {
    eventsService.emit("app.userRefresh");
}

Services

Clipboard service

When the clipboard in local storage is updated

eventsService.emit("clipboardService.storageUpdate");

Editor service

When an editor is opened

var args = {
    editors: editors,
    editor: editor
};

eventsService.emit("appState.editors.open", args);

When an editor is closed

var args = {
    editors: editors,
    editor: closedEditor
};

// emit event to let components know an editor has been removed
eventsService.emit("appState.editors.close", args);

When all editors are closed

var args = {
    editors: editors,
    editor: null
};

eventsService.emit("appState.editors.close", args);

Editor State service

eventsService.emit("editorState.changed", { entity: entity });

Localization service

When the language resource file is loaded from the server

eventsService.emit("localizationService.updated", response.data);

Overlay service

When an overlay is opened

eventsService.emit("appState.overlay", overlay);

When an overlay is closed

eventsService.emit("appState.overlay", null);

TinyMCE service

When upload of a file starts

eventsService.emit("rte.file.uploading");

When upload of a file ends

eventsService.emit("rte.file.uploaded");

When the user presses CTRL + S

eventsService.emit("rte.shortcut.save");

Tours

When tours are loaded

eventsService.emit("appState.tour.updatedTours", tours);

When user starts a tour

eventsService.emit("appState.tour.start", tour);

When user ends a tour

eventsService.emit("appState.tour.end", tour);

When a tour is disabled

eventsService.emit("appState.tour.end", tour);

When user completes a tour

eventsService.emit("appState.tour.complete", tour);

Tree service

When loading a tree node fails

eventsService.emit("treeService.treeNodeLoadError", { error: reason });

When a tree node is removed

eventsService.emit("treeService.removeNode", { node: treeNode });

User service

When the user is logged out

const args = { isTimedOut: isTimedOut };
eventsService.emit("app.notAuthenticated", args);

When user is trying to log in, but have not start nodes

var result = { errorMsg: errorMsg, user: data, authenticated: false, lastUserId: lastUserId, loginType: "credentials" };
eventsService.emit("app.notAuthenticated", result);

When user is successfully authenticated

var result = { user: data, authenticated: true, lastUserId: lastUserId, loginType: "credentials" };
eventsService.emit("app.authenticated", result);

When user data is refetched from the server

if (args && args.broadcastEvent) {
    //broadcast a global event, will inform listening controllers to load in the user specific data
    eventsService.emit("app.authenticated", result);
}

Util service

When the app is initialized

eventsService.emit("app.reInitialize");

Directives

Toggle directive

When the toggle is initialized

eventsService.emit("toggleValue", { value: scope.checked });

When the toggle is clicked

eventsService.emit("toggleValue", { value: !scope.checked });

Controllers

Grid controller

When a new row is added

eventsService.emit("grid.rowAdded", { scope: $scope, element: $element, row: row });

When a new control is added

eventsService.emit("grid.itemAdded", { scope: $scope, element: $element, cell: cell, item: newControl });

When the grid is initializing

eventsService.emit("grid.initializing", { scope: $scope, element: $element });

When the grid is initialized

eventsService.emit("grid.initialized", { scope: $scope, element: $element });

Languages overview controller

When a language is deleted

eventsService.emit("editors.languages.languageDeleted", args);

Other

Setting the page title

Available from 8.4.0

$scope.$emit("$changeTitle", title);

For more information see Change title

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:

$scope.$emit("$changeTitle", title);

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

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.