Application API
Contents
API for fetching and manipulating applications.
Usage
Add the following to your build.gradle file:
dependencies {
include "com.enonic.xp:lib-app:${xpVersion}"
}Add the import statement to your controller:
import appLib from '/lib/xp/app';You are now ready to use the API.
Functions
get
Returns an installed application. If a local and a virtual app are both installed with the specified key, then the local one will take precedence and will be returned in the result.
Parameters
| Name | Type | Description | ||||||
|---|---|---|---|---|---|---|---|---|
|
params |
object |
JSON with parameters
|
Returns
object : (Application) Property object of an installed application with the specified key, or null if the application was not found.
Example
import {get as getApp} from '/lib/xp/app';
const application = getApp({key: 'my-app-key'});
if (application) {
log.info('Application name = %s', application.displayName);
} else {
log.info('Application not found');
}const expected = {
key: 'my-app',
displayName: 'app display name',
vendorName: 'vendor name',
vendorUrl: 'https://vendor.url',
url: 'https://myapp.url',
version: '1.0.0',
systemVersion: '4.2.3-SNAPSHOT',
minSystemVersion: '2.0.0',
maxSystemVersion: '3.0.0',
modifiedTime: '2020-09-25T10:00:00Z',
started: true,
system: false
};list
Fetches all installed applications. If a local and a virtual app are both installed with the same key, then the local one will take precedence and will be returned in the result.
Returns
object[] : (Application[]) Array of applications' property objects, or an empty array if there are no installed applications.
Example
import {list} from '/lib/xp/app';
const apps = list();const expected = [
{
key: 'app1',
displayName: 'app display name',
vendorName: 'vendor name',
vendorUrl: 'https://vendor.url',
url: 'https://myapp.url',
version: '1.0.0',
systemVersion: '1.21.3',
minSystemVersion: '2.0.0',
maxSystemVersion: '3.0.0',
modifiedTime: '2020-09-25T10:00:00Z',
started: true,
system: false
},
{
key: 'app2',
displayName: 'app display name 2',
vendorName: 'vendor name 2',
vendorUrl: 'https://vendor2.url',
url: 'https://myapp2.url',
version: '4.1.2',
systemVersion: '1.2.33-SNAPSHOT',
minSystemVersion: '5.3.11',
maxSystemVersion: '3.0.6',
modifiedTime: '2021-09-25T10:00:00Z',
started: false,
system: true
}
];getDescriptor
Returns descriptor of an installed application.
Parameters
| Name | Type | Description | ||||||
|---|---|---|---|---|---|---|---|---|
|
params |
object |
JSON with parameters
|
Returns
object : (ApplicationDescriptor) Application descriptor.
Example
import {getDescriptor} from '/lib/xp/app';
const descriptor = getDescriptor({key: 'my-app-key'});const expected = {
key: 'my-app',
description: 'my app description',
icon: {
data: {},
mimeType: 'image/png',
modifiedTime: '2021-12-03T10:15:30Z'
}
};createVirtualApplication
Creates a virtual application (along with its schema repository nodes) with the specified key.
Parameters
| Name | Type | Description | ||||||
|---|---|---|---|---|---|---|---|---|
|
params |
object |
JSON with params
|
Returns
object : (Application) Property object of the created application.
Example
my-app-key key:
import {createVirtualApplication} from '/lib/xp/app';
const app = createVirtualApplication({
key:'my-app-key'
});deleteVirtualApplication
Removes a virtual application with the specified key.
Parameters
| Name | Type | Description | ||||||
|---|---|---|---|---|---|---|---|---|
|
params |
object |
JSON with params
|
Returns
boolean : true if deletion succeeded, otherwise false.
Example
my-app-key key:
import {deleteVirtualApplication} from '/lib/xp/app';
const result = deleteVirtualApplication({
key:'my-app-key'
});getApplicationMode
Fetches mode of an application with the specified key.
Parameters
| Name | Type | Description | ||||||
|---|---|---|---|---|---|---|---|---|
|
params |
object |
JSON with params
|
Returns
string : Application mode. Can be one of the following types:
-
bundled- an installed and active application, no virtual app with the same key exists; -
virtual- a "virtual", node-based application, no bundled app with the same key exists; -
augmented- both bundled and virtual application co-exist with the same application key.
| Installed but disabled bundled applications are considered missing. |
Example
my-app-key key:
import {getApplicationMode} from '/lib/xp/app';
const result = getApplicationMode({
key:'my-app-key'
});Type Definitions
Application
Type
object
Properties
| Name | Type | Description |
|---|---|---|
|
key |
string |
Application key |
|
displayName |
string |
Display name |
|
vendorName |
string |
Vendor name |
|
vendorUrl |
string |
Vendor url |
|
url |
string |
Url |
|
version |
string |
Version |
|
systemVersion |
string |
System version |
|
minSystemVersion |
string |
Min system version |
|
maxSystemVersion |
string |
Max system version |
|
modifiedTime |
object |
Modified time |
|
started |
boolean |
|
|
system |
boolean |
|
ApplicationDescriptor
Type
object
Properties
| Name | Type | Description |
|---|---|---|
|
key |
string |
Application key |
|
description |
`string |
Application description |
|
icon |
Application icon |
Icon
Type
object
Properties
| Name | Type | Description |
|---|---|---|
|
data |
object |
icon stream data |
|
mimeType |
string |
icon mime type |
|
modifiedTime |
string |
icon modified time |
