Class: XMLEditor

XMLEditor()

A web-based XML editor which is implemented as a client of xxeserver, the XMLmind XML Editor WebSocket server.

Constructor

new XMLEditor()

Constructs an XML editor, the implementation of custom HTML element <xxe-client>.
Source:

Classes

XMLEditor

Members

autoConnect :boolean

Get/set the autoConnect property of this XML editor.

If true, automatically connect to the server when the first time any listDocumentTemplates, newDocument, newRemoteFile, openDocument or openRemoteFile is invoked.

Default value: true.

Type:
  • boolean
Source:

autoRecover :boolean

Get/set the autoRecover property of this XML editor.

If true, automatically recover the document being edited when the connection was lost by this XMLEditor without first explicitely closing the document. This happens for example, when the user clicks the Reload button of the web browser.

Default value: true.

Type:
  • boolean
Source:

button2PastesText :boolean

Get/set the button2PastesText property of this XML editor.

If true, selecting text by dragging the mouse automatically copies this text to a dedicated private clipboard. Then clicking button #2 (middle button) elsewhere pastes copied text at the clicked location. This allows to emulate the X Window Primary Selection on all platforms.

Note that the X Window Primary Selection is not natively supported on platforms where it should be (e.g. Linux) because there is no JavaScript API or clever trick allowing to update the Primary Selection without updating the System Clipboard at the same time.

Default value: false.

Type:
  • boolean
Source:

clientProperties :string

Get/set the clientProperties property of this XML editor.

Client properties consists in a number of property name/property value pairs which are typically used to associate the user of this XML editor with the XXE server connection (XMLEditor server-side peer).

On the server side, these client properties are seen by the XMLEditor server-side peer as Java system properties, which makes them usable in different contexts (macros, access to remote file systems, etc).

This syntax of the clientProperties property is: 

properties = property [ ';' property ]*
property = name '=' value

In a property value, character ';' may be escaped as '\u003B'. Example: 

user=john;group=reviewers\u003Bauthors;DAV.password=changeit

Default value: no client properties.

Type:
  • string
Source:

clipboardIntegration :ClipboardIntegration

Get the clipboardIntegration property of this XML editor which contains the object implementing the system clipboard integration.
Type:
Source:

configurationName :string

Get the configurationName property of this XML editor which contains the name of the configuration associated to the document being edited; null if no configuration is associated to the document or if no document is currently being edited.
Type:
  • string
Source:

connected :boolean

Get the connected property of this XML editor which tests whether this editor is connected to the XMLmind XML Editor websocket server.
Type:
  • boolean
Source:

diffSupport :number

Get the diffSupport property of this XML editor which tests whether the comparison of the revisions of the document being edited has been enabled.
  • 0: not enabled. (Or no document is currently being edited.)
  • 1: enabled.
  • 2: enabled and all the revisions are stored in the document.
Type:
  • number
Source:

documentFileHandle :FileSystemFileHandle

Get/set the documentFileHandle property of this XML editor which contains the local file handle of edited document; null if there is no document currently being edited or if edited document has no local file handle (newly created document, not a local file or local file handles not supported).

This FileSystemFileHandle is needed by the application hosting this XML editor to save the document content to disk. See The File System Access API.

Type:
  • FileSystemFileHandle
Source:

documentIsOpened :boolean

Get the documentIsOpened property of this XML editor which tests whether a document is currently opened in the editor.
Type:
  • boolean
Source:

documentUID :string

Get the documentUID property of this XML editor which contains the UID of the document being edited if any; null otherwise.
Type:
  • string
Source:

documentURI :string

Get the documentURI property of this XML editor which contains the URI of the document being edited if any; null otherwise.
Document having a storage managed by client code
The URI (identifier) of the document which is used by client code.
Document having a storage managed by XXE server
The URL (location) of the document which is used by XXE server.
Type:
  • string
Source:

documentURL :string

Get the documentURL property of this XML editor which contains the URL of the document being edited if any; null otherwise.
Document having a storage managed by client code
An internal, private, URL representation of the URI (identifier) of the document, which is useful only to XXE server. Cannot be used by XXE server to actually access the document, as the storage of the document is managed by client code. (This URL is needed because XXE server exclusively uses hierarchical URLs and not URIs.)
Document having a storage managed by XXE server
The URL (location) of the document which is used by XXE server. Identical to documentURI.
Type:
  • string
Source:

documentView :DocumentView

Get the documentView property of this XML editor which contains the DocumentView contained in this XMLEditor.
Type:
Source:

isRemoteFile :boolean

