Configuration

Configuration Object Structure

The configuration object passed to OnlyOfficeEditorModule.init() follows the OnlyOffice Document Server API specification with additional module-specific handling.

Basic Structure

var config = {
    document: {
        fileType: string,
        key: string,
        title: string,
        url: string,
        permissions: object    // optional
    },
    documentType: string,
    editorConfig: {
        mode: string,
        lang: string,
        customization: object,
        user: object,
        // ... other options
    },
    events: object,  // Managed by the module
    height: string,
    width: string,
    type: string
};

Document Configuration

Defines the document to be opened in the editor.

document.fileType

string

required

The file extension/type: 'docx', 'xlsx', 'pptx', 'pdf', etc.

fileType: 'docx'

document.key

string

required

Unique document identifier. Must change when document content changes. Used for caching and collaboration.

key: 'doc-123-v2'

document.title

string

required

Document title displayed in the editor.

title: 'Annual Report 2024.docx'

document.url

string

required

Absolute URL to the document file. Must be accessible by OnlyOffice Document Server.

url: 'https://example.com/documents/report.docx'

document.permissions

object

Document permissions object controlling what users can do.

permissions: {
    edit: true,
    download: true,
    print: true,
    review: false,
    comment: true
}

The document.url must be accessible from the OnlyOffice Document Server, not from the client browser. Ensure proper network configuration and CORS policies.

Example: Complete Document Config

document: {
    fileType: 'xlsx',
    key: 'spreadsheet-' + documentId + '-v' + version,
    title: 'Q4 Sales Data.xlsx',
    url: 'https://cdn.example.com/files/sales-q4.xlsx',
    permissions: {
        edit: userCanEdit,
        download: userCanDownload,
        print: true,
        review: userIsReviewer,
        comment: true,
        fillForms: true,
        modifyFilter: userCanEdit,
        modifyContentControl: userCanEdit
    },
    info: {
        owner: 'John Doe',
        uploaded: '2024-01-15',
        folder: 'Sales Reports'
    }
}

Document Type

Specifies the type of editor to use.

documentType

string

required

The editor type: 'word', 'cell', or 'slide'.

'word': Document editor (doc, docx, txt, etc.)
'cell': Spreadsheet editor (xls, xlsx, csv, etc.)
'slide': Presentation editor (ppt, pptx, etc.)

documentType: 'word'

Editor Configuration

Controls editor behavior, appearance, and user settings.

Mode

editorConfig.mode

string

Editor mode: 'edit' or 'view'. Defaults to 'edit'.

editorConfig: {
    mode: 'edit'  // or 'view'
}

Language

editorConfig.lang

string

Interface language code (e.g., 'en', 'es', 'fr').

editorConfig: {
    lang: 'en'
}

User Information

editorConfig.user

object

Information about the current user for collaboration features.

editorConfig: {
    user: {
        id: 'user-123',
        name: 'Jane Smith',
        group: 'Sales Team'
    }
}

Callback URL

editorConfig.callbackUrl

string

Server endpoint for saving document changes. OnlyOffice Document Server will POST updates to this URL.

editorConfig: {
    callbackUrl: 'https://example.com/api/documents/callback'
}

Customization Options

The editorConfig.customization object controls the editor’s appearance and behavior. OnlyOfficeEditorModule applies default values automatically.

Default Customization Values

The module sets these defaults if not specified:

editorConfig: {
    customization: {
        uiTheme: 'theme-classic-light',
        compactToolbar: false,
        toolbarNoTabs: false,
        hideRightMenu: true,
        hideRulers: true,
        review: {
            showReviewChanges: false
        }
    }
}

UI Theme

editorConfig.customization.uiTheme

string

default:"theme-classic-light"

Color theme for the editor interface.Options:

'theme-classic-light': Light theme (default)
'theme-light': Modern light theme
'theme-dark': Dark theme

customization: {
    uiTheme: 'theme-dark'
}

Use compact toolbar layout.

customization: {
    compactToolbar: true
}

Hide tabs in the toolbar.

customization: {
    toolbarNoTabs: true
}

Hide the file name in the toolbar.

customization: {
    toolbarHideFileName: true
}

UI Elements Visibility

Hide the right sidebar menu. Set to false to show object properties, comments, etc.

customization: {
    hideRightMenu: false
}

editorConfig.customization.hideRulers

boolean

