Portal Library
Contents
Functions to access portal functionality.
Usage
Add the following to your build.gradle
file:
dependencies {
include "com.enonic.xp:lib-portal:${xpVersion}"
}
In your JavaScript controller, add a require statement:
var portalLib = require('/lib/xp/portal');
You are now ready to use the library functionality.
Functions
assetUrl
This function generates a URL pointing to a static file.
Parameters
Name | Type | Description | |||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
params |
object |
Input parameters as JSON
|
Returns
string : The generated URL.
Example
var url = portalLib.assetUrl({
path: 'styles/main.css'
});
attachmentUrl
This function generates a URL pointing to an attachment.
Parameters
Name | Type | Description | ||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
params |
object |
Input parameters as JSON
|
Returns
string : The generated URL.
Example
var url = portalLib.attachmentUrl({
id: '1234',
download: true
});
componentUrl
This function generates a URL pointing to a component.
Parameters
Name | Type | Description | ||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
params |
object |
Input parameters as JSON
|
Returns
string : The generated URL.
Example
var url = portalLib.componentUrl({
component: 'main/0'
});
var expected = 'ComponentUrlParams{type=server, params={}, component=main/0}'
getComponent
This function returns the component corresponding to the current execution context. It is meant to be called from a layout or part controller.
Returns
object : The current component as JSON.
Example
var result = portalLib.getComponent();
log.info('Current component name = %s', result.name);
var 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
This function returns the content corresponding to the current execution context. It is meant to be called from a page, layout or part controller.
Returns
object : The current content as JSON.
Example
var result = portalLib.getContent();
log.info('Current content path = %s', result._path);
var 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
This function returns the id provider key corresponding to the current execution context.
Returns
object : The current id provider as JSON.
Example
var idProviderKey = portalLib.getIdProviderKey();
if (idProviderKey) {
log.info('Id provider key: %s', idProviderKey);
}
var expected = "myidprovider";
getMultipartForm
This function returns a JSON containing multipart items. If not a multipart request, then this function returns undefined
.
Returns
object : The multipart form items.
Example
var result = portalLib.getMultipartForm();
log.info('Multipart form %s', result);
var 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
This function returns a JSON containing a named multipart item. If the item does not exists, 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
var result = portalLib.getMultipartItem('item1');
log.info('Multipart item %s', result);
var expected = {
"name": "item1",
"fileName": "item1.jpg",
"contentType": "image/png",
"size": 10
};
getMultipartStream
This function 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
var stream1 = portalLib.getMultipartStream('item2');
var stream2 = portalLib.getMultipartStream('item2', 1);
getMultipartText
This function 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
var text = portalLib.getMultipartText('item1');
getSite
This function returns the parent site of the content corresponding to the current execution context. It is meant to be called from a page, layout or part controller.
Returns
object : The current site as JSON.
Example
var result = portalLib.getSite();
log.info('Current site name = %s', result._name);
var 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
This function returns the site configuration for this app in the parent site of the content corresponding to the current execution context. It is meant to be called from a page, layout or part controller.
Returns
object : The site configuration for current application as JSON.
Example
var result = portalLib.getSiteConfig();
log.info('Field value for the current site config = %s', result.Field);
var expected = {
"Field": 42
};
idProviderUrl
This function generates a URL pointing to an ID provider.
Parameters
Name | Type | Attributes | Description | |||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
params |
object |
<optional> |
Input parameters as JSON
|
Returns
string : The generated URL.
imagePlaceholder
This function generates a URL to an image placeholder.
Parameters
Name | Type | Description | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
params |
object |
Input parameters as JSON
|
Returns
string : Placeholder image URL.
Example
var url = portalLib.imagePlaceholder({
width: 32,
height: 24
});
var expected = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAYCAYAAACbU/80AAAAGUlEQVR42u3BAQEAAACCIP+vbkhAAQAA7wYMGAAB93LuRQAAAABJRU5ErkJggg==';
imageUrl
This function generates a URL pointing to an image.
Parameters
Name | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
params |
object |
Input parameters as JSON
|
Returns
string : The generated URL.
Example
var url = portalLib.imageUrl({
id: '1234',
scale: 'block(1024,768)',
filter: 'rounded(5);sharpen()'
});
loginUrl
This function generates a URL pointing to the login function of an ID provider.
Parameters
Name | Type | Attributes | Description | ||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
params |
object |
<optional> |
Input parameters as JSON
|
Returns
string : The generated URL.
logoutUrl
This function generates a URL pointing to the logout function of the application corresponding to the current user.
Parameters
Name | Type | Attributes | Description | |||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
params |
object |
<optional> |
Input parameters as JSON
|
Returns
string : The generated URL.
pageUrl
This function generates a URL pointing to a page.
Parameters
Name | Type | Description | |||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
params |
object |
Input parameters as JSON
|
Returns
string : The generated URL.
Example
var url = portalLib.pageUrl({
path: '/my/page',
params: {
a: 1,
b: [1, 2]
}
});
processHtml
This function replaces abstract internal links to images and internal content items contained in an HTML text with full URLs. It will also render 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
var html = portalLib.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
This function 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
var unsafeHtml = '<p><a href="https://example.com/" onclick="stealCookies()">Link</a></p>' +
'<iframe src="javascript:alert(\'XSS\');"></iframe>';
var sanitizedHtml = portalLib.sanitizeHtml(unsafeHtml);
var expected = '<p><a href="https://example.com/">Link</a></p>';
serviceUrl
This function generates a URL pointing to a service.
Parameters
Name | Type | Description | |||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
params |
object |
Input parameters as JSON
|
Returns
string : The generated URL.
Example
var url = portalLib.serviceUrl({
service: 'myservice',
params: {
a: 1,
b: 2
}
});
url
This function generates a URL.
Parameters
Name | Type | Description | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
params |
object |
Input parameters as JSON
|
Returns
string : The generated URL.
Example
var url = portalLib.url({
path: '/site/master/mysite',
params: {
a: 1,
b: 2
}
});