Get the isRemoteFile property of this XML editor which tests whether the storage of the document being edited is managed by XXE server.

Value is true if the storage is managed by XXE server; false if the storage managed by client code (or if no document is being edited).

Type:
  • boolean
Source:

namespacePrefixes :array

Get the namespacePrefixes property of this XML editor which contains an (possibly empty) array containing namespace prefix/URI pairs; null if no document is currently being edited.

The default namespace (having an empty prefix), if any, is always the last pair of returned array.

Type:
  • array
Source:

readOnlyDocument :boolean

Get the readOnlyDocument property of this XML editor which tests whether the document has been opened in read-only mode.
Type:
  • boolean
Source:

resourceStorage :ResourceStorage

Get/set the resourceStorage property of this XML editor.

This resource storage object will be used only for documents whose storage is managed by client code.

Default value: dummy resource storage object ResourceStorage.

Type:
Source:

saveAsNeeded :boolean

Get the saveAsNeeded property of this XML editor which tests whether plain save or save as is needed to save the document being edited.

If saveNeeded===true and saveAsNeeded===true, then the client code must prompt the user for a save URI or URL and invoke saveDocumentAs rather than saveDocument.

Type:
  • boolean
Source:

saveNeeded :boolean

Get the saveNeeded property of this XML editor which tests whether the document being edited has been modified and thus needs to be saved.
Type:
  • boolean
Source:

searchReplaceIsVisible :boolean

Get the searchReplaceIsVisible property of this XML editor which tests whether the text search/replace pane is currently displayed.
Type:
  • boolean
Source:

serverURL :string

Get/set the serverURL property of this XML editor, which specifies the ws:// or wss:// URL of the XMLmind XML Editor websocket server.

Default value: automatically determined using the URL of the HTML page containing this XMLEditor.

Type:
  • string
Source:

Methods

addEventListener(type, listener)

Register specified event listener with this XMLEditor.
Parameters:
Name Type Description
type string the type of an XMLEditorEvent, for example: "documentOpened", "documentClosed", etc.
listener function the event handler, a function accepting an XMLEditorEvent as its argument.
Source:

addRequestListener(listener)

Register specified request listener with this XMLEditor.

Not for general use; only to debug an XMLEditor.

A request listener is a function having 3 arguments: boolean auto_connect, string request_name, array request_arguments, response.

For each request, this function is called twice: first time with a undefined response, before the request is sent to the server; second time with a response, after the response to the request is received from the server. This response may be any value (including null) or an Error.

Parameters:
Name Type Description
listener function the listener to be registered.
Source:

cacheResource(resource)

Cache specified resource.

Useful to cache the (non-cached) resources returned by XMLEditor#loadResource, XMLEditor#loadResource and XMLEditor#openResource.

Parameters:
Name Type Description
resource Resource the resource to be cache.
Source:
See:

closeDocument(discardChangesopt) → {Promise}

Closes the document being edited.
Parameters:
Name Type Attributes Default Description
discardChanges boolean <optional>
 false specifies whether the changes made to the document should be discarded.
Source:
See:
Returns:
A Promise containing a boolean or an Error. The value of the promise is true if no document is currently opened in the editor or if the document has been successfully closed; false if the document has been modified and discardChanges===false. An error is reported if, for any reason, the operation fails.
Type
Promise

connect() → {Promise}

Explicitly connect to the XMLmind XML Editor websocket server (XXE server for short).

Normally invoking this method is not useful because the XMLEditor#autoConnect property being true by default, this XML editor will automatically connect to the websocket server when needed to.

Source:
See:
Returns:
A Promise containing true (already connected or successful connection) or an Error. An error is reported if, for any reason, the operation fails.
Type
Promise

createDirectory(url) → {Promise}

Create the directory on the XXE server side having specified location.

Parent directories are automatically created if needed to.

Parameters:
Name Type Description
url string the URL (absolute location) of the directory to be created.
Source:
Returns:
A Promise containing true if the directory has been created, false if it already existed or an Error.
Type
Promise

disconnect() → {Promise}

Explicitly disconnect from the XMLmind XML Editor websocket server (XXE server for short).

Normally invoking this method is not useful. This is done when the web browser tab or window containing this XMLEditor is closed.

Source:
See:
Returns:
A Promise containing true (already disconnected or successful disconnection) or an Error. An error is reported if, for any reason, the operation fails.
Type
Promise

fetchResource(uri) → {Promise}

Fetch resource having specified URI from resource cache.

In principle, there is no need to directly invoke this method.

