Docs Developer Site
DeveloperDocsXpStableApiLib Portal

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

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

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

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.

label

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

string : The generated URL.

Example

Obtains list of active tasks: 
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

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

string : The generated URL.

Example

Obtains list of active tasks: 
var url = portalLib.componentUrl({
  component: 'main/0'
});
Return value: 
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

Obtains list of active tasks: 
var result = portalLib.getComponent();
log.info('Current component name = %s', result.name);
Return value: 
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

Get content and log the result: 
var result = portalLib.getContent();
log.info('Current content path = %s', result._path);
Return value: 
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

Returns the current id provider: 
var idProviderKey = portalLib.getIdProviderKey();

if (idProviderKey) {
    log.info('Id provider key: %s', idProviderKey);
}
Return value: 
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

Get the form and log the result: 
var result = portalLib.getMultipartForm();
log.info('Multipart form %s', result);
Return value: 
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

Get item and log the result: 
var result = portalLib.getMultipartItem('item1');
log.info('Multipart item %s', result);
Return value: 
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

Get site and log the result: 
var result = portalLib.getSite();
log.info('Current site name = %s', result._name);
Return value: 
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

Get site and log the result: 
var result = portalLib.getSiteConfig();
log.info('Field value for the current site config = %s', result.Field);
Return value: 
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

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

string : The generated URL.

imagePlaceholder

This function generates a URL to an image placeholder.

Parameters

Name Type Description

params

object

Input parameters as JSON

Properties
Name Type Description

width

number

Width of the image in pixels.

height

number

Height of the image in pixels.

Returns

string : Placeholder image URL.

Example

Obtains image encoded to base64: 
var url = portalLib.imagePlaceholder({
  width: 32,
  height: 24
});
Return value: 
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

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

string : The generated URL.

Example

Obtains image url: 
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

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

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

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

string : The generated URL.

pageUrl

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

string : The generated URL.

Example

Obtains page url: 
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

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.

XP XP 7.7.0 7.7.0 imageWidths

number[]

<optional>

A comma-separated list of image widths. If this parameter is provided, all <img> tags will have an additional srcset attribute with image URLs generated for specified widths.

XP XP 7.8.0 7.8.0 imageSizes

string

<optional>

Specifies the width for an image depending on browser dimensions. The value has the following format: (media-condition) width. Multiple sizes are comma-separated.

Returns

string : The processed HTML.

Example

Process HTML: 
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

Sanitizes unsafe HTML: 
var unsafeHtml = '<p><a href="https://example.com/" onclick="stealCookies()">Link</a></p>' +
                 '<iframe src="javascript:alert(\'XSS\');"></iframe>';
var sanitizedHtml = portalLib.sanitizeHtml(unsafeHtml);
Return value: 
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

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 or `websocket.

params

object

<optional>

Custom parameters to append to the url.

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

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 or websocket.

params

object

<optional>

Custom parameters to append to the url.

Returns

string : The generated URL.

Example

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

Contents

Contents