goog.provide('sync.api.Editor');
goog.provide('sync.api.Editor.LinkOpenedEvent');
goog.provide('sync.api.Editor.WebappMessageReceived');
goog.require('goog.events.EventTarget');
goog.require('sync.api.WebappMessage');
goog.require('sync.actions.AttributeEditingActionsProvider');
/**
* A visual editor for an XML document.
*
* @constructor
*/
sync.api.Editor = function() {
goog.events.EventTarget.call(this);
};
goog.inherits(sync.api.Editor, goog.events.EventTarget);
/**
* Returns the actions manager for the current editor.
*
* @return {sync.api.ActionsManager} the actions manager of this editor.
*/
sync.api.Editor.prototype.getActionsManager = function() {
return null;
};
/**
* Returns the selection method of the editor.
*
* @return {sync.api.SelectionModel} The selection model.
*/
sync.api.Editor.prototype.getSelectionManager = function() {
return null;
};
/**
* A callback invoked when the asynchronous request for the XML content finishes.
* If the operation is successful, the first
* parameter is <code>null</code> and the second one is a string that represents
* the content. If case of an error, the first parameter is an object describing
* the error.
*
* @callback sync.api.Editor~onXmlContentReceived
*
* @param {object} error The error object, or null if the request was successful.
* @param {string} content The serialized XML content.
*/
/**
* Retrieves the content of the XML document asynchronously.
*
* @param {sync.api.Editor~onXmlContentReceived} callback The callback that will be called
* once the XML content is retrieved.
*/
sync.api.Editor.prototype.getXmlContent = function(callback) {
};
/**
* <p>Registers an enhancer for a type of form controls.
*
* <p>This registration should be performed before the editor is loaded, so that the enhancer can
* be used for the initial rendering of the document.
*
* @param {string} name The type of the form-control, which is the fully qualified name of the
* Java WebappFormControlRenderer class.
* @param {function(HTMLElement, sync.api.Editor)} enhancer The constructor for an instance of {@link sync.formctrls.Enhancer}
* that will be used to enhance form controls rendered by the specified Java renderer.
*
*/
sync.api.Editor.prototype.registerEnhancer = function(name, enhancer) {
};
/**
* <p>Notifies the server that the client is still alive.
*
* <p>When it receives the keep-alive message, the server makes sure to:
* <ul>
* <li>extend the document lifetime in memory
* <li>extend the license for the current user
* <li>keep the edited documents locked (if the URLStreamHandler supports locking).
* <ul>
*
* @param {number} interval The interval between two keepalive requests (in seconds).
*/
sync.api.Editor.prototype.enableKeepalives = function(interval) {
};
/**
* Sets the editor status as modified or not.
*
* If the editor is modified, when the user leaves the page, we
* warn them that there are unsaved changes.
*
* @param {boolean} dirty Whether the editor should be marked as dirty or not.
*/
sync.api.Editor.prototype.setDirty = function(dirty) {
};
/**
* @return {boolean} true if the document is read-only.
*/
sync.api.Editor.prototype.isDirty = function() {
};
/**
* Loads an editor with the given options.
*
* Should not be called if the editor was not already loaded
*
* @param {sync.api.Workspace.LoadingOptions} options The options used to open the editor.
*/
sync.api.Editor.prototype.load = function(options) {
};
/**
* Register a provider that is used to determine a custom interface used to edit an attribute.
*
* @param {sync.actions.AttributeEditingActionsProvider} attributeActionsProvider The actions provider.
*/
sync.api.Editor.prototype.registerAttributeActionsProvider = function(attributeActionsProvider) {
};
/**
* Event types generated by this editor.
*
* @enum {string}
*/
sync.api.Editor.EventTypes = {
/**
* Generated when a link is about to be opened.
*/
LINK_OPENED: 'link_openend',
/**
* Generated when an WebappMessage whose type is not handled by the webapp itself
* was reported on the server-side.
*/
CUSTOM_MESSAGE_RECEIVED: 'custom_message',
/**
* Generated when some editor-related actions were loaded.
*/
ACTIONS_LOADED: 'actions_loaded',
/**
* Generated the editor changes its dirty status.
*/
DIRTY_STATUS_CHANGED: 'dirty_status_changed'
};
/**
* Link opened event.
*
* <hr/>
* <p>
* Example of listening for this event:
* </p>
* <pre>
* goog.events.listen(editor, sync.api.Editor.EventTypes.LINK_OPENED, function(e) {
* // e is of type sync.api.Editor.LinkOpenedEvent
* });
* </pre>
*
* @param {string} url The URL to be opened
* @param {boolean} external Whether the link should be opened in an
* external application.
* @param {object=} params The parameters to pass to the new editor.
*
* @constructor
*/
sync.api.Editor.LinkOpenedEvent = function(url, external, params) {
this.type = sync.api.Editor.EventTypes.LINK_OPENED;
/**
* The URL that will be opened.
*
* @type {string}
*/
this.url = url;
/**
* Flag indicating whether the link is an external one, e.g. to a web page.
*
* @type {boolean}
*/
this.external = external;
/**
* Key-value mapping that contains parameters that will be passed to the new editor in case it is
* opened in the oXygen XML WebApp.
*
* @type {Object.<string,string>}
*/
this.params = params || {};
};
/**
* Event triggered when a webapp message is received from the server-side code.
*
* @param {Object} webappMessageJSON The webapp message sent by the server-side code, as JSON.
* @param {string} context The context in which the message is received.
*
* @constructor
*/
sync.api.Editor.WebappMessageReceived = function(webappMessageJSON, context) {
this.type = sync.api.Editor.EventTypes.CUSTOM_MESSAGE_RECEIVED;
this.message = new sync.api.WebappMessage(webappMessageJSON);
this.context = context;
};
/**
* The constants representing the context in which a webapp message is received.
*
* @enum {string}
*/
sync.api.Editor.WebappMessageReceived.Context = {
/**
* During the loading of the document.
*/
LOAD: 'load',
/**
* During the save operation.
*/
SAVE: 'save',
/**
* During the save as operation.
*/
SAVE_AS: 'save',
/**
* While the document is edited.
*/
EDITING: 'editing',
/**
* During a image request.
*/
IMAGE: 'image'
};
/**
* @typedef {Object} sync.api.Editor.ActionsLoadedEvent.ActionDescriptor The action descriptor.
* @property {boolean} compatible Whether the action is compatible with webapp. If not, it will not be used in the UI.
* @property {string=} icon16 The URL for a 16x16 icon to be used for the action.
* @property {string=} icon20 The URL for a 24x24 icon to be used for the action. Yes, 24x24, it's called icon20 for
* backwards compatibility reasons.
* @property {string} id The unique ID of the action.
* @property {string=} name The display name of the action.
* @property {string=} tooltip The tooltip description of the action.
* @property {string=} shortcut The shortcut of the action. Can use platform-generic modifiers (e.g. M1) similar with
* how they work in SA.
*/
/**
* @typedef {Object} sync.api.Editor.ActionsLoadedEvent.ActionEntry The descriptor for an action entry on the toolbar or in the context menu.
* @property {string} id The ID of the action to render on the toolbar.
* @property {string} type Equal to "action".
*/
/**
* @typedef {Object} sync.api.Editor.ActionsLoadedEvent.Sep A separator.
* @property {string} type Equal to "sep".
*/
/**
* @typedef {Object} sync.api.Editor.ActionsLoadedEvent.ActionsListDescriptor The descriptor for a toolbar, a drop-down menu on the toolbar, or context sub-menu.
* @property {string=} icon16 The URL for a 16x16 icon to be used to render the actions list.
* @property {string=} icon20 The URL for a 24x24 icon to be used to render the actions list. Yes, 24x24, it's called icon20 for
* backwards compatibility reasons.
* @property {HTMLElement=} iconDom A DOM element that will be used to render the actions list.
* @property {string=} name The display name of the toolbar.
* @property {string} type Equal to "list".
* @property {Array<sync.api.Editor.ActionsLoadedEvent.ActionsListDescriptor|sync.api.Editor.ActionsLoadedEvent.ActionEntry|sync.api.Editor.ActionsLoadedEvent.Sep>} children
* the list entries.
*/
/**
* @typedef {Object} sync.api.Editor.ActionsLoadedEvent.ContextMenuEntry The context menu entry descriptor.
* @property {string=} icon The URL for a 16x16 icon to be used for the toolbar.
* @property {string=} name The display name of the toolbar.
* @property {string} type Equal to "list".
* @property {Array<sync.api.Editor.ActionsLoadedEvent.ActionsListDescriptor|sync.api.Editor.ActionsLoadedEvent.ActionEntry|sync.api.Editor.ActionsLoadedEvent.Sep>} children
* the list entries.
*/
/**
* @typedef {Object} sync.api.Editor.ActionsLoadedEvent.ActionsConfiguration The object used to open the editor.
* @property {Array<sync.api.Editor.ActionsLoadedEvent.ActionDescriptor>} actions An array of actions descriptors.
* @property {Array<sync.api.Editor.ActionsLoadedEvent.ActionsListDescriptor>} toolbars An array of descriptors for
* actions lists that will be rendered as toolbars.
* @property {Array<sync.api.Editor.ActionsLoadedEvent.ContextMenuEntry>} contextualItems An array of descriptors for entries in
* the context menu.
*/
/**
* <p>Configuration of the actions that are going to be enabled for the current editor
* was loaded. This configuration may specify some of the:</p>
* <ul>
* <li>the action together with their shortcuts
* <li>the configuration of one of the toolbars
* <li>the configuration of the context menu
* </ul>
*
* <p>This event is triggered before the action are used, so changes to the configuration will
* take effect in the UI.
*
* <p>The toolbar and contextmenu configurations contain only action ids. In order to change the
* actual actions or to add more actions one can use the {@link sync.api.ActionsManager}.
*
* <hr/>
* <p>
* Example of listening for this event:
* </p>
* <pre>
* goog.events.listen(editor, sync.api.Editor.EventTypes.ACTIONS_LOADED, function(e) {
* // e is of type sync.api.Editor.ActionsLoadedEvent
* });
* </pre>
*
* @param {sync.api.Editor.ActionsConfiguration} actionsConfiguration A JSON object that represents the actions configuration.
*
* @constructor
*/
sync.api.Editor.ActionsLoadedEvent = function(actionsConfiguration) {
this.type = sync.api.Editor.EventTypes.ACTIONS_LOADED;
this.actionsConfiguration = actionsConfiguration;
};
/**
* This event should be triggered when the dirty status of the editor changes.
*
* <hr/>
* <p>
* Example of listening for this event:
* </p>
* <pre>
* goog.events.listen(editor, sync.api.Editor.EventTypes.DIRTY_STATUS_CHANGED, function(e) {
* // e is of type sync.api.Editor.DirtyStatusChangedEvent
* });
* </pre>
*
* @param {boolean} isDirty If the editor has unsaved changes, isDirty should be true.
* @constructor
*/
sync.api.Editor.DirtyStatusChangedEvent = function(isDirty) {
this.type = sync.api.Editor.EventTypes.DIRTY_STATUS_CHANGED;
this.isDirty = isDirty;
};