Parameters:
Name Type Description
uri string absolute URI of the resource to be fetched.
Source:
See:
Returns:
a Resource if found in cache; null otherwise.
Type
Promise

getCommandState(cmdName, cmdParam) → {array}

Returns the state of specified command. This state is automatically updated after each received EditingContextChangedEvent.

Used by some XMLEditor parts and also by some commands (e.g. ContextualMenuCmd).

Parameters:
Name Type Description
cmdName string command name.
cmdParam string command parameter. May be null.
Source:
Returns:
an array containing 3 items:
  • enabled, a boolean,
  • detail, an object (generally null) which depends on the command,
  • inSelectedState, null if the command has no selected state; true if the command is in selected state, false if the command is in non-selected state.
Returns null if specified command is not one of the "contextual commands" registered with this XMLEditor.
Type
array

getDocument(formattingOptionsopt) → {Promise}

Get the XML source of the document being edited.

By default, the XML source is formatted using the save options found in the user preferences and the save options found in the configuration of the document being edited (if any). However parameter formattingOptions may be used to change this default formatting to a certain extent. See below.

Parameters:
Name Type Attributes Default Description
formattingOptions object <optional>
 null Changes the formatting defaults described above.
KeyValueDescription
indent Integer Any strictly negative values means: do not indent. Otherwise (even 0), indent the XML source.
maxLineLength Strictly positive integer Specifies the maximum line length for elements containing text interspersed with child elements. Ignored if indent<0.
addOpenLines boolean If true, an open line is added between the child elements of a parent element (if the content model of the parent only allows child elements). Ignored if indent<0.
favorInteroperability boolean If true, favor the interoperability with HTML as recommended by the XHTML spec. Use this option only for XHTML documents.
Source:
Returns:
A Promise containing containing the XML source, null or an Error. The value of the promise is null if there is no document currently opened in this editor. An error is reported if, for any reason, the operation fails.

Note that returned XML source is a string which generally (but not always, depending on favorInteroperability) starts with an XML declaration (<?xml version= encoding= ?>), so you may need to remove it or modify it before serializing this source.

Type
Promise

getResource(uri) → {Promise}

Same as XMLEditor#loadResource except that this method first attempts to fetch the resource from the cache.

Note that resources actuall loaded by this method are automatically cached.

Parameters:
Name Type Description
uri string absolute URI of the resource to be obtained.
Source:
See:
Returns:
A Promise containing a Resource or an Error.
Type
Promise

listDocumentTemplates() → {Promise}

Lists available document templates.
Source:
Returns:
A Promise containing an array or an Error. The value of the promise is an array of arrays (branches) or strings (leafs), organized as a hierarchical structure.
  • A leaf is a template name.
  • A branch always starts with a "+" or "-" "CATEGORY_NAME" string and contains sub-arrays (sub-branches) and/or strings (leafs).
  • "+" specifies that the branch should be initially expanded. "-" specifies that the branch should be initially collapsed.

An error is reported if, for any reason, the operation fails.

Type
Promise

listFiles(url) → {Promise}

List the content of the directory on the XXE server side having specified location.
Parameters:
Name Type Description
url string the URL (absolute location) of the file to be listed.
Source:
Returns:
A Promise containing an (possibly empty) object or array of objects or an Error.

An empty object means that specified file does not exist.

A non empty object means that specified file is a file and not a directory.

Otherwise the result is an array containing one object per directory entry. The directory itself is not included. The objects are lexicographically sorted by their names.

An object contains:

name
Name of file or subdirectory.
directory
true if it is a subdirectory; false otherwise.
size
The size in bytes of the file; -1 for a subdirectory.
date
The date of the last modification of the file or subdirectory, the number of seconds since the ECMAScript/UNIX Epoch (January 1, 1970, 00:00:00 UTC); -1 if unknown.
Type
Promise

listRootDirectories() → {Promise}

Lists the root directories on the XXE server side which may be accessed by this XML editor.
Source:
Returns:
A Promise containing (possibly empty) array or an Error.

An empty array means that file access on the XXE server side is not allowed.

Otherwise an array contains one object per root directory.

An object contains:

label
A short label for use in the UI (e.g. "Home", "Computer").
uri
The absolute URI of the root directory. Ends with "/".
readonly
If true, file modifications of any kind anywhere inside this root directory will be denied.
Type
Promise

loadResource(uri) → {Promise}

Load document resource having specified URI.
Parameters:
Name Type Description
uri string absolute URI of the resource to be loaded.
Source:
Returns:
A Promise containing a Resource or an Error.

