API for calling Backup add-on from custom code

Overview

API is available to all who've purchased SaaS (Ultimate) or OEM license. It lets you ability to interact with Backup add-on by Application Programming Interface. API is not required to run add-on with CKEditor or TinyMCE: it only for connecting your custom JS code with the plugin and for very deep changins logic of add-on.

To enable API fill the option jsplus_backup_api_key with your personal API key. You can get it by opening new support ticket (please write there on what domain you will use the API).

Technically API is JavaScript object containing different methods. Every such object is attached to editor instance you are runing plugin in. You can get this object by calling:

CKEDITOR.instances["editor_id"].api["jsplus_backup"]

All items in this API have one of the two types: method or event.

You can call any method any time or redefine it. Due to the add-on uses the same API inside you will change algorithm of the plugin setting your own methods instead of existing one.
Not all methods is great idea to redefine. All recommendations about reimplementing logic of the methods you can find in description of any method.

Another part of API are events. You can attach your own listener to existing method by calling event.addListener(func) function, or remove existing listeners by event.removeListener(func) or event.clearListeners().
You can also call event.call(parameters) to call the method every time you need.
Please do not redefine events until you fully understand why you are doing it.

API documentation

backupNow(): int
Performs backup and returns timestamp: a time in seconds since Unix epoch (Jan 1, 1970).
No redefine, use saveBackup function instead.
Options: jsplus_backup_save_empty
Calls: getContent, areContentsEqual, saveBackupAndCallListeners
Called by: restoreAndCallListeners

saveBackupAndCallListeners(timestamp: int, html: string)
Calls ``saveBackup`` function with specified parameters and according events listeners before and after.
No redefine, use saveBackup function instead.
Events: onBeforeBackupSave, onAfterBackupLoad
Calls: saveBackup
Called by: backupNow

saveBackup(timestamp: int, html: string)
Performs backing up HTML content with specified timestamp into the storage.
Redefine for changing the way of storing backed up data.
Calls: getAll, getSymbolsCount, getWordsCount, getImagesCount
Called by: saveBackupAndCallListeners

restore(timestamp: int)
Restores a snapshot with the specified timestamp from the storage.
No redefine, redefine get method if you want to load data from your custom database.
Calls: get
Called by: restoreAndCallListeners

restoreAndCallListeners(timestamp: int)
Calls ``restore`` function and according event listeners. Also backs up current content before loading selected.
No redefine, its better to reimplement restore function to change content loading logic.
Options: jsplus_backup_save_before_load
Calls: restore, backupNow

getAll()
Retuns all snapshot as a structure like `[{html: string, words: int, symbols: int}, ...]`. This method is responsible to getting info about all available backups and theirs contents.
Redefine redefine this method for custom collecting all data, not forgetting about to filter it by getInstanceId.
Calls: getSymbolsCount, getWordsCount, getImagesCount
Called by: saveBackup, delete, getLastBackedUpContent

get(timestamp: int)
Retuns info about existing backup with the specified timestamp in format {html: string, words: int, symbols: int}
Redefine reimplementing this function is the way to load data from your custom storage (i. e. SQL Database).
Called by: restore

clear()
Removes all backups with current instance ID from the storage.
Redefine if you use custom DB to store backups.

delete(timestamp)
Deletes snapshot with the specified timestamp from the storage. This function is not used in standard implementation by the plugin but included here for your API needs only.
Redefine if you need API call for deleting backup from your custom storage.
Calls: getAll, saveBackupsToLocalStorage

getInstanceId(): string
The function is used almost by every all other functions. It returnes an unique identifier used for distinguishing different instances of editor (CKEditor and TinyMCE). By default it formes ID by connecting current URL and name of the editor (based on ID HTML attribute).
Redefine for example if your storing algorithm must have different snapshots stacks for different users: in this case just add user IDs to the return result.

formatSize(bytesNumber): string
Formats size in human format (i. e. 1250 bytes = "1.2 Kb").
Redefine if you want to use another size format (for example in KiB/MiB/...).

formatCount(number): string
Formats the number (of symbols, words and images).
Redefine if you want to format numbers in your own way.

formatDate(timestamp): string
Formats timestamp from integer to human form. In basic implementation it converts value by format specified in ```jsplus_backup_date_format``` parameter (`HH:MM mmm d, yyyy` by default).
Redefine if you want to see dates in UI in some specific format.
Options: jsplus_backup_date_format

getContent(): string
Returnes current content from the editor.
No redefine, this function is connector to CKEditor or TinyMCE.
Called by: backupNow

isContentEmpty(html): boolean
Checks is the content really blank. Content in HTML format may have many invisible tags but no readable words or images. Current implementation of this function tries to filter invisible content and perform regular check for string is blank after that.
Redefine if you have better implementation.

getWordsCount(html): integer
Returns a number of words displayed to the viewer (without calculating number of tags and other technical info).
Redefine if you have your own algorithm for calculating content words number inside HTML markup.
Called by: saveBackup, getAll

getSymbolsCount(html): integer
Returns a number of symbols displayed to the viewer (without calculating number symbols in tags and other markup).
Redefine if you have your own algorithm for calculating content symbols number inside HTML markup.
Called by: saveBackup, getAll

getImagesCount(html): integer
Returns a number of images displayed to the viewer. By default it calcultes the number of `` tags.
Redefine if you have your own algorithm for calculating content images number inside HTML markup.
Called by: saveBackup, getAll

getLastBackedUpContent(): string
Returns the last HTML saved by this add-on for current editor instance. This value is used for comparing current content with previous one (to avoid duplicate snapshots).
Redefine for faster getting last content when using custom DB (otherwise is will call slow getAll method and get the last backup from there).
Calls: getAll

areContentsEqual(html1, html2): boolean
Compares contents of two snapshots. Used before saving new content (if previous one is equals to current the saving will be interrupted). In default implementation it only compares two strings.
Redefine i. e. if you need to compare content after filtering some tags (for example invisible).
Called by: backupNow

onBeforeBackupSave(instanceId: string, timestamp: int, html: string)
Called before saving the content as new snapshot.
Event, use standard events API to attach or detach listeners.
No redefine, add new listener with onBeforeBackupSave.addListener(func) instead of redefining this function
Stops current method execution if even one of the listeners returns false

onAfterBackupSave(instanceId: string, timestamp: int, html: string)
Called after saving the content as new snapshot.
Event, use standard events API to attach or detach listeners.
No redefine, add new listener with onAfterBackupSave.addListener(func) instead of redefining this function

onBeforeBackupLoad(instanceId: string, timestamp: int, html: string)
Called before loading the backup to the editor.
Event, use standard events API to attach or detach listeners.
No redefine, add new listener with onBeforeBackupLoad.addListener(func) instead of redefining this function

onAfterBackupLoad(instanceId: string, timestamp: int, html: string)
Called before loading the backup to the editor.
Event, use standard events API to attach or detach listeners.
No redefine, add new listener with onAfterBackupLoad.addListener(func) instead of redefining this function