default:true

Hide rulers in document editor.

customization: {
    hideRulers: false  // Show rulers
}

Review/Track Changes

editorConfig.customization.review.showReviewChanges

boolean

default:false

Show tracked changes panel on load.

customization: {
    review: {
        showReviewChanges: true
    }
}

The module automatically migrates the deprecated showReviewChanges property to review.showReviewChanges.

Other Customization Options

OnlyOfficeEditorModule doesn’t modify these, but they’re supported:

editorConfig.customization.chat

boolean

Enable/disable chat feature.

editorConfig.customization.comments

boolean

Enable/disable comments.

editorConfig.customization.zoom

number

Initial zoom level (percentage).

editorConfig.customization.autosave

boolean

Enable/disable autosave.

editorConfig.customization.forcesave

boolean

Enable force save mode.

Complete Customization Example

var config = {
    document: {
        fileType: 'docx',
        key: 'doc-123',
        title: 'Contract.docx',
        url: 'https://example.com/contract.docx'
    },
    documentType: 'word',
    editorConfig: {
        mode: 'edit',
        lang: 'en',
        user: {
            id: 'user-456',
            name: 'John Doe'
        },
        customization: {
            uiTheme: 'theme-dark',
            compactToolbar: true,
            toolbarNoTabs: false,
            hideRightMenu: false,
            hideRulers: false,
            zoom: 120,
            autosave: true,
            chat: false,
            comments: true,
            review: {
                showReviewChanges: true
            }
        }
    }
};

OnlyOfficeEditorModule.init('editorContainer', config);

Events

The config.events object is managed internally by OnlyOfficeEditorModule. Instead of configuring events directly, use the options parameter.

Module Event Callbacks

Pass callbacks through the options parameter of init():

options.onReady

function

Called when the editor application is initialized and ready to use.

options: {
    onReady: function() {
        console.log('Editor is ready');
        // Enable save button, etc.
    }
}

Maps to: OnlyOffice onAppReady event

options.onDocumentReady

function

Called when the document has been fully loaded in the editor.

options: {
    onDocumentReady: function() {
        console.log('Document loaded');
        // Document is now editable
    }
}

Maps to: OnlyOffice onDocumentReady event

options.onError

function

Called when an error occurs in the editor.

options: {
    onError: function(event) {
        console.error('Editor error:', event);
        alert('An error occurred: ' + event.data);
    }
}

Maps to: OnlyOffice onError eventParameters:

event: Error event object with details

Internal Events

These events are handled internally by the module:

onDownloadAs: Triggered when document download completes (used by getEditedDocumentUrl())
onAppReady: Hides loading indicator and calls options.onReady

Event Flow Example

var config = {
    document: {
        fileType: 'docx',
        key: 'doc-789',
        title: 'Document.docx',
        url: 'https://example.com/doc.docx'
    },
    documentType: 'word'
};

var options = {
    onReady: function() {
        console.log('1. Editor initialized');
        document.getElementById('saveButton').disabled = false;
    },
    onDocumentReady: function() {
        console.log('2. Document loaded and ready for editing');
        document.getElementById('loadingMessage').style.display = 'none';
    },
    onError: function(evt) {
        console.error('3. Error occurred:', evt);
        document.getElementById('errorMessage').textContent = 
            'Failed to load editor: ' + (evt.data || 'Unknown error');
        document.getElementById('errorMessage').style.display = 'block';
    }
};

var editor = OnlyOfficeEditorModule.init('editorContainer', config, options);

Do NOT set config.events directly. The module overwrites this property to manage internal event handling. Use the options parameter instead.

Dimensions

Control the editor size:

height

string

Editor height with CSS unit.

height: '600px'  // or '100%', '80vh', etc.

width

string

Editor width with CSS unit.

width: '100%'  // or '800px', etc.

Editor Type

type

string

Platform type: 'desktop' or 'mobile'.

type: 'desktop'

Proxy Configuration

For getEditedDocumentBlob() to work with cross-origin restrictions:

// Set global proxy URL before calling getEditedDocumentBlob()
window.__onlyOfficeProxyUrl = '/api/document-proxy?url=';

// The module will now fetch documents through your proxy
OnlyOfficeEditorModule.getEditedDocumentBlob('editorContainer')
    .then(function(blob) {
        // Process blob
    });

Proxy Implementation Example (ASP.NET)

