Portal API
Contents
API to access functions related to rendering.
Usage
Add the following to your build.gradle file:
dependencies {
include "com.enonic.xp:lib-portal:${xpVersion}"
}
Add the import statement to your controller:
import portalLib from '/lib/xp/portal';
You are now ready to use the API.
Functions
assetUrl
Starting from XP 7.15.0 assetUrl is deprecated and will be removed in future versions. lib-asset and lib-static are introduced as a replacement.
Generates URL to a static file.
Parameters
| Name | Type | Description | |||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
params |
object |
Input parameters as JSON
|
Returns
string : The generated URL.
Example
import {assetUrl} from '/lib/xp/portal';
const url = assetUrl({
path: 'styles/main.css'
});
attachmentUrl
Generates URL to an attachment.
Parameters
| Name | Type | Description | ||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
params |
object |
Input parameters as JSON
|
Returns
string : The generated URL.
Example
import {attachmentUrl} from '/lib/xp/portal';
const url = attachmentUrl({
id: '1234',
download: true
});
componentUrl
Generates URL to a page component.
Parameters
| Name | Type | Description | ||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
params |
object |
Input parameters as JSON
|
Returns
string : The generated URL.
Example
import {componentUrl} from '/lib/xp/portal';
const url = componentUrl({
component: 'main/0'
});
const expected = 'ComponentUrlParams{type=server, params={}, component=main/0}'
getComponent
Returns component in the current execution context. It is meant to be called from a layout or a part controller.
Returns
object : The current component as JSON.
Example
import {getComponent} from '/lib/xp/portal';
const result = getComponent();
log.info('Current component name = %s', result.name);
const expected = {
path: "/main/0",
type: "layout",
descriptor: "myapplication:mylayout",
config: {
a: "1"
},
regions: {
bottom: {
components: [
{
path: "/main/0/bottom/0",
type: "part",
descriptor: "myapplication:mypart",
config: {
a: "1"
}
}
],
name: "bottom"
}
}
};
getContent
Returns content in the current execution context. It is meant to be called from a page, a layout or a part controller.
Returns
object : The current content as JSON.
Example
import {getContent} from '/lib/xp/portal';
const result = getContent();
log.info('Current content path = %s', result._path);
const expected = {
_id: "123456",
_name: "mycontent",
_path: "/a/b/mycontent",
creator: "user:system:admin",
modifier: "user:system:admin",
createdTime: "1970-01-01T00:00:00Z",
modifiedTime: "1970-01-01T00:00:00Z",
type: "base:unstructured",
displayName: "My Content",
hasChildren: false,
language: "en",
valid: false,
data: {
a: "1"
},
x: {},
page: {},
attachments: {},
publish: {}
};
getIdProviderKey
Returns the key of ID provider in the current execution context.
Returns
object : The current ID provider as JSON.
Example
import {getIdProviderKey} from '/lib/xp/portal';
const idProviderKey = getIdProviderKey();
if (idProviderKey) {
log.info('Id provider key: %s', idProviderKey);
}
const expected = "myidprovider";
getMultipartForm
Returns a JSON containing multipart items. If not a multipart request, then this function returns undefined.
Returns
object : The multipart form items.
Example
import {getMultipartForm} from '/lib/xp/portal';
const result = getMultipartForm();
log.info('Multipart form %s', result);
const expected = {
item1: {
name: "item1",
fileName: "item1.jpg",
contentType: "image/png",
size: 10
},
item2: [
{
name: "item2",
fileName: "image1.png",
contentType: "image/png",
size: 123
},
{
name: "item2",
fileName: "image2.jpg",
contentType: "image/jpeg",
size: 456
}
]
};
getMultipartItem
Returns a JSON containing a named multipart item. If the item does not exist, it returns undefined.
Parameters
| Name | Type | Attributes | Description |
|---|---|---|---|
|
name |
string |
Name of the multipart item |
|
|
index |
number |
<optional> |
Optional zero-based index. It should be specified if there are multiple items with the same name |
Returns
object : The named multipart form item.
Example
import {getMultipartItem} from '/lib/xp/portal';
const result = getMultipartItem('item1');
log.info('Multipart item %s', result);
const expected = {
name: "item1",
fileName: "item1.jpg",
contentType: "image/png",
size: 10
};
getMultipartStream
Returns a data stream for a named multipart item.
Parameters
| Name | Type | Attributes | Description |
|---|---|---|---|
|
name |
string |
Name of the multipart item |
|
|
index |
number |
<optional> |
Optional zero-based index. It should be specified if there are multiple items with the same name |
Returns
object : Stream of multipart item data.
Example
import {getMultipartStream} from '/lib/xp/portal';
const stream1 = getMultipartStream('item2');
const stream2 = getMultipartStream('item2', 1);
getMultipartText
Returns the multipart item data as text.
Parameters
| Name | Type | Attributes | Description |
|---|---|---|---|
|
name |
string |
Name of the multipart item |
|
|
index |
number |
<optional> |
Optional zero-based index. It should be specified if there are multiple items with the same name |
Returns
string : Text for multipart item data.
Example
import {getMultipartText} from '/lib/xp/portal';
const text = getMultipartText('item1');
getSite
Returns the parent site of a content in the current execution context. It is meant to be called from a page, a layout or a part controller.
Returns
object : The current site as JSON.
Example
import {getSite} from '/lib/xp/portal';
const result = getSite();
log.info('Current site name = %s', result._name);
const expected = {
_id: "100123",
_name: "my-content",
_path: "/my-content",
type: "base:unstructured",
hasChildren: false,
valid: false,
data: {
siteConfig: {
applicationKey: "myapplication",
config: {
Field: 42
}
}
},
x: {},
page: {},
attachments: {},
publish: {}
};
getSiteConfig
Returns configuration of the parent site for a content in the current execution context. It is meant to be called from a page, a layout or a part controller.
Returns
object : The site configuration for current application as JSON.
Example
import {getSiteConfig} from '/lib/xp/portal';
const result = getSiteConfig();
log.info('Field value for the current site config = %s', result.Field);
const expected = {
Field: 42
};
idProviderUrl
Generates URL to an ID provider.
Parameters
| Name | Type | Attributes | Description | |||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
params |
object |
<optional> |
Input parameters as JSON
|
Returns
string : The generated URL.
imagePlaceholder
Generates URL of an image placeholder with a specified size.
Parameters
| Name | Type | Description | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
params |
object |
Input parameters as JSON
|
Returns
string : Placeholder image URL.
Example
import {imagePlaceholder} from '/lib/xp/portal';
const url = imagePlaceholder({
width: 32,
height: 24
});
const expected = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAYCAYAAACbU/80AAAAGUlEQVR42u3BAQEAAACCIP+vbkhAAQAA7wYMGAAB93LuRQAAAABJRU5ErkJggg==';
imageUrl
Generates URL to an image.
Parameters
| Name | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
params |
object |
Input parameters as JSON
|
Returns
string : The generated URL.
Example
import {imageUrl} from '/lib/xp/portal';
const url = imageUrl({
id: '1234',
scale: 'block(1024,768)',
filter: 'rounded(5);sharpen()'
});
loginUrl
Generates URL to the login endpoint of an ID provider.
Parameters
| Name | Type | Attributes | Description | ||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
params |
object |
<optional> |
Input parameters as JSON
|
Returns
string : The generated URL.
logoutUrl
Generates URL to the logout endpoint of ID provider in the current context.
Parameters
| Name | Type | Attributes | Description | |||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
params |
object |
<optional> |
Input parameters as JSON
|
Returns
string : The generated URL.
pageUrl
Generates URL to a content page.
Parameters
| Name | Type | Description | |||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
params |
object |
Input parameters as JSON
|
Returns
string : The generated URL.
Example
import {pageUrl} from '/lib/xp/portal';
const url = pageUrl({
path: '/my/page',
params: {
a: 1,
b: [1, 2]
}
});
processHtml
Resolves internal links to images and internal content items contained in an HTML text and replaces them with correct URLs. It will also process embedded macros.
When outputting processed HTML in Thymeleaf, use attribute data-th-utext="${processedHtml}". |
Parameters
| Name | Type | Description | |||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
params |
object |
Input parameters as JSON
|
Returns
string : The processed HTML.
Example
import {processHtml} from '/lib/xp/portal';
const html = processHtml({
value: '<a href="content://123" target="">Content</a>' +
'<a href="media://inline/123" target="">Inline</a>' +
'<a href="media://download/123" target="">Download</a>' +
'<img src="image://123"/>',
imageWidths: [32, 480, 800]
});
sanitizeHtml
Sanitizes an HTML string by stripping all potentially unsafe tags and attributes.
| HTML sanitization can be used to protect against cross-site scripting (XSS) attacks by sanitizing any HTML code submitted by a user. |
Parameters
| Name | Type | Description |
|---|---|---|
|
html |
string |
HTML string value to process |
Returns
string : The sanitized HTML.
Example
import {sanitizeHtml} from '/lib/xp/portal';
const unsafeHtml = '<p><a href="https://example.com/" onclick="stealCookies()">Link</a></p>' +
'<iframe src="javascript:alert(\'XSS\');"></iframe>';
const sanitizedHtml = sanitizeHtml(unsafeHtml);
const expected = '<p><a href="https://example.com/">Link</a></p>';
serviceUrl
Generates URL to a service.
Parameters
| Name | Type | Description | |||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
params |
object |
Input parameters as JSON
|
Returns
string : The generated URL.
Example
import {serviceUrl} from '/lib/xp/portal';
const url = serviceUrl({
service: 'myservice',
params: {
a: 1,
b: 2
}
});
url
Generates URL to a resource.
Parameters
| Name | Type | Description | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
params |
object |
Input parameters as JSON
|
Returns
string : The generated URL.
Example
import {url as buildUrl} from '/lib/xp/portal';
const url = buildUrl({
path: '/site/master/mysite',
params: {
a: 1,
b: 2
}
});