Docs Developer Site
Developer Docs Enonic Development Kit 8.x Libraries Value library

Value library

Contents

Helper functions for creating the complex value types that JSON cannot express on its own — geo-points, instants, dates, node references, and binary attachments.

Install

Add the library to your build.gradle file:

dependencies {
  include xplibs.value
}

TypeScript types come from the @enonic-types/lib-value package, installed at the version of XP your project builds against — see TypeScript.

Complex value types

Every property in the storage has a value type, and storage uses it to determine both validation and indexing automatically. JSON carries some value types on its own — strings, numbers, booleans, and nested objects (a Set). The rest have no JSON equivalent, and nothing declares a node property’s type up front, so '59.9139,10.7522' is just a string unless the value says otherwise.

These helpers supply that missing type. Pass the result straight into the property where the value belongs, and storage picks the index mappings from it: a GeoPoint gets the geoPoint mapping, an Instant, LocalDate, or LocalDateTime gets datetime, each alongside the default text mapping. Store the same value as a plain string and it is indexed as text only — geo and date-range queries will not match it.

The helpers are used almost exclusively with lib-node against custom repositories. lib-content does not need them, because a content type declares its field types and the engine converts plain JSON according to that schema.

Storing complex value types on a node
import {connect} from '/lib/xp/node';
import {geoPoint, instant, localDate, reference} from '/lib/xp/value';

const repo = connect({
    repoId: 'my-repo',
    branch: 'master'
});

const office = repo.create({
    _name: 'oslo-office',
    displayName: 'Oslo office',
    location: geoPoint(59.9139, 10.7522),
    openedAt: instant('2016-08-01T11:22:00Z'),
    leaseExpires: localDate('2027-06-30'),
    manager: reference('1234-5678-91011')
});
Sample response (system properties abridged)
{
    _id: 'b186d24f-ac38-42ca-a6db-1c1bda6c6c26',
    _name: 'oslo-office',
    _path: '/oslo-office',
    _nodeType: 'default',
    displayName: 'Oslo office',
    location: '59.9139,10.7522',
    openedAt: '2016-08-01T11:22:00Z',
    leaseExpires: '2027-06-30',
    manager: '1234-5678-91011'
}

Complex values are read back as strings. create() and get() serialize every property to its string form, so a GeoPoint returns as '<lat>,<lon>' and a Reference as the node ID. Only the JavaScript view is flattened — the stored property keeps its value type and its index mappings.

Editors are the exception. Inside the editor callback of update, modify, or patch, properties arrive as the complex values themselves rather than strings, which is what lets an untouched property round-trip without degrading to text.

Functions

binary

Creates a BinaryAttachment value from a name and a binary stream.

Parameters

binary() takes two positional arguments: name (string — the binary name) and stream (ByteSource — the binary stream).

Returns

object : (BinaryAttachment)

Example

Create a binary attachment from a stream
import {binary} from '/lib/xp/value';
import {newStream} from '/lib/xp/io';

const attachment = binary('myFile.txt', newStream('Hello World'));

geoPoint

Creates a GeoPoint value from numeric coordinates.

Parameters

geoPoint() takes two positional arguments: lat (number — latitude) and lon (number — longitude).

Returns

object : (GeoPoint)

Example

Create a geo-point from coordinates
import {geoPoint} from '/lib/xp/value';

const location = geoPoint(59.9139, 10.7522);

const lat = location.getLatitude();

Coordinates keep a decimal point in their string form, so geoPoint(80, -80) reads back as '80.0,-80.0'.

geoPointString

Creates a GeoPoint value from a comma-separated latitude and longitude string.

Parameters

geoPointString() takes one positional argument: value (string — comma-separated latitude and longitude, e.g. '59.9139,10.7522').

Returns

object : (GeoPoint)

Example

Create a geo-point from a string
import {geoPointString} from '/lib/xp/value';

const location = geoPointString('59.9139,10.7522');

instant

Creates an Instant value from an ISO-8601 string or a Date object.

Parameters

instant() takes one positional argument: value (string | Date — an ISO-8601-formatted instant such as '2011-12-03T10:15:30Z', or a JavaScript Date).

Returns

object : (Instant)

Example

Create an instant
import {instant} from '/lib/xp/value';

const openedAt = instant('2016-08-01T11:22:00Z');

const millis = openedAt.toEpochMilli();

localDate

Creates a LocalDate value from an ISO local date string or a Date object.

