Portal library
Contents
API to access functions related to rendering.
Usage
Add the following to your build.gradle file:
dependencies {
include xplibs.portal
}
Add the import statement to your code:
import portalLib from '/lib/xp/portal';
You are now ready to use the API.
Functions
apiUrl
Generates a URL pointing to a Universal API. Picks the right URL form based on the calling context — a service-point under the active service when called from a site, webapp, or admin tool, and /api/ otherwise.
Parameters
| Name | Type | Description | ||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
params |
object |
Input parameters as JSON
|
Returns
string : The generated URL.
Example
import {apiUrl} from '/lib/xp/portal';
const url = apiUrl({
api: 'com.example.myapp:myapi',
path: '/items',
params: {
id: '42'
}
});
assetUrl
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.
If name is provided, XP will try to find an attachment by the unique name and give an exception if it’s not found. If name is empty but label is provided, XP will try to find an attachment with the provided label (will return the first one if several were found, or give an exception if none were found). If both name and label are empty, XP will generate attachment url only for a binary content with 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
});
baseUrl
Generates a base URL.
Parameters
| Name | Type | Description | ||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
params |
object |
Input parameters as JSON
|
Returns
string : The generated URL.
Example
import {baseUrl} from '/lib/xp/portal';
const url = baseUrl({
type: 'server',
path: '/path',
project: 'explicit-project',
branch: 'explicit-branch'
});
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'
});
getComponent
Returns the component in the current execution context. Meant to be called from a layout or part.
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 the content in the current execution context. Meant to be called from a page, layout, or part.
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
string|null : The current ID provider key, or null if no ID provider is bound to the current context.
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 the request is not multipart, an empty object is returned.
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 null.
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. If the item does not exist, it returns null.
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. If the item does not exist, it returns null.
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 the content in the current execution context. Meant to be called from a page, layout, or part.
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 the configuration of the parent site for the content in the current execution context. Meant to be called from a page, layout, or part.
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
HTTP services are deprecated in XP 8 in favor of Universal APIs. Use apiUrl for new code; serviceUrl() is retained for backward compatibility with legacy services in src/main/resources/services/. |
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
}
});