postMessage API List
The postMessage APIs are broadly divided into major categories:
Note: To enable postMessage APIs, you need to register your domain(s) with us. Please refer this link to know how to allow or add your postMessage domain list.
Send Messages to Writer iFrame
Under the send message section, you can post content, review as well as control document save from your host page.
The list of send message methods and their categories are tabulated below:
Content
- Create Named Range
- Find and Replace
- Get All Named Contents (Text / HTML)
- Get Named Content by ID (Text / HTML)
- Get Named Contents by Name (Text / HTML)
- Get Document Stats
- Insert Content (Text / HTML)
- Insert Named Content
- Insert Merge Field
- Insert Signer Field
- Lock Content
- Replace Named Content
- Submit Fillable Document
- Update Fillable Field Properties
- Unlock Content
Fillable Fields
- Insert Fillable Field
- Update Fillable Field by ID
- Update Fillable Fields by Name
- Update Fillable Fields
Named Range
- Get Named Range by ID
- Get Named Ranges by Name
- Get All Named Ranges
- Move Cursor To Named Range
- Remove Named Range by ID
- Remove Named Ranges by Name
Review
- Review Changes (AcceptAll / RejectAll)
Document
Format
Content
Create Named Range
Purpose
To create a named range for a selected text in Zoho Writer iFrame and it will return a range ID to your web application's host page.
"message": "CreateNamedRange",
"data": {
"name": <String> // Ex: "name": "My Content"
},
"oncomplete": function(data) {
console.log(JSON.stringify(data));
if (data.result === 1) {
// Handle Success
console.log("ID for the inserted named range", data.rangeId);
} else {
// Handle Failure
}
},
"onexception": function(data) {
// Handle exception
}
} );
Find and Replace
Purpose
To find a text and replace it with another text from your web application's host page to Zoho Writer iFrame.
XDC.postMessage ( {
"message": "FindAndReplace",
"data": {
"findText": <String>,
"replaceWith": <String>,
"isReplaceAll": <Boolean>
},
"oncomplete": function(data) {
console.log(JSON.stringify(data));
if (data.result === 1) {
// Handle Success
} else {
// Handle Failure
}
},
"onexception": function(data){
// Handle exception
}
} );
Get All Named Contents
Purpose
To get the contents of all the named ranges in the document.
"message": "GetAllNamedContents",
"data": {
"contentType": "text" // or HTML
},
"oncomplete": function(data) {
console.log(JSON.stringify(data));
if (data.result === 1) {
// Handle Success
} else {
// Handle Failure
}
},
"onexception": function(data) {
// Handle exception
}
} );
Get Named Content by ID
Purpose
To get the content in the named range using Named Range ID.
"message": "GetNamedContentById",
"data": {
"rangeId": <String>,
"contentType": "text" // or HTML
},
"oncomplete": function(data) {
console.log(JSON.stringify(data));
if (data.result === 1) {
// Handle Success
} else {
// Handle Failure
}
},
"onexception": function(data) {
// Handle exception
}
} );
Get Named Contents by Name
Purpose
To get the contents in the named range using Named Range name.
"message": "GetNamedContentsByName",
"data": {
"rangeName": <String>,
"contentType": "text" // or HTML
},
"oncomplete": function(data) {
console.log(JSON.stringify(data));
if (data.result === 1) {
// Handle Success
} else {
// Handle Failure
}
},
"onexception": function(data) {
// Handle exception
}
} );
Get Document Stats
Purpose
To get the number of words, characters and pages present in the document.
"message": "DocumentStats",
"oncomplete": function(data) {
console.log(JSON.stringify(data));
// {
// "words": "75",
// "characters": "522",
// "pages": "1"
// }
},
"onexception": function(data) {
// Handle exception
}
} );
Insert Content
Purpose
To insert text or HTML content from your web application's host page to Zoho Writer iFrame.
"message": "InsertContent",
"data": {
"content": " Happy Writing!",
"contentType": "text", // or HTML
"htmlFormat": "SourceFormat", // or DestinationFormat (This data is applicable only when the 'contentType: HTML' and its default value will be 'SourceFormat')
"scrollIntoView": "<Boolean>"
},
"oncomplete": function(data) {
console.log(JSON.stringify(data));
if (data.result === 1) {
// Handle Success
} else {
// Handle Failure
}
},
"onexception": function(data) {
// Handle exception
}
} );
Insert Named Content
Purpose
To insert a named text or HTML content in Zoho Writer iFrame and it will return a range ID to your web application's host page.
XDC.postMessage ( {
"message": "InsertNamedContent",
"data": {
"name":<String>, // Ex: "name": "New Content"
"content": " Happy Writing!",
"contentType": "text", // or HTML
"htmlFormat": "SourceFormat", // or DestinationFormat (This data is applicable only when the 'contentType: HTML' and its default value will be 'SourceFormat')
"scrollIntoView": "<Boolean>"
},
"oncomplete": function(data) {
console.log(JSON.stringify(data));
if (data.result === 1) {
// Handle Success
console.log("ID for the inserted named range", data.rangeId);
} else {
// Handle Failure
}
},
"onexception": function(data) {
// Handle exception
}
} );
Insert Merge Field
Purpose
To insert a merge field from your web application's host page to Zoho Writer iFrame.
XDC.postMessage ( {
"message": "InsertMergeField",
"data": {
"mergeFieldName":<String>,
"mergeFieldDisplayName":<String>,
"mergeFieldPlaceholderImage":<Url>,
"mergeFieldType":<MergeFieldType>,
"mergeFieldFormat":<MergeFieldFormat>
},
"oncomplete": function(data) {
console.log(JSON.stringify(data));
if (data.result === 1) {
// Handle Success
} else {
// Handle Failure
}
},
"onexception": function(data) {
// Handle exception
}
} );
Please refer the below table to insert different types of merge field with corresponding merge field format by replacing the values of <MergeFieldType> and <MergeFieldFormat>.
MergeFieldType | MergeFieldFormat | Description |
"barcode" | "code128", "code39", "ean13", "upc", "itf14", "msi", "pharmacode", "codabar" | To insert barcode as a merge field from your web application's host page to Zoho Writer iFrame. |
"checkbox" | NA | To insert checkbox as a merge field from your web application's host page to Zoho Writer iFrame. |
"image" | "fill_image_to_frame" "fit_image_to_frame" "resize_frame_to_image" "stretch_image_to_frame" | To insert image as a merge field from your web application's host page to Zoho Writer iFrame. |
"link" | NA | To insert link as a merge field from your web application's host page to Zoho Writer iFrame. |
"list" | "vertical" "horizontal" | To insert list as a merge field from your web application's host page to Zoho Writer iFrame. |
"multiline" | NA | To insert multiline as a merge field from your web application's host page to Zoho Writer iFrame. |
"number" | NA | To insert number as a merge field from your web application's host page to Zoho Writer iFrame. |
"phone" | "(###) ### ####" "###-###-####" | To insert phone number as a merge field from your web application's host page to Zoho Writer iFrame. |
"qrcode" | "plain_text" "url" "contact" "phone" "sms" "wifi" | To insert qrcode as a merge field from your web application's host page to Zoho Writer iFrame. |
"richtext" | NA | To insert rich text as a merge field from your web application's host page to Zoho Writer iFrame. |
"text" | NA | To insert text as a merge field from your web application's host page to Zoho Writer iFrame. |
Insert Signer Field
Purpose
To insert a signer field from your web application's host page to Zoho Writer iFrame.
XDC.postMessage ( {
"message": "InsertSignerField",
"data": {
"signerFieldType":<SignerFieldType>,
"recipient":<String>,
"signerFieldName":<String>,
"signerFieldFormat":<SignerFieldFormat>,
"dropdownOptions":<Array>,
"isMandatory":<Boolean>
},
"oncomplete": function(data) {
console.log(JSON.stringify(data));
if (data.result === 1) {
// Handle Success
} else {
// Handle Failure
}
},
"onexception": function(data) {
// Handle exception
}
} );
Please refer the below table to insert different types of signer field with corresponding signer field format by replacing the values of <SignerFieldType> and <SignerFieldFormat>.
SignerFieldType | SignerFieldFormat | Description |
"checkbox" | NA | To insert checkbox as a signer field from your web application's host page to Zoho Writer iFrame. |
"company" | NA | To insert company name as a signer field from your web application's host page to Zoho Writer iFrame. |
"custom_date" | "dd MMM yyyy" "MMM dd yyyy" | To insert custom date as a signer field from your web application's host page to Zoho Writer iFrame. |
"dropdown" | NA | To insert dropdown as a signer field from your web application's host page to Zoho Writer iFrame. |
"email" | NA | To insert email address as a signer field from your web application's host page to Zoho Writer iFrame. |
"fullname" | NA | To insert full name as a signer field from your web application's host page to Zoho Writer iFrame. |
"initial" | NA | To insert initial as a signer field from your web application's host page to Zoho Writer iFrame. |
"job_title" | NA | To insert job title as a signer field from your web application's host page to Zoho Writer iFrame. |
"sign_date" | NA | To insert the signing date as a signer field from your web application's host page to Zoho Writer iFrame. |
"signature" | NA | To insert signature as a signer field from your web application's host page to Zoho Writer iFrame. |
"textfield" | NA | To insert text field as a signer field from your web application's host page to Zoho Writer iFrame. |
Lock Content
Purpose
To lock the selected or unselected content from Zoho Writer iFrame to your web application's host page.
"message": "LockContent",
"data": {
"userInfo": [{"name": <String>, "id": <String>}, ..],
"redact": "<Boolean>",
"onselection": "<Boolean>" // By default, the value will be 'true' - to lock the selected content; 'false' - to lock the unselected content
},
"oncomplete": function(data) {
console.log(JSON.stringify(data));
if (data.result === 1) {
// Handle Success
} else {
// Handle Failure
}
},
"onexception": function(data) {
// Handle exception
}
} );
Replace Named Content
Purpose
To replace an existing named content in Zoho Writer iFrame with the given text or HTML content.
XDC.postMessage ( {
"message": "ReplaceNamedContent",
"data": {
"contentType": "text", // or HTML
"htmlFormat": "SourceFormat", // or DestinationFormat (This data is applicable only when the 'contentType: HTML' and its default value will be 'SourceFormat')
"rangeId": <String>, // or "rangeName": <String>
"replaceWith": <String>
},
"oncomplete": function(data) {
console.log(JSON.stringify(data));
if (data.result === 1) {
// Handle Success
} else {
// Handle Failure
}
},
"onexception": function(data){
// Handle exception
}
} );
Submit Fillable Document
Purpose
To submit a fillable document after filling the fillable fields from Zoho Writer iFrame to your web application's host page.
"message": "SubmitFillableDocument",
"data": { },
"oncomplete": function(data) {
console.log(JSON.stringify(data));
if (data.result === 1) {
// Handle Success
} else {
// Handle Failure
}
},
"onexception": function(data) {
// Handle exception
}
} );
Update Fillable Field Properties
Purpose
To update properties of the fillable fields inserted in the document from Zoho Writer iFrame to your web application's host page.
"message": "UpdateFillableFieldProperties",
"data": {
"propertyName": "maxLength",
"propertyValue": 1000,
"fillableFieldNames": ["Text Field 1", "Text Field 2", "Text Field 3"] //You can also pass the label of a single fillable field to update its property using the same key.
},
"oncomplete": function(data) {
console.log(JSON.stringify(data));
if (data.result === 1) {
// Handle Success
} else {
// Handle Failure
}
},
"onexception": function(data) {
// Handle exception
}
} );
Unlock Content
Purpose
To unlock the selected content from Zoho Writer iFrame to your web application's host page.
"message": "UnlockContent",
"data": {},
"oncomplete": function(data) {
console.log(JSON.stringify(data));
if (data.result === 1) {
// Handle Success
} else {
// Handle Failure
}
},
"onexception": function(data) {
// Handle exception
}
} );
Fillable Fields
Insert Fillable Field
Purpose
To insert a fillable field from your web application's host page to Zoho Writer iFrame.
XDC.postMessage ( {
"message": "InsertFillableField",
"data": {
"fillableFieldType": <FieldType>,
"fillableFieldName": <String>,
"fillableFieldValue": <FieldValue>
},
"oncomplete": function(data) {
console.log(JSON.stringify(data));
if (data.result === 1) {
// Handle Success
console.log("ID for the inserted fillable field", data.fillableFieldId);
} else {
// Handle Failure
}
},
"onexception": function(data) {
// Handle exception
}
} );
Please refer the below table to insert different types of fillable fields by replacing the values of <FieldType> and <FieldValue>.
FieldType | Data Type | FieldValue | Description |
"checkbox" | Boolean | true / false | To insert checkbox as a fillable field from your web application's host page to Zoho Writer iFrame. |
"currency" | Number | Integer | To insert currency as a fillable field from your web application's host page to Zoho Writer iFrame. |
"date" | Number | in Milliseconds | To insert date as a fillable field from your web application's host page to Zoho Writer iFrame. |
"email" | String | Ex: xyz@zylker.com | To insert email as a fillable field from your web application's host page to Zoho Writer iFrame. |
"number" | Number | Integer | To insert number as a fillable field from your web application's host page to Zoho Writer iFrame. |
"percent" | Number | Integer | To insert percent as a fillable field from your web application's host page to Zoho Writer iFrame. |
"phone" | Number | Integer | To insert phone as a fillable field from your web application's host page to Zoho Writer iFrame. |
"selectbox" | Array | ["option1","option2"] | To insert selectbox as a fillable field from your web application's host page to Zoho Writer iFrame. |
"singleline" | String | NA | To insert single line as a fillable field from your web application's host page to Zoho Writer iFrame. |
Update Fillable Field by ID
Purpose
To update a fillable field using the fillable field ID.
XDC.postMessage ( {
"message": "UpdateFillableFieldById",
"data": {
"fillableFieldId": <String>,
"fillableFieldValue": <String>
},
"oncomplete": function(data) {
console.log(JSON.stringify(data));
if (data.result === 1) {
// Handle Success
} else {
// Handle Failure
}
},
"onexception": function(data) {
// Handle exception
}
} );
Update Fillable Fields by Name
Purpose
To update fillable fields with respect to fillable field name.
XDC.postMessage ( {
"message": "UpdateFillableFieldsByName",
"data": {
"fillableFieldName": <String>,
"fillableFieldValue": <String>
},
"oncomplete": function(data) {
console.log(JSON.stringify(data));
if (data.result === 1) {
// Handle Success
} else {
// Handle Failure
}
},
"onexception": function(data) {
// Handle exception
}
} );
Update Fillable Fields
Purpose
To update multiple fillable fields at the same time.
XDC.postMessage ( {
"message": "UpdateFillableFields",
"data": {
"fillableFieldValues": {
field_label_1= field_value_1,
field_label_2= field_value_2
}
},
"oncomplete": function(data) {
console.log(JSON.stringify(data));
if (data.result === 1) {
// Handle Success
} else {
// Handle Failure
}
},
"onexception": function(data) {
// Handle exception
}
} );
Named Range
Get Named Range by ID
Purpose
To get or retrieve the named range for the given ID.
XDC.postMessage ( {
"message": "GetNamedRangeById",
"data": {
"rangeId": <String>
},
"oncomplete": function(data) {
console.log(JSON.stringify(data));
if (data.result === 1) {
// Handle Success
} else {
// Handle Failure
}
},
"onexception": function(data) {
// Handle exception
}
);
Get Named Ranges by Name
Purpose
To get or retrieve the named ranges for the given name.
XDC.postMessage ( {
"message": "GetNamedRangesByName",
"data": {
"rangeName": <String>
},
"oncomplete": function(data) {
console.log(JSON.stringify(data));
if (data.result === 1) {
// Handle Success
} else {
// Handle Failure
}
},
"onexception": function(data){
// Handle exception
}
);
Get All Named Ranges
Purpose
To get or retrieve all the named ranges.
XDC.postMessage ( {
"message": "GetAllNamedRanges",
"oncomplete": function(data) {
console.log(JSON.stringify(data));
if (data.result === 1) {
// Handle Success
} else {
// Handle Failure
}
},
"onexception": function(data) {
// Handle exception
}
);
Move Cursor To Named Range
Purpose
To move the cursor to the named range from your web application's host page and scroll to view in Zoho Writer iFrame.
XDC.postMessage ( {
"message": "MoveCursorToNamedRange",
"data": {
"rangeId": <String>
},
"oncomplete": function(data) {
console.log(JSON.stringify(data));
if (data.result === 1) {
// Handle Success
} else {
// Handle Failure
}
},
"onexception": function(data){
// Handle exception
}
);
Remove Named Range by ID
Purpose
To delete a named range for the given ID.
XDC.postMessage ( {
"message": "RemoveNamedRangeById",
"data": {
"rangeId": <String>,
"deleteContent": <Boolean>
},
"oncomplete": function(data) {
console.log(JSON.stringify(data));
if (data.result === 1) {
// Handle Success
} else {
// Handle Failure
}
},
"onexception": function(data) {
// Handle exception
}
);
Remove Named Ranges by Name
Purpose
To delete the named ranges for the given name.
XDC.postMessage ( {
"message": "RemoveNamedRangesByName",
"data": {
"rangeName": <String>,
"deleteContent": <Boolean>
},
"oncomplete": function(data) {
console.log(JSON.stringify(data));
if (data.result === 1) {
// Handle Success
} else {
// Handle Failure
}
},
"onexception": function(data) {
// Handle exception
}
};
Format
Set Format
Purpose
To set the data in a defined format (say JSON) and send to a Writer document from the host page.
XDC.postMessage ( {
"message": "SetFormat",
"data": {
"format": <JSON>
},
"oncomplete": function(data) {
console.log(JSON.stringify(data));
if (data.result === 1) {
// Handle Success
} else {
// Handle Failure
}
},
"onexception": function(data) {
// Handle exception
}
} );
Review
Review Changes
Purpose
To review the content and accept or reject changes in the Writer document.
XDC.postMessage ( {
"message": "ReviewChanges",
"data": {
"action": "AcceptAll" // or "RejectAll"
},
"oncomplete": function(data) {
console.log(JSON.stringify(data));
if (data.result === 1) {
// Handle Success
} else {
// Handle Failure
}
},
"onexception": function(data) {
// Handle exception
}
} );
Document
Export Document
Purpose
To export the document in the required format from Zoho Writer iFrame to your web application's host page.
"message": "ExportDocument",
"data": {
"format": <String> // pdf/doc/docx/rtf/odt/txt/html/zip/epub/zdoc
},
"oncomplete": function(data) {
console.log(JSON.stringify(data));
if (data.result === 1) {
// Handle Success
} else {
// Handle Failure
}
},
"onexception": function(data) {
// Handle exception
}
} );
Save Document
Purpose
To "save" the Writer document.
XDC.postMessage ( {
"message": "SaveDocument",
"data": {
"hideSaveButton": <Boolean>, // Default value will be true
"forceSave": <Boolean>, // Default value will be true
"saveUrlParams": <JSON>,
"format": <String> // pdf/doc/docx/rtf/odt/txt/html/zip/epub/zdoc
},
// Use "SaveDocumentResponse" event for oncomplete
"onexception": function(data) {
// Handle exception
}
} );
Receive Messages from Writer iFrame
Under the receive message section, you can obtain multiple notifications about document status from Writer iFrame to your host page.
The list of receive message methods and their categories are tabulated below:
Document
- Document Load In Progress
- Document Load Complete
- Document Modified
- Fillable Field Inserted
- Fillable Field Updated
- Fillable Fields Deleted
- Named Ranges Deleted
- Named Ranges In Selection
- Save Document Response
Selection
Document
Document Load In Progress
Purpose
To receive the "Document Load In Progress" notification from Writer iFrame to the host page.
XDC.receiveMessage("DocumentLoadInProgress", function(data) {
console.log(data);
} );
Document Load Complete
Purpose
To receive the "Document Load Complete" notification from Writer iFrame to the host page.
XDC.receiveMessage("DocumentLoadComplete", function(data) {
console.log(data);
} );
Document Modified
Purpose
To receive the "Document Modified" notification from Writer iFrame to the host page.
XDC.receiveMessage("DocumentModified", function(data) {
console.log(data);
} );
Fillable Field Inserted
Purpose
To receive a notification when the "Fillable Field" is inserted from Writer iFrame to the host page.
XDC.receiveMessage("FillableFieldInserted", function(data) {
console.log(data);
} );
Fillable Field Updated
Purpose
To receive a notification when the "Fillable Field" is updated from Writer iFrame to the host page.
XDC.receiveMessage("FillableFieldUpdated", function(data) {
console.log(data);
} );
Fillable Fields Deleted
Purpose
To receive a notification when the "Fillable Fields" are deleted from Writer iFrame to the host page.
XDC.receiveMessage("FillableFieldsDeleted", function(data) {
console.log(data);
} );
Named Ranges Deleted
Purpose
To receive a notification when the "Named Ranges" are deleted from Writer iFrame to the host page.
XDC.receiveMessage("NamedRangesDeleted", function(data) {
console.log(data);
} );
Named Ranges In Selection
Purpose
To receive a notification when the "Named Ranges" are selected from Writer iFrame to the host page.
XDC.receiveMessage("NamedRangesInSelection", function(data) {
console.log(data);
} );
Save Document Response
Purpose
To receive a save document response from Writer iFrame to the host page.
XDC.receiveMessage("SaveDocumentResponse", function(data) {
console.log(data);
} );
Selection
Selection Changed
Purpose
To receive a notification from Writer iFrame on a change of selected text in a document.
XDC.receiveMessage("SelectionChanged", function(data) {
console.log(data);
} );
Note: To know about the list of error handling cases in postMessage API's, refer here.