IMPORTANT: the resource data is null if there is no way load a resource knowing just its URI. This is for example the case of local files.

Type
Promise

newDocument(categoryName, templateName, docURI) → {Promise}

Creates and opens a new document whose storage is to be managed by client code.
Parameters:
Name Type Default Description
categoryName string the category of the document template. For example, "DocBook v5+/5.1".
templateName string the name of the document template. For example, "Book".
docURI string null the URI (an identifier) of the newly created document. May be null in which case an "untitled" URI is automatically computed.
Source:
See:
Returns:
A Promise containing a boolean or an Error. The value of the promise is true if new document has successfully been opened; false if currently opened document first needs to be saved. An error is reported if, for any reason, the operation fails.
Type
Promise

newDocumentFromTemplate(templateContent, docURI) → {Promise}

Creates and opens a new document whose storage is to be managed by client code.
Parameters:
Name Type Default Description
templateContent string | Blob | ArrayBuffer the XML contents of the document template.
docURI string null the URI (an identifier) of the newly created document. May be null in which case an "untitled" URI is automatically computed.
Source:
See:
Returns:
A Promise containing a boolean or an Error. The value of the promise is true if new document has successfully been opened; false if currently opened document first needs to be saved. An error is reported if, for any reason, the operation fails.
Type
Promise

newRemoteFile(categoryName, templateName, docURL) → {Promise}

Creates and opens a new document whose storage is to be managed by XXE server.
Parameters:
Name Type Default Description
categoryName string the category of the document template. For example, "DocBook v5+/5.1".
templateName string the name of the document template. For example, "Book".
docURL string null the URL (a location) of the newly created document. May be null in which case an "untitled" URL is automatically computed.
Source:
See:
Returns:
A Promise containing a boolean or an Error. The value of the promise is true if new document has successfully been opened; false if currently opened document first needs to be saved. An error is reported if, for any reason, the operation fails.
Type
Promise

newRemoteFileFromTemplate(templateContent, docURL) → {Promise}

Creates and opens a new document whose storage is to be managed by XXE server.
Parameters:
Name Type Default Description
templateContent string | Blob | ArrayBuffer the XML contents of the document template.
docURL string null the URL (a location) of the newly created document. May be null in which case an "untitled" URL is automatically computed.
Source:
See:
Returns:
A Promise containing a boolean or an Error. The value of the promise is true if new document has successfully been opened; false if currently opened document first needs to be saved. An error is reported if, for any reason, the operation fails.
Type
Promise

openDocument(docContent, docURI, readOnlyopt) → {Promise}

Opens a document, whose storage is managed by client code, whose content is docContent.
Parameters:
Name Type Attributes Default Description
docContent string | Blob | ArrayBuffer the XML contents of the document.
docURI string the URI (an identifier) of the document. May not be null.
readOnly boolean <optional>
 false if true, the document is opened in read-only mode.
Source:
See:
Returns:
A Promise containing a boolean or an Error. The value of the promise is true if the document has successfully been opened; false if currently opened document first needs to be saved. An error is reported if, for any reason, the operation fails.
Type
Promise

openRemoteFile(docURL, readOnlyopt) → {Promise}

Opens a document, whose storage is managed by XXE server, whose content is found in docURL.
Parameters:
Name Type Attributes Default Description
docURL string the URL (absolute location) of the document to be opened. May not be null.
readOnly boolean <optional>
 false if true, the document is opened in read-only mode.
Source:
See:
Returns:
A Promise containing a boolean or an Error. The value of the promise is true if the document has successfully been opened; false if currently opened document first needs to be saved. An error is reported if, for any reason, the operation fails.
Type
Promise

openResource(options) → {Promise}

Prompt user to choose an existing document resource.
Parameters:
Name Type Description
options Object options for use by the resource chooser dialog box.

Dialog box options are:

title
The title of the dialog box. Defaults to "Open" or "Save".
extensions
An array of [description, MIME_type, extension, ... ,extension] arrays. File extensions must not start with '.'. Example: 
[ 
   ["PNG images", "image/png", "png"], 
   ["JPEG images", "image/jpeg", "jpg", "jpeg"] 
]

Default: none (accept all files).

templateURI
Suggested choice (absolute URI). Default: null.
option
An array of 3 items: [option_name, initial_boolean_value, option_label] specifying a check box to be added as an accessory to the dialog box. Default: none (no dialog box "accessory").
Source:
See:
Returns:
A Promise containing a ready-to-use Resource or null if user canceled this operation or an Error.
Type
Promise

putResource(data, uri) → {Promise}

