portal

Functions to access portal functionality.

Example
var portalLib = require('/lib/xp/portal');

Methods

(static) assetUrl(params) → {string}

This function generates a URL pointing to a static file.

Parameters:
Name Type Description
params object

Input parameters as JSON.

Properties
Name Type Attributes Default Description
path string

Path to the asset.

application string <optional>

Other application to reference to. Defaults to current application.

type string <optional>
server

URL type. Either server (server-relative URL) or absolute.

params object <optional>

Custom parameters to append to the url.

Returns:

The generated URL.

Type
string
Example
var url = portalLib.assetUrl({
    path: 'styles/main.css'
});

(static) attachmentUrl(params) → {string}

This function generates a URL pointing to an attachment.

Parameters:
Name Type Description
params object

Input parameters as JSON.

Properties
Name Type Attributes Default Description
id string <optional>

Id to the content holding the attachment.

path string <optional>

Path to the content holding the attachment.

name string <optional>

Name to the attachment.

type string <optional>
source

Label of the attachment.

download boolean <optional>
false

Set to true if the disposition header should be set to attachment.

type string <optional>
server

URL type. Either server (server-relative URL) or absolute.

params object <optional>

Custom parameters to append to the url.

Returns:

The generated URL.

Type
string
Example
var url = portalLib.attachmentUrl({
    id: '1234',
    download: true
});

(static) componentUrl(params) → {string}

This function generates a URL pointing to a component.

Parameters:
Name Type Description
params object

Input parameters as JSON.

Properties
Name Type Attributes Default Description
id string <optional>

Id to the page.

path string <optional>

Path to the page.

component string <optional>

Path to the component. If not set, the current path is set.

type string <optional>
server

URL type. Either server (server-relative URL) or absolute.

params object <optional>

Custom parameters to append to the url.

Returns:

The generated URL.

Type
string
Example
var url = portalLib.componentUrl({
    component: 'main/0'
});

assert.assertEquals('ComponentUrlParams{type=server, params={}, component=main/0}', url);

(static) getComponent() → {object}

This function returns the component corresponding to the current execution context. It is meant to be called from a layout or part controller.

Returns:

The current component as JSON.

Type
object
Examples
var result = portalLib.getComponent();
log.info('Current component name = %s', result.name);
// Component returned.
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"
        }
    }
};

(static) getContent() → {object}

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:

The current content as JSON.

Type
object
Examples
var result = portalLib.getContent();
log.info('Current content path = %s', result._path);
// Content returned.
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": {}
};

(static) getIdProviderKey() → {object}

This function returns the id provider key corresponding to the current execution context.

Returns:

The current id provider as JSON.

Type
object
Examples
// Returns the current id provider.
var idProviderKey = portalLib.getIdProviderKey();

if (idProviderKey) {
    log.info('Id provider key: %s', idProviderKey);
}
// Id provider key returned.
var expected = "myidprovider" +
               "";

(static) getMultipartForm() → {object}

This function returns a JSON containing multipart items. If not a multipart request, then this function returns undefined.

Returns:

The multipart form items.

Type
object
Examples
var result = portalLib.getMultipartForm();
log.info('Multipart form %s', result);
// Multipart-form returned.
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
        }
    ]
};

(static) getMultipartItem(name, indexopt) → {object}

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:

The named multipart form item.

Type
object
Examples
var result = portalLib.getMultipartItem('item1');
log.info('Multipart item %s', result);
// Multipart-form returned.
var expected = {
    "name": "item1",
    "fileName": "item1.jpg",
    "contentType": "image/png",
    "size": 10
};

(static) getMultipartStream(name, indexopt) → {*}

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:

Stream of multipart item data.

Type
*
Example
var stream = portalLib.getMultipartStream('item2');
var stream2 = portalLib.getMultipartStream('item2', 1);

(static) getMultipartText(name, indexopt) → {string}

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:

Text for multipart item data.

Type
string
Example
var text = portalLib.getMultipartText('item1');

(static) getSite() → {object}

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:

The current site as JSON.

Type
object
Examples
var result = portalLib.getSite();
log.info('Current site name = %s', result._name);
// Site data returned.
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": {}
};

(static) getSiteConfig() → {object}

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:

The site configuration for current application as JSON.

Type
object
Examples
var result = portalLib.getSiteConfig();
log.info('Field value for the current site config = %s', result.Field);
// Site config returned.
var expected = {
    "Field": 42
};

(static) idProviderUrl(paramsopt) → {string}

This function generates a URL pointing to an ID provider.

Parameters:
Name Type Attributes Description
params object <optional>

Input parameters as JSON.

Properties
Name Type Attributes Default Description
idProvider string <optional>

Key of an ID provider. If idProvider is not set, then the id provider corresponding to the current execution context will be used.

contextPath string <optional>
vhost

Context path. Either vhost (using vhost target path) or relative to the current path.

type string <optional>
server

URL type. Either server (server-relative URL) or absolute.

params object <optional>

Custom parameters to append to the url.

Returns:

The generated URL.

Type
string

(static) imagePlaceholder(params) → {string}

This function generates a URL to an image placeholder.

