Docs Developer Site
Developer Docs Enonic Development Kit next Libraries Admin library

Admin library

Contents

This API provides admin-related functions.

Usage

Add the following to your build.gradle file:

dependencies {
  include xplibs.admin
}

Add the import statement to your code:

import adminLib from '/lib/xp/admin';

You are now ready to use the API.

Functions

getInstallation

Returns the installation name.

Parameters

None

Returns

string : The installation name.

Example

import {getInstallation} from '/lib/xp/admin';

const name = getInstallation();

getVersion

Returns the version of the XP installation.

Parameters

None

Returns

string : The version number of the XP runtime.

Example

import {getVersion} from '/lib/xp/admin';

const version = getVersion();

getToolUrl

Returns the URL for an admin tool of a specific application.

Parameters

Name Type Description

application

string

Full application name (f.ex, com.enonic.app.main).

tool

string

Name of the tool inside an app (f.ex, main).

Returns

string : URL of the requested admin tool.

Example

import {getToolUrl} from '/lib/xp/admin';

const url = getToolUrl('com.enonic.app.main', 'main');

getHomeToolUrl

Returns the URL for the Home admin tool.

Parameters

getHomeToolUrl() takes a single, optional params object with these properties:

Name Type Description

type

string

Optional. URL type. Either server (server-relative URL) or absolute. Default is server.

Returns

string : The URL pointing to the Home admin tool.

Example

import {getHomeToolUrl} from '/lib/xp/admin';

const url = getHomeToolUrl({type: 'absolute'});

extensionUrl

Returns the URL for an admin extension.

Parameters

extensionUrl() takes a single params object with these properties:

Name Type Description

application

string

Application key that provides the extension.

extension

string

Name of the extension.

type

string

Optional. URL type. Either server (server-relative URL) or absolute. Default is server.

params

object

Optional. Custom query parameters to append to the URL.

Returns

string : URL of the requested extension.

Example

import {extensionUrl} from '/lib/xp/admin';

const url = extensionUrl({
    application: 'com.enonic.app.main',
    extension: 'launcher',
    type: 'absolute',
    params: {
        id: '42'
    }
});

setTopic

XPXP8.1.08.1.0 Sets the state of an admin events topic owned by this application.

Admin pages subscribe to topics over the admin:events API, and this application publishes to them with sendToTopic. See Admin events for how a page connects.

A topic is addressed by its canonical name, <application-key>:<name>, which the platform composes from the calling application and the local name given here. An application can only set and publish to its own topics.

A non-empty allow registers the topic, or updates the list of an already registered one, in which case current subscribers are re-evaluated and those no longer allowed are denied and dropped. An empty allow array clears the registration: publishing then fails and new subscriptions are denied, while existing subscriptions and the topic’s sequence numbering persist and resume if the topic is set again. The registration is also cleared when the application stops.

Parameters

setTopic() takes a single params object with these properties:

Name Type Description

name

string

Local topic name: 1-255 characters, no :, no whitespace.

allow

string | string[]

Principal keys allowed to subscribe, in addition to role:system.admin, which may always subscribe. An empty array clears the topic registration.

Returns

string : The canonical topic name, <application-key>:<name>, which subscribers address.

Example

Register the topic from main.ts, so that it exists on every node before any page subscribes:

main.ts
import {setTopic, sendToTopic} from '/lib/xp/admin';
import {listener} from '/lib/xp/event';

setTopic({
    name: 'contentChanged',
    allow: 'role:cms.admin'
});

listener({
    type: 'node.updated',
    localOnly: false,
    callback: () => sendToTopic('contentChanged')
});

sendToTopic

XPXP8.1.08.1.0 Publishes a message to an admin events topic owned by this application.

The message is delivered to the sockets on this node holding an acknowledged subscription to the topic, stamped with a per-topic sequence number that lets a subscriber count what it missed. Delivery is best effort.

The message is not distributed over the cluster. Subscribers on other nodes receive it only if the application publishes on those nodes too.

Publishing from an event listener registered in main.ts does exactly that: main.ts runs on every node, so each node’s listener publishes to its own subscribers. Distribution is then the event’s concern - see local versus distributed semantics - and each subscriber receives one message rather than one per node.

Parameters

Name Type Description

name

string

Local topic name, as passed to setTopic.

message

object | array | string | number | boolean

Optional. Message data. Must be serializable to JSON and must not contain null values. Defaults to an empty object.

Returns

Nothing.

Example

import {sendToTopic} from '/lib/xp/admin';

sendToTopic('contentChanged', {
    project: 'intranet',
    count: 3
});

Admin events

XPXP8.1.08.1.0 A topic is of no use until an admin page subscribes to it. The admin:events API carries every subscription of a page over one websocket, and serves the browser client that speaks it.

Mount the API on the admin tool that needs it, in the tool’s descriptor:

apis:
  - "admin:events"

Pass the API url to the page from the tool’s implementation:

import {apiUrl} from '/lib/xp/portal';

const eventsUrl = apiUrl({api: 'admin:events'});

In the browser, import the client the API serves and subscribe by canonical topic name:

const {connect} = await import(`${eventsUrl}/client.js`);

connect({
    onEvent: event => console.log('message', event.topic, event.data),
    onLoss: loss => console.log('missed', loss.count, 'messages of', loss.topic)
}).subscribe('com.example.myapp:contentChanged');

connect subscribes through a shared worker started from the client’s own url, so every admin page of the browser that loads it shares one worker, and with it one socket. Where shared workers are unavailable the client opens a socket of the page’s own instead. A connection receives only the topics it subscribed to.

onLoss reports messages that did not arrive: count is how many, or null when that cannot be known, such as after a reconnect to another node. A page that only refreshes its data can treat an event and a loss the same way.

widgetUrl

Deprecated — use extensionUrl instead. This function will be removed in future versions.

Returns the URL for a widget. Equivalent to calling extensionUrl with extension set to the widget name.

Parameters

widgetUrl() takes a single params object with these properties:

Name Type Description

application

string

Application key that provides the widget.

widget

string

Name of the widget.

type

string

Optional. URL type. Either server (server-relative URL) or absolute. Default is server.

params

object

Optional. Custom query parameters to append to the URL.

Returns

string : URL of the requested widget.

Contents

Contents