This guide describes how to use Gentics CMS Multichannelling features within the Gentics CMS JavaScript API

The reader’s general understanding of how multichannelling works is assumed in this documentation. For details about how multichannelling works, and how best to use it please consult the guides under “Multichannelling”.

1 Working with channels:

Be default the Gentics CMS JS API has no channel context set. This means that, by default, loading and saving content objects is always done on master nodes.

To determine which channel is currently selected, simply call with no arguments.

1.1 Changing channels

It is possible to switch channels by setting a new channel node ID using

	// Use node with id 3 as current channel context;

1.2 Leaving a channel

Passing false to function will cause the channel context to be removed. Internally, this will mean that REST-API requests that are performed by the Gentics CMS JS API will not send a nodeId query parameter with the request.;

1.3 Getting channel objects

Once you have switched into a channel, any content object (image, page, folder, files) that is subsequently accessed by means of calling or GCN.folder() for example will result in either an inherited object or a localized object of the selected channel being returned.

	// No channel set by default
	var masterPage =;
	// Switch into channel node 3;
	// `channelPage' will be an inherited or
	// localized copy of page 116.
	var channelPage =; 

Each object access chain is bound to one channel. The channel to which an object chain is bound to will be the channel that was current when the root of the an object access chain was created. A new object access chain is created when accessing an content object from the GCN object eg: or GCN.image(2).

// Switch into channel 1;
var page1 =;;
var folder1 = page.folder();

// Note that even though the channel has been unset, folder1
// will still be bound to channel 1 because it belongs to a
// chain that was initialized in the context of channel 1.
equal(folder1._channel, page1._channel);

// Assuming that folder1 is an inherited object (and not
// localized one) It should be possible to do the following
// to get the folder object version from the master node.
var folder2 = GCN.folder(

// Since the above statement marks the root of a new object
// access chain, folder2 will now be bound to a different
// channel.
ok(folder1._channel != folder2._channel)

2 localize()

When working in a channel context, one can create a channel-local copy of an inherited content object by using the localize() method.

2.1 Localize a page;
	// Load page 116 within channel node 3. We will
	// therefore. In our example page 116 has not be
	// localized yet, and therefore, the inherited object
	// is returned.
	var inherited =;
	inherited.localize(function (localized) {
		// !=

Once a you have called localize() on an object, further attempts to access that object with its inherited id when still in the channel in which it was localized will return the localized version of the page rather than the inherited version.

localize() is not implemented for template content objects in the Gentics CMS JS API yet.

2.2 Accessing a localized page with its inherited ID.

When loading content objects while working with channel, the returned object may not have the same internal content id as that used to fetch it. This would be the case if you are accessing a localized object with its inherited id as the example below illustrates.; (localized) {, function (page) {
			// ===

2.3 localize() errors

Attempting to localize an object when no channel is set will cause an CHANNEL_ID_NOT_SET error to be raised.

Attempting to localize an object which has not an inherited object will cause an CANNOT_LOCALIZE error to be raised.

3 Unlocalize()

Calling unlocalize() on a previously localized content object will cause the localized version to be removed, and the inherited version to become visible again.;
	var localized =;
	var inherited =;

unlocalize() is not implemented for template content objects in the Gentics CMS JS API yet.

3.1 unlocalize() errors Attempting to unlocalize an object when no channel is set will cause an CHANNEL_ID_NOT_SET error to be raised.

Attempting to unlocalize an object which has not be previously localized will cause an CANNOT_UNLOCALIZE error to be raised.

4 Notes

delete() is not currently implemented for localized or inherited objects.

It is not possible to create objects in folders that that are outside of the currently selected channel.

5 Need for caution

One needs to be cautious when using channel-inherited ids to load content objects. The object data that is loaded varies depending on whether or not you are in a channel, and whether or not a channel local copy of the inherited object exists in a given channel.

Consider working in a channel (with a node id 2 for example). Further consider that this channel inherits a page with the id 123, and that at some point in time a channel-local copy of this page is made with the id 456. Now consider the following statements:;
	var p1 =, function () {});
	var p2 =, function () {});;
	var p3 =, function () {});
	var p4 =, function () {});

The fact that page 456 is a channel-local copy of page 123 in the channel 2, means that p1, and p2 will be two difference objects on the client which reference the exact same object on the backend.

If client changes were made to p1 and p2, and both objects are saved(), one set of changes will be overridden, with the last changes to reach the server clobbering those of the first.

As a side note to developers, in this scenario out library cache would contain the following entries:

"PageAPI:0/123" = @clientobject1 => @serverobject1
"PageAPI:0/456" = @clientobject2 => @serverobject2
"PageAPI:2/123" = @clientobject3 => @serverobject2
"PageAPI:2/456" = @clientobject4 => @serverobject2