Gentics CMS Documentation

Chapters

1. Publishing and Sucscribing to messages

2. Messages Published by the Core Library

   • error-encountered Message

3. 'content-rendered' Message

   • Example

4. authentication-required Message

   • Example

5. Custom Error Handlers

1 Publishing and Sucscribing to messages

Publishing and subscribing works using the GCN.pub() and GCN.pub() methods. Here’s a usage example:

// publishing a message
GCN.pub('some-event-encountered', [parameters]);

Publishing a message allows you to specify a message name and also to add one custom parameter like an array or an object to pass additional information to your message subscriber.

// subscribing to error messages
GCN.sub('error-encountered', function (error) {
	console.log('an error occured: ' + error.toString());
});

Subscribing to messages is accomplished by specifying the message name and a callback function. The callback will receive one parameter containing additional information if the message sender has added data.

2 Messages Published by the Core Library

2.1 error-encountered Message

Subscribing to these messages allows you to handle all error messages encountered at runtime. The subscriber will receive an GCNError object as an argument.

2.1.1 GCNError Object

The GCNError object contains the following properties and methods:

• code – The error’s error code as a string.
• message – A user-friendly message describing the error. This message may be communited to the user.
• data – An object that holds information about relevent data around the context of when the error occured. This information may be useful for logging.
• toString() – Prints the error in a log-friendly way.

2.1.2 Error Codes

• UNKNOWN_ARGUMENT – To be completed.
• INVALID_ARGUMENT – To be completed.
• NO_AUTH_HANDLER – Authentication was required, but no handlers have been registered to listen for authentication-required messages.
• UNFETCHED_OBJECT_ACCESS – Attempting to invoke a read method on an object that has not yet had its data fetched from the server. The following methods can only be called within a success callback closure otherwise this error will be raised:
  • meta()
  • props()
  • id()
• READONLY_ATTRIBUTE – Attempting to write to a readonly property.
• AUTHENTICATION_FAILED – Will be triggered when the cancel() method that is passed to the authentication-required handler is called.
• NO_SESSION – To be completed.

2.1.3 Example

// handle all errors
GCN.sub('error-encountered', function (error) {
	console.log(error.toString());
});

3 'content-rendered' Message

Whenever a tag is rendered (including when it is rendered for editing), or when a page is rendered for preview, a global render message is published. The registered callback will be called after the tag or page that has been rendered but before it has reached the success handler that was passed to the invoking function. The handler receives 3 arguments: first is the rendered HTML, the second is the Content Object which was rendered, and the third argument is a callback, that, when invoked, will allow the render invocation to reach its completion. This callback receives the modified html as its only argument.

3.1 Example

GCN.sub('content-rendered', function (html, tag, callback) {	
	html = html.replace('foo', 'bar');
	callback(html);
});

4 authentication-required Message

An authentication-required message is published when an API method that requires an authenticated session in order to accomplish communication with the Gentics CMS back-end is invoked and no authenticated session exists. This can also happen if a previously authenticated session expires or is otherwise destroyed.

When the authentication-required message is published, any subscriptions will be invoked, and receive an array containing two callbacks as its arguments. The first callback will be a proceed() function that should be called once an authenticated session has been obtained. The second is the cancel() function which aborts the process that was waiting for the authenticated session. Calling cancel() will result in a error event being triggered.

4.1 Example

GCN.sub('authentication-required', function (args) {
	var isLoginSuccessful;
	var proceed = args[0];
	var cancel = args[1];

	// ... attempt login

	if (isLoginSuccessful) {
		proceed();
	} else {
		cancel();
	}
});

5 Custom Error Handlers

With the exception of meta(), prop(), part(), and id(), methods in the Gentics CMS JavaScript API receive optional success and error callbacks. A success handler is required whenever we wish to read/write an object’s data to and from the Gentics CMS back-end.

If the success handler is provided it will trigger communication with the server and bring the control flow into the success callback once that communication completes. If an error occurs during this process an error-encountered message is published. If provided, the custom error handler will be invoked first and only if it returns true will the invocation then be bubble an trigger an error-encountered message.