Concept

An editor that is embedded in your HTML pages can be interacted with using our JavaScript API. See Embedding an Editor in your own portals

There are many reasons a team would want to do this. Some examples are:

• Updating variables on document load

• Connecting to a custom widget

• Building a partial or complete custom interface

• Creating a “Save” button or an auto-save feature
  
  

Connection To CHILI publisher

You cannot communicate with the CHILI publisher directly due to the editor running in an iframe and browser security blocking JavaScript communication across iframes.

Therefore, if you want to utilize our JavaScript API across iframes you need to utilize our plugin: publisher-connector

You can install publisherInterface via npm

or through yarn

Or you can use the version from unpkg.com in your <script/> tags:

https://unpkg.com/@chili-publish/publisher-connector@latest/dist/publisherInterface.min.js

Once you have decided, it is time to begin your integration. There are two steps:

• Create an instance of the PublisherInterface

• Listen to the event for the CHILI document to be fully rendered

Create an instance of the PublisherInterface

To create an instance of the publisherInterface, you will need to use the .build() method and pass in the iframe element.

Below is the code of a quite simple website where the iframe URL for CHILI publisher is already set.

Notice that the .build() method returns a Promise. In the code above we utilize the async/await syntax, but we could also use the alternative then syntax.

Listen to the event for the CHILI document to be fully rendered

As soon as the Promise from the .build() method is resolved, you are good to begin interacting with the CHILI publisher editor. However, due to the loading of the document it may be wise to wait until the document has fully rendered before you start your interaction.

To do this, we need to add an event listener for the event DocumentFullyRendered. The event DocumentFullyRendered is fired off only when the CHILI document and workspace are completely drawn to the screen.

Now, this is not a web event, we must use a special method called .addListener(). This method takes an event name (string) and a callback function to be called when the event is fired off.

The full JavaScript example would look like:

These method calls we are making will return an Exception if something goes wrong. Therefore, it is important to wrap your calls with a try/catch

There is an earlier event called DocumentFullyLoaded, this event is called when the CHILI document has been fully deserialized from the XML format into an in-memory JavaScript object. If you would like to listen for that, the method is similar:

Working With CHILI publisher JavaScript API

If you have followed along, you should have a working example as an HTML file, and you can begin playing around with our JavaScript API.

You can check out pages like: Common JavaScript integration tasks, but you will notice they are using editor or editorObject and there is no Promise to be found in any of the examples. The reason it looks different is because all examples outside this one page communicate with CHILI publisher directly, meaning no iframe and no publisherInterface. The publisherInterface is just an interface that uses the postMessage() method, but under the hood it utilizes the direct editorObject.

You can find the source code that is running on the Online server here: https://github.com/chili-publish/publisher-connector/blob/main/onServer/chiliInternalWrapper.ts

There are a few differences between the publisherInterface interface and the direct editorObject:

• Naming Convention

• Promise Return

• Events

Naming Convention

A small, but important difference is that the methods from the publisherInterface uses common JavaScript naming - camel case. This differs from the Pascal case used by the editorObject.

So editorObject.GetObject() becomes publisherInterface.getObject().

So editorObject.SetProperty() becomes publisherInterface.setProperty().

Promise Return

While the editorObject methods return without delay, the publisherInterface uses postMessage(). This means that the message must be serialized, sent, deserialized across from one window to another.

To make this easy, the publisherInterface methods return a Promise.

So instead of:

You would do:

or use await, in a function marked async:

Just like editorObject methods, if something goes wrong, an Exception will be thrown.

Events

The publisherInterface does events completely different from what is documented for the editorObject.

To use events with the editorObject, it involved calling the editorObject.AddListener() method and then defining a function on window.OnEditorEvent() method that took a string for events. The OnEditorEvent() function would typically have a switch case or a series of if/else to determine which event was called.

publisherInterface makes things much simpler. If you want to listen to an event and then do something, then name it and add a callback function.

Removing an event is pretty much the same.

Four Common Uses

Okay now that you understand the difference between the PublisherInterface object and the editorObject, we can look at the methods on these objects. Keep in mind that there are several methods, but we will only cover four use cases:

• Listening to Events

• Reading Properties

• Setting Properties

• Executing Function

Listening to Events

You can listen to events using this method .addListener(). The first parameter takes an event name (string) and a callback function to be called when the event is fired off.

publisherInterface Object

editorObject Object

Reading Properties

To read properties of the document, you use the method .getObject() which will return to you either a copy of the JavaScript object or a primitive. CHILI publisher converts the XML into a big JavaScript object starting at the document element with a all the child elements becoming properties.

So, if you wanted to get the full document object you could do this:

publisherInterface Object

editorObject Object

The above calls will give you a shallow snapshot of the document. By shallow, we mean that it only goes one level deep down the key/value object tree. By snapshot, we mean that the object returned has no reference to the in-memory CHILI document object.

If you wanted to get the name, you could just then do .name

You can also get the property directly by passing the string document.name in the getObject() method.

The string document.name is commonly referred to as CHILI path. It is the key/value path of the object.

For example, if you wanted to get the id of the first frame on page two.

Reading Properties

Okay we know how to read properties, but how do we set properties? We utilize the setProperty() method. This method takes a CHILI path string, the property to set, and the value to set it to.

publisherInterface Object

editorObject Object

Executing Functions

Remember that CHILI publisher serializes the XML to a JavaScript object. Well that object has methods/functions, which we can interact with via CHILI path.

We can do this utilizing the .executeFunction() method. This method’s signature takes the CHILI path, the function name, and then a variable number of parameters based on the function you wish to call. The response will vary based on the function you wish to call.

So, for example, creating a new frame:

publisherInterface Object

editorObject Object

While getting the XML of the document, it has no extra parameters:

Unfortunately, unlike properties, functions on CHILI objects are not shown in the .getObject() method. The most common function names can be found in this documentation, or contact support to see if there exist a function for what you are trying to achieve.

Working With Older CHILI publish On-prem