Parameters:
Name Type Description
params object

Image parameters as JSON.

Properties
Name Type Description
width number

Width of the image in pixels.

height number

Height of the image in pixels.

Returns:

Placeholder image URL.

Type
string
Examples
var url = portalLib.imagePlaceholder({
    width: 32,
    height: 24
});
// URL returned.
var expected = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAYCAYAAACbU/80AAAAGUlEQVR42u3BAQEAAACCIP+vbkhAAQAA7wYMGAAB93LuRQAAAABJRU5ErkJggg==';

(static) imageUrl(params) → {string}

This function generates a URL pointing to an image.

Parameters:
Name Type Description
params object

Input parameters as JSON.

Properties
Name Type Attributes Default Description
id string

ID of the image content.

path string

Path to the image. If id is specified, this parameter is not used.

scale string

Required. Options are width(px), height(px), block(width,height) and square(px).

quality number <optional>
85

Quality for JPEG images, ranges from 0 (max compression) to 100 (min compression).

background string <optional>

Background color.

format string <optional>

Format of the image.

filter string <optional>

A number of filters are available to alter the image appearance, for example, blur(3), grayscale(), rounded(5), etc.

type string <optional>
server

URL type. Either server (server-relative URL) or absolute.

params object <optional>

Custom parameters to append to the url.

Returns:

The generated URL.

Type
string
Example
var url = portalLib.imageUrl({
    id: '1234',
    scale: 'block(1024,768)',
    filter: 'rounded(5);sharpen()'
});

(static) loginUrl(paramsopt) → {string}

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.

Properties
Name Type Attributes Default Description
idProvider string <optional>

Key of a id provider using an application. If idProvider is not set, then the id provider corresponding to the current execution context will be used.

redirect string <optional>

The URL to redirect to after the login.

contextPath string <optional>
vhost

Context path. Either vhost (using vhost target path) or relative to the current path.

type string <optional>
server

URL type. Either server (server-relative URL) or absolute.

params object <optional>

Custom parameters to append to the url.

Returns:

The generated URL.

Type
string

(static) logoutUrl(paramsopt) → {string}

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.

Properties
Name Type Attributes Default Description
redirect string <optional>

The URL to redirect to after the logout.

contextPath string <optional>
vhost

Context path. Either vhost (using vhost target path) or relative to the current path.

type string <optional>
server

URL type. Either server (server-relative URL) or absolute.

params object <optional>

Custom parameters to append to the url.

Returns:

The generated URL.

Type
string

(static) pageUrl(params) → {string}

This function generates a URL pointing to a page.

Parameters:
Name Type Description
params object

Input parameters as JSON.

Properties
Name Type Attributes Default Description
id string <optional>

Id to the page. If id is set, then path is not used.

path string <optional>

Path to the page. Relative paths is resolved using the context page.

type string <optional>
server

URL type. Either server (server-relative URL) or absolute.

params object <optional>

Custom parameters to append to the url.

Returns:

The generated URL.

Type
string
Example
var url = portalLib.pageUrl({
    path: '/my/page',
    params: {
        a: 1,
        b: [1, 2]
    }
});

(static) processHtml(params) → {string}

This function replaces abstract internal links contained in an HTML text by generated URLs.

When outputting processed HTML in Thymeleaf, use attribute data-th-utext="${processedHtml}".

Parameters:
Name Type Description
params object

Input parameters as JSON.

Properties
Name Type Attributes Default Description
value string

Html value string to process.

type string <optional>
server

URL type. Either server (server-relative URL) or absolute.

Returns:

The processed HTML.

Type
string
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>'
});

(static) sanitizeHtml(html) → {string}

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:

The sanitized HTML.

Type
string
Examples
var unsafeHtml = '<p><a href="http://example.com/" onclick="stealCookies()">Link</a></p>' +
                 '<iframe src="javascript:alert(\'XSS\');"></iframe>';
var sanitizedHtml = portalLib.sanitizeHtml(unsafeHtml);
// Sanitized HTML returned.
var expectedHtml = '<p><a href="http://example.com/">Link</a></p>';

(static) serviceUrl(params) → {string}

This function generates a URL pointing to a service.

Parameters:
Name Type Description
params object

Input parameters as JSON.

Properties
Name Type Attributes Default Description
service string

Name of the service.

application string <optional>

Other application to reference to. Default is current application.

type string <optional>
server

URL type. Either server (server-relative URL) or absolute.

params object <optional>

Custom parameters to append to the url.

Returns:

The generated URL.

Type
string
Example
var url = portalLib.serviceUrl({
    service: 'myservice',
    params: {
        a: 1,
        b: 2
    }
});

(static) url(params) → {string}

This function generates a URL.

Parameters:
Name Type Description
params object

Input parameters as JSON.

Properties
Name Type Attributes Default Description
path string

Path of the resource.

type string <optional>
server

URL type. Either server (server-relative URL) or absolute.

params object <optional>

Custom parameters to append to the url.

Returns:

The generated URL.

Type
string
Example
var url = portalLib.url({
    path: '/site/master/mysite',
    params: {
        a: 1,
        b: 2
    }
});