General Document and Editor functions

Initial Processing

Modifying the document after loading the editor should be done after you have received the "DocumentFullyLoaded" event: JavaScript Events

Saving and Reverting

You can revert the current document to its last saved version using:

   editor.ExecuteFunction("document", "Revert")

Saving a document is an asynchronous task, which can be triggered using:

   editor.ExecuteFunction("document", "Save")

The "DocumentSaved" event is triggered once the save has been completed.

It is possible to prevent the user from saving through the normal "Save" icon, by listening to the "DocumentSaveRequested" event. If you decide not to allow the user to save at that point, you can call:

   //DENY SAVING
   editor.SetProperty("document","saveDenied",true);
   //BE FRIENDLY, AND LET THE USER KNOW
   editor.Alert("No saving allowed right now.","Sorry");

Document dirty state

Whenever the user toggles the document between having / not having unmodified changes (as represented by the current state of the undo stack), you can receive the "DocumentDirtyStateChanged" event. At that point, you can call the following code to find the current state of the document:

   var hasUnsavedChanges = editor.GetDirtyState();

You can use this to show/hide/disable parts of your interface, but also to warn the user when he tries to navigate away from the page (using your HTML page's onbeforeunload event)

Opening a new document in an opened Editor

   editor.ExecuteFunction("document", "OpenDocument", newDocID)

Following this, a new "DocumentFullyLoaded" event will be triggered

Zooming on documents

You can set the zooming-percentage on the document by modifying the zoom property of the document.

	editor.SetProperty("document", "zoom", 225);

You can also set the zoom-level of the editor to fit the document's width, height, or both.

	editor.ExecuteFunction("document.editor","Fit","page");

The last argument can be "page", "width" or "height".

Selecting a frame in the editor

It is possible to trigger the selection of a frame via Javascript.
Most of the times, this will be done with a tagged frame, but the selection of a specific frame can be done as described above, underneath "Object descriptors for lists"

The sample below will select a frame that has been tagged as 'BG_IMAGE'.

function selectFrameWithTag(){
    var frametag = "BG_IMAGE";
	editor.ExecuteFunction('document.allFrames[' + frametag + ']', 'Select');
}

Copying and pasting frames

  To copy one or more selected frames in the editor, you can use 

	editor.ExecuteFunction("document.selectedFrames", "Copy") 

To paste the frames that are copied, you can use

	editor.ExecuteFunction('document', 'PasteFrames');

Delete a frame

  To remove a frame from the document

	editor.ExecuteFunction("document.selectedFrame", "Delete"); 

Unselecting of (multiple) frame(s)

You can unselect one or more frames by calling  

	editor.ExecuteFunction('document.selectedFrames', 'Clear');

Undo/Redo

  To Undo or Redo changes on a document, you can control the undo manager   

	//undo 1 change
	editor.ExecuteFunction("document.undoManager", "Undo", 1);
	//redo 1 change
	editor.ExecuteFunction("document.undoManager", "Redo", 1);

In case some functions should not become visible in the Undo/Redo manager, it can be disabled

	//Hold changes
	editor.SetProperty("doc.undoManager", "holdChanges", true);
	//Don't hold changes
	editor.SetProperty("doc.undoManager", "holdChanges", false);

Grouping a set of operation in the undo stack manager.

Sometimes when a series of changes are executed they don't always need to be listed as separate steps in the undo/redo stack.
Therefor following function could be used:

//#1. this is called before you would make your series of changes
editor.ExecuteFunction("document.undoManager","BeginUndoableOperations","My grouped action");
 
//#2. Perform all your changes
//#3. End gathering of all changes made
editor.ExecuteFunction("document.undoManager.currentOperationGroup","EndOperations"); 

You can have it provided with your own name. 

Changing the cursor selection

To select a different cursor type, you can call:  

	editor.ExecuteFunction("document","SetCursor",name);

Where name could be "hand", "pointer", "text",...
An overview of the possible cursors can be found here: Editor Enumerations - CursorType

Working with PrivateData

It is possible to add or read PrivateData on a CHILI Object with javascript. (More info on PrivateData: PrivateData XML)

A PrivateData item is a key value pair. To add a PrivateDataItem to the selected frame (or use another objectdescriptor like "document")

	var frame = editor.GetObject("document.selectedFrame");
    if (frame !== null){
    	var privateItem = editor.ExecuteFunction("document.selectedFrame.privateData","Add"); 
    	editor.SetProperty("document.selectedFrame.privateData[" + privateItem.id + "]","name","yourownkey");
        editor.SetProperty("document.selectedFrame.privateData[" + privateItem.id + "]","value","This is the variable's value");
    }

When you  want to read out the value of this PrivateData item, you can use:

	var frame = editor.GetObject("document.selectedFrame");
	if (frame !== null){
    	var privateItem = editor.GetObject("document.selectedFrame.privateData[yourownkey]"); 
        console.log("-------private item: " + privateItem);
    	console.log("-------privateValue: " + privateItem.value);
	}

Retrieve mouse position in relation to the document (version ≥ v4.7)

Via this Javascript API functionality you can retrieve the position of the mouse in relation to the document, to for example insert a frame on that location in the document.
The function “document.GetMousePosition” returns: {page:pageindex, mouseX:x pos in workspace units, mouseY: y pos in workspace units}

position = editor.ExecuteFunction('document','GetMousePosition');
mousePositionValue.innerHTML = "page: " + position.page + ", x: " + position.mouseX + ", y:" + position.mouseY;

Retrieve location and size of controls on the editor canvas (HTML editor version ≥ v4.7)

Via this Javascript API functionality you can retrieve location and size of controls on the editor canvas in the editor canvas coordinate space (pixels). This will allow you for example to position a custom HTML based inline toolbar above a frame.

The function “control.GetEditorCanvasMetrics” returns: {x:x pos in pixels, y:y pos in pixels, width:width in pixels, height: height in pixels} for frames, pages, pages control, panels, …

var r = editor.ExecuteFunction("document.pages[0].frames[0].contentFrameControl","GetEditorCanvasMetrics");
var r = editor.ExecuteFunction("document.editor.leftPanels.panelContainers.controlsCollection[0].contentCtrl","GetEditorCanvasMetrics");
floatingElement.style.left = r.x + "px";
floatingElement.style.top = r.y + "px";
floatingElement.style.width = r.width + "px";
floatingElement.style.height = r.height + "px";
 
Some example paths:
page: document.pages[0].pageControl 
pages canvas: document.editor.pagePanel
panel: document.editor.leftPanels.panelContainers.controlsCollection[0].contentCtrl 
panel: document.workSpace.leftPanels[pages].controls[0].ctrl 
toolbar: document.editor.topPanel 
toolbar: document.workSpace.topToolBar.parentContainer 
frame: document.pages[0].frames[0].frameControl

OpenDocumentFromXml (HTML editor version ≥ v4.7)

 As of version 4.7  "DocumentGetHTMLEditorURL" doesn't require a DocumentID anymore. If not supplied the editor will launch without a document.
This will allow you to load a document XML from a location different from the CHILI DAM. The javascript API function "OpenDocumentFromXml(string documentXmlOrId, string workspaceXmlOrId = "")" will allow you to load an xml on the client side.

Both parameters for this function can be an XML or an ID.
In case of an ID this will look at the CHILI DAM for the document XML linked to that ID. In the other case an XML is loaded.

This function therefore allows you to store documents outside of the CHILI DAM on for example an Amazon or Azure server or ...

You can do this by calling:

editor.ExecuteFunction("document", "OpenDocumentFromXml", "documentIDorXML", "workspaceIDorXML");

Where "documentIDorXML" and "workspaceIDorXML" would obviously need to be replaced by a correct ID or XML

Accessing shapes from workspace library

 As of version 4.8.1.0 you're able to access the shapes workspace library using following code:

editor.GetObject("document.workSpace.defaultShapes");

GetPNGSnapshot Javascript function (editor version ≥ Version 4.12)

The Javascript function provides the ability to do a snapshot of a canvas control, allows users to get PNG snapshots of a particular page or frame in a document.

editor.ExecuteFunction("document.selectedFrame.frameControl","GetPNGSnapshot");
editor.ExecuteFunction("document.pages[0].pageControl","GetPNGSnapshot");

GetPageSnapshot JavaScript function (HTML editor version ≥ Version 5.1)

 This JavaScript function will return full-sized preview PNG's of documents with extended control possibilities.
When called, this function returns a snapshot of the requested page in png format, similar to the GetPNGSnapshot function.

This function can, for example, be used by customers who wish to show 3D live previews, with live updates in a separate frame or using a third-party 3D viewer.
Or by customers who wish to have a fast preview for use in something like a custom pages panel or a shopping basket.

editor.GetPageSnapshot('0', '1000x1000', ["Background Layer", "Content Layer", "Promo", "Watermark"], null, 'preview', true ); 
// page, size, visible layer array, null for default frame visibility, viewmode, transparant</pre>