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