Parameters

localDate() takes one positional argument: value (string | Date — an ISO local date such as '2011-12-03', or a JavaScript Date).

Returns

object : (LocalDate)

Example

Create a local date
import {localDate} from '/lib/xp/value';

const leaseExpires = localDate('2027-06-30');

const year = leaseExpires.getYear();

localDateTime

Creates a LocalDateTime value from a local date-time string or a Date object.

Parameters

localDateTime() takes one positional argument: value (string | Date — a local date-time string such as '2007-12-03T10:15:30', or a JavaScript Date).

Returns

object : (LocalDateTime)

Example

Create a local date-time
import {localDateTime} from '/lib/xp/value';

const doorsOpen = localDateTime('2016-01-08T10:00:00.000');

localTime

Creates a LocalTime value from an ISO local time string or a Date object.

Parameters

localTime() takes one positional argument: value (string | Date — an ISO local time such as '10:15:30', or a JavaScript Date).

Returns

object : (LocalTime)

Example

Create a local time
import {localTime} from '/lib/xp/value';

const doorsOpen = localTime('10:00:00.000');

reference

Creates a Reference value from a node ID string.

Parameters

reference() takes one positional argument: value (string — a node ID, e.g. '1234-5678-91011').

Returns

object : (Reference)

Example

Create a node reference
import {reference} from '/lib/xp/value';

const manager = reference('1234-5678-91011');

const nodeId = manager.getNodeId();

Type Definitions

GeoPoint

A typed geo-point value. Returned by geoPoint() and geoPointString().

Methods

Name Type Description

getLatitude()

number

The latitude component.

getLongitude()

number

The longitude component.

toString()

string

Serialized form — '<lat>,<lon>'.

Instant

A typed instant (point in time) value. Returned by instant().

Methods

Name Type Description

getEpochSecond()

number

Seconds since the Unix epoch.

getNano()

number

Nanoseconds adjustment within the current second.

toEpochMilli()

number

Milliseconds since the Unix epoch.

Reference

A typed node reference value. Returned by reference().

Methods

Name Type Description

getNodeId()

string

The referenced node ID.

toString()

string

String form of the node ID.

LocalDateTime

A typed local date-time value (no time-zone). Returned by localDateTime().

Methods

Name Type Description

getYear()

number

The year.

getMonthValue()

number

Month as a number (1–12).

getMonth()

Month

Month as a string constant.

getDayOfMonth()

number

Day of the month (1–31).

getDayOfWeek()

DayOfWeek

Day of the week as a string constant.

getHour()

number

Hour of day (0–23).

getMinute()

number

Minute of hour (0–59).

getSecond()

number

Second of minute (0–59).

getNano()

number

Nanosecond of second.

LocalDate

A typed local date value (no time, no time-zone). Returned by localDate().

Methods

Name Type Description

getYear()

number

The year.

getMonthValue()

number

Month as a number (1–12).

getMonth()

Month

Month as a string constant.

getDayOfMonth()

number

Day of the month (1–31).

getDayOfYear()

number

Day of the year (1–366).

getDayOfWeek()

DayOfWeek

Day of the week as a string constant.

isLeapYear()

boolean

Whether the year is a leap year.

LocalTime

A typed local time value (no date, no time-zone). Returned by localTime().

Methods

Name Type Description

getHour()

number

Hour of day (0–23).

getMinute()

number

Minute of hour (0–59).

getSecond()

number

Second of minute (0–59).

getNano()

number

Nanosecond of second.

BinaryAttachment

A typed binary attachment value wrapping a name reference and a stream. Returned by binary().

Methods

Name Type Description

getReference()

BinaryReference

Reference to the stored binary.

getByteSource()

ByteSource

The underlying binary stream.

BinaryReference

A reference to a stored binary. Returned by BinaryAttachment.getReference().

Methods

Name Type Description

toString()

string

The binary name.

Month

Month name constant — one of 'JANUARY', 'FEBRUARY', 'MARCH', 'APRIL', 'MAY', 'JUNE', 'JULY', 'AUGUST', 'SEPTEMBER', 'OCTOBER', 'NOVEMBER', 'DECEMBER'.

DayOfWeek

Day name constant — one of 'MONDAY', 'TUESDAY', 'WEDNESDAY', 'THURSDAY', 'FRIDAY', 'SATURDAY', 'SUNDAY'.

Contents

Contents