Gentics CMS Documentation

Chapters

1. Working with channels: GCN.channel()

   • Changing channels

   • Leaving a channel

   • Getting channel objects

2. localize()

   • Localize a page

   • Accessing a localized page with its inherited ID.

   • localize() errors

3. Unlocalize()

   • unlocalize() errors

4. Notes

5. Need for caution

1 Working with channels: GCN.channel()

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 GCN.channel() with no arguments.

1.1 Changing channels

It is possible to switch channels by setting a new channel node ID using GCN.channel()

	// Use node with id 3 as current channel context
	GCN.channel(3);

1.2 Leaving a channel

Passing false to GCN.channel() 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.

	GCN.channel(false);

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 GCN.page() 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 = GCN.page(116);
	// Switch into channel node 3
	GCN.channel(3);
	// `channelPage' will be an inherited or
	// localized copy of page 116.
	var channelPage = GCN.page(116); 

// Switch into channel 1
GCN.channel(1);
var page1 = GCN.page(1);
GCN.channel(false);
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(folder1.id())

// 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

	GCN.channel(3);
	// 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 = GCN.page(116);
	inherited.localize(function (localized) {
		// inherited.id() != localized.id()
	});

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.

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.

	GCN.channel(3);
	GCN.page(116).localize(function (localized) {
		GCN.page(116, function (page) {
			//page.id() === localized.id()
		});
	});

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.

	GCN.channel(id_of_channeled_node);
	var localized = GCN.page(id_of_page_that_was_localized);
	localized.unlocalize();
	var inherited = GCN.page(id_of_page_that_was_localized);

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

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:

	GCN.channel(2);
	var p1 = GCN.page(123, function () {});
	var p2 = GCN.page(456, function () {});
	GCN.channel(false);
	var p3 = GCN.page(123, function () {});
	var p4 = GCN.page(456, function () {});

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