[Route("api/document-proxy")]
public IActionResult ProxyDocument(string url)
{
    if (string.IsNullOrEmpty(url))
        return BadRequest();
    
    using (var client = new HttpClient())
    {
        var response = client.GetAsync(url).Result;
        var content = response.Content.ReadAsByteArrayAsync().Result;
        return File(content, "application/octet-stream");
    }
}

Complete Configuration Example

// Optional: Set proxy for cross-origin document downloads
window.__onlyOfficeProxyUrl = '/api/proxy?url=';

var config = {
    document: {
        fileType: 'docx',
        key: 'unique-key-' + documentId + '-v' + version,
        title: 'Project Proposal.docx',
        url: 'https://storage.example.com/documents/proposal.docx',
        permissions: {
            edit: true,
            download: true,
            print: true,
            review: true,
            comment: true
        }
    },
    documentType: 'word',
    editorConfig: {
        mode: 'edit',
        lang: 'en',
        callbackUrl: 'https://example.com/api/documents/save-callback',
        user: {
            id: currentUserId,
            name: currentUserName,
            group: currentUserGroup
        },
        customization: {
            uiTheme: 'theme-classic-light',
            compactToolbar: false,
            hideRightMenu: false,
            hideRulers: false,
            autosave: true,
            forcesave: false,
            comments: true,
            chat: false,
            zoom: 100,
            review: {
                showReviewChanges: true
            }
        }
    },
    height: '100%',
    width: '100%',
    type: 'desktop'
};

var options = {
    onReady: function() {
        console.log('Editor ready');
        hideLoadingSpinner();
        enableSaveButton();
    },
    onDocumentReady: function() {
        console.log('Document loaded');
        trackDocumentOpen(documentId);
    },
    onError: function(error) {
        console.error('Editor error:', error);
        showErrorMessage('Failed to load document');
        logError(error);
    }
};

var editor = OnlyOfficeEditorModule.init('editorContainer', config, options);

if (!editor) {
    console.error('Failed to initialize editor');
    showErrorMessage('Could not start document editor');
}

Best Practices

Document Keys

Always generate unique keys for each document version. Include version numbers or timestamps.

Error Handling

Always provide onError callback to handle initialization and runtime errors gracefully.

Permissions

Set appropriate permissions based on user roles to control editing, downloading, and printing.

Customization

Test different UI themes and toolbar configurations to match your application’s design.

User Control

JavaScript API

Handlers

Configuration Object Structure

Basic Structure

Document Configuration

Example: Complete Document Config

Document Type

Editor Configuration

Mode

Language

User Information

Callback URL

Customization Options

Default Customization Values

UI Theme

UI Elements Visibility

Review/Track Changes

Other Customization Options

Complete Customization Example

Events

Module Event Callbacks

Internal Events

Event Flow Example

Dimensions

Editor Type

Proxy Configuration

Proxy Implementation Example (ASP.NET)

Complete Configuration Example

Best Practices

Document Keys

Error Handling

Permissions

Customization

See Also

Build docs developers (and LLMs) love

User Control

JavaScript API

Handlers

Documentation Index

​Configuration Object Structure

​Basic Structure

​Document Configuration

​Example: Complete Document Config

​Document Type

​Editor Configuration

​Mode

​Language

​User Information

​Callback URL

​Customization Options

​Default Customization Values

​UI Theme

​Toolbar Options

​UI Elements Visibility

​Review/Track Changes

​Other Customization Options

​Complete Customization Example

​Events

​Module Event Callbacks

​Internal Events

​Event Flow Example

​Dimensions

​Editor Type

​Proxy Configuration

​Proxy Implementation Example (ASP.NET)

​Complete Configuration Example

​Best Practices

Document Keys

Error Handling

Permissions

Customization

​See Also

Build docs developers (and LLMs) love

Configuration Object Structure

Basic Structure

Document Configuration

Example: Complete Document Config

Document Type

Editor Configuration

Mode

Language

User Information

Callback URL

Customization Options

Default Customization Values

UI Theme

Toolbar Options

UI Elements Visibility

Review/Track Changes

Other Customization Options

Complete Customization Example

Events

Module Event Callbacks

Internal Events

Event Flow Example

Dimensions

Editor Type

Proxy Configuration

Proxy Implementation Example (ASP.NET)

Complete Configuration Example

Best Practices

See Also