Same as XMLEditor#storeResource except that this method automatically caches the newly stored resource.
Parameters:
Name Type Description
data Blob the data to be stored.
uri string absolute URI of the resource to be created (or overwritten if it already exists).
Source:
See:
Returns:
A Promise containing a Resource or an Error.
Type
Promise

recoverDocument(documentUID) → {Promise}

Opens a document which was previously opened in this XMLEditor but for which the connection to the server was lost before the document was cleanly closed (using XMLEditor#closeDocument).

The connection to the server is lost quite easily; for example when the user clicks the Reload button of the web browser. That's why by default, an XMLEditor has an auto-recover feature. So in principle, there is no need to invoke this method.

Parameters:
Name Type Description
documentUID string the unique ID of the document to be recovered. This ID is found in DocumentOpenedEvent and all events derived from it.
Source:
See:
Returns:
A Promise containing a boolean or an Error. The value of the promise is true if the document has successfully been recovered; false if currently opened document first needs to be saved and also when specified document cannot be recovered anymore because it has been automatically closed by the server. An error is reported if, for any reason, the operation fails.
Type
Promise

removeEventListener(type, listener)

Unregister specified event listener with this XMLEditor. Specified listener must have been registered with this XMLEditor by invoking XMLEditor#addEventListener.
Parameters:
Name Type Description
type string the type of an XMLEditorEvent, for example: "documentOpened", "documentClosed", etc.
listener function the event handler, a function accepting an XMLEditorEvent as its argument.

This function is called before the request is actually sent to the server.
Source:

removeRequestListener(listener)

Unregister specified request listener with this XMLEditor.

Not for general use; only to debug an XMLEditor.

Parameters:
Name Type Description
listener function the listener to be unregistered.
Source:

saveDocument() → {Promise}

Saves the document being edited.
Document having a storage managed by client code
Merely changes the save state of the document. That is, this method does not actually save the document to disk.
Document having a storage managed by XXE server
The document is saved to disk by XXE server. Save file is overwritten if it already exists.
Source:
See:
Returns:
A Promise containing a boolean or an Error. The value of the promise is true if the document has successfully been saved; false if there is no document currently opened in this editor or if the document doesn't need to be saved or if the modified document needs to be "saved as". An error is reported if, for any reason, the operation fails.
Type
Promise

saveDocumentAs(location) → {Promise}

Saves the document being edited, changing its identifier or location.

Notes:

  • "Saving as" a read-only document will make it read-write.
  • "Saving as" a document cannot change the origin of its storage (that is, change from storage managed by the client to storage managed by the server, or the other way round).
Parameters:
Name Type Description
location string the new location of the document. May not be null.
Document having a storage managed by client code
location is an URI (an identifier). Merely changes the save state of the document. That is, this method does not actually save the document to disk.
Document having a storage managed by XXE server
location is an URL (absolute location). The document is saved to disk by XXE server. Save file is overwritten if it already exists.
Source:
See:
Returns:
A Promise containing a boolean or an Error. The value of the promise is true if the document has been successfully saved; false if no document is currently opened in the editor. An error is reported if, for any reason, the operation fails.
Type
Promise

showSearchReplace()

Show or hide the text search/replace pane.
Source:

showStatus(text, autoEraseopt)

Display specified message in the status area of this XMLEditor.
Parameters:
Name Type Attributes Default Description
text string the message to be displayed. May be null or the empty string.
autoErase boolean <optional>
 true autoErase - if true, automatically erase the message after 10s.
Source:

storeResource(data, uri) → {Promise}

Create (or overwrite if it already exists) resource having specified URI.

Any parent directory of specified URI which does not already exist is automatically created.

Parameters:
Name Type Description
data Blob the data to be stored.
uri string absolute URI of the resource to be created (or overwritten if it already exists).
Source:
Returns:
A Promise containing a Resource or an Error.

IMPORTANT: the resource data is not actually saved to disk if there is no way save a resource knowing just its URI. This is for example the case of local files.

Type
Promise

validateDocument() → {Promise}

Check the validity of the document being edited.
Source:
See:
Returns:
A Promise containing null, a diagnostics object or an Error. The value of the promise is null if there is no document currently opened in this editor and also when opened document does not conform to any schema and thus cannot be checked for validity (when this is the case, DocumentValidatedEvent is not fired by the server). An error is reported if, for any reason, the operation fails.

A diagnostics object has the following keys:

severity
The overall severity of the diagnostics.
diagnostics
A possibly empty array of diagnostic objects. See description in DocumentValidatedEvent.
Type
Promise