Tutorial

Logging

Table of contents
  1. Simple logs
  2. Logging complex objects
    1.Arrays
    2.JSON objects
    3.cplace objects
  3. Error logs
  4. Log names

Often it is required to produce some kind of output in a script for reporting errors or for debugging. The cplace api brings some handy logging tools for this which you can use to report misbehaviour or states of the script.

Simple logs

The most easy and straightforward way of logging is by just calling the cplace.log() method. It takes a string or an object as input and writes it to the "log-space". Imagine we're writing something not trivial and want to know if calculations are done right and everything runs as expected. To check that we just log some data, run the script and check the logs:

var someValue = page.get('cf.cplace.randomNumberAttribute'); // assume this is 1337.0
cplace.log('someValue: ' + someValue);
// will log:
// someValue: 1337.0

Logging complex objects

When logging objects like arrays, pages or just plain JSON objects we have to consider a few irregularities:

Arrays

Javascript native arrays [1, 2, 3] are not rendered correctly by default but appear as [object Array] in the logs when done like

var dataArray = [1, 2, 3];
cplace.log(dataArray);
// [object Array]

This can be circumvented by adding some text to the log:

var dataArray = [1, 2, 3];
cplace.log('dataArray: ' + dataArray);
// dataArray: 1,2,3

The mechanism will also flatten arrays which can be useful (or not), depending on how you want to read the displayed data

var dataArray = [
    [1, 2, 3],
    [4, 5, 6],
    [7, 8, 9]
];
cplace.log('dataArray: ' + dataArray);
// dataArray: 1,2,3,4,5,6,7,8,9

If you do not want to add some extra text to your log you can always stringify the array. This will also retain any structural syntax like brackets and braces, so you can differ nested objects:

var dataArray = [1, 2, 3];
cplace.log(JSON.stringify(dataArray));
// dataArray: [1,2,3]

JSON objects

Similar to arrays JS native json objects are usually rendered as [object Object], even used with a string

var debugObj = { a: 2, b: '3'};
cplace.log(debugObj);
// [object Object]

cplace.log('object: ' + debugObj);
// object: [object Object]

so you have to use JSON.stringify()

var debugObj = { a: 1, b: '2'};
cplace.log(JSON.stringify(debugObj));
// {"a":1,"b":"2"}

or get the data from the object manually

var debugObj = { a: 1, b: '2'};
cplace.log('a: ' + debugObj.a + ', b: ' + debugObj.b);
// a: 1, b: 2

cplace objects

Some apis provide complex java objects like pages, collections/iterables or searches. When this kind of object is put in a log method, its corresponding toString() method is invoked on the Java level. This will most likely produce completely different outputs than what javascript does usually. Also not all available data is displayed e.g.

cplace.log(page);
// Test Page [uid=page/nsv1eu5aj0yj08lirjeq0uam3, state: persistent_read_only]`

so you probably need to extract information by hand.

Error logs

It's also possible to log errors with cplaceJS. These logs will be displayed differently in the cplaceJS admin view and written to the default log stream, i.e. they will also appear in the regular cplace log files. To log an error use cplace.error() as you would use the log method:

cplace.error('Error: Something went terribly wrong!');

Log names

The cplaceJS admin view aggregates all logs emitted from scripts in the tenant. To better differentiate between different spaces and users you can use the filtering, but we can take this even further and filter for so called "log names". Log names are strings which are attached to logs and provide the possibility to create name spaces for logs.

To use a log name you have to explicitly set it in every script or every time you change the log name inside a script:

cplace.setLogName('changeListener.myType.myAttribute');
cplace.log('Some cool debug information ...' + changeEvent.getEntity());

will result in the log line

DEBUG [changeListener.myType.myAttribute] Some cool debug information ...Test 7 [uid=page/nsv1eu5aj0yj08lirjeq0uam3, state: persistent_read_only]

Now you can enter the log name you want to display in the field and scroll through all logs that were logged with that name (be sure to type the full name correctly as the field does not support partial matches).