Justinaquino: "Add Pandapower and ONLYOFFICE Nextcloud analysis pages"

2026-03-09T16:22:23Z

"Add Pandapower and ONLYOFFICE Nextcloud analysis pages"

New page

= ONLYOFFICE Nextcloud Integration — Repository Analysis =

{{Quote|A comprehensive guide for newcomers to understand the codebase, its architecture, and how to contribute.}}

----

== 1. What Is This Project? ==

This is a '''Nextcloud app''' that integrates [https://www.onlyoffice.com/ ONLYOFFICE Docs] (a self-hosted Document Server) with Nextcloud. It enables:

* '''In-browser editing''' of documents, spreadsheets, and presentations (DOCX, XLSX, PPTX, PDF, and 50+ formats)
* '''Real-time co-editing''' — multiple users editing simultaneously
* '''Version history''' — track and restore document revisions
* '''Template management''' — create documents from templates
* '''Federated editing''' — co-edit across linked Nextcloud instances
* '''Format conversion''' — convert between office formats server-side

'''Key facts:'''
* '''App ID:''' <code>onlyoffice</code>
* '''Version:''' 10.0.0 (requires Nextcloud 33)
* '''License:''' AGPL-3.0
* '''Author:''' Ascensio System SIA
* '''Language split:''' ~60% PHP backend, ~40% JavaScript frontend

----

== 2. Top-Level Directory Structure ==

<syntaxhighlight lang="text">
onlyoffice-nextcloud/
├── appinfo/ # Nextcloud app metadata & routing
│ ├── info.xml # App ID, version, dependencies, settings registration
│ └── routes.php # All HTTP routes (web + OCS API)
│
├── lib/ # PHP backend (~46 files)
│ ├── AppInfo/ # App bootstrap
│ ├── Controller/ # 8 controllers (editor, callback, settings, API)
│ ├── Listeners/ # 8 event listeners (file actions, CSP, sharing)
│ ├── Cron/ # Background jobs
│ ├── Command/ # CLI commands
│ ├── Migration/ # Database migrations
│ ├── AppConfig.php # Central config (1,200+ lines)
│ ├── Crypt.php # JWT token handling
│ ├── DocumentService.php # Document Server connector
│ ├── FileUtility.php # File operations
│ ├── KeyManager.php # Document key storage
│ └── ... # Template, preview, notification managers
│
├── src/ # JavaScript frontend (~31 files)
│ ├── main.js # Files app integration (context menus, file actions)
│ ├── editor.js # Main editor interface
│ ├── settings.js # Admin settings page
│ ├── share.js # Sharing panel
│ ├── viewer.js # Read-only viewer
│ ├── template.js # Template picker
│ ├── desktop.js # Desktop client integration
│ ├── directeditor.js # Direct editing (token-based)
│ └── listener.js # Editor event listener
│
├── templates/ # PHP templates (8 files)
│ ├── editor.php # Editor page (loads iframe)
│ ├── settings.php # Admin settings form
│ └── ... # Share, loader, picker templates
│
├── css/ # Stylesheets (7 files)
├── img/ # Icons — app logo, format icons (DOCX, XLSX, PPTX, PDF)
├── l10n/ # Localization — 20+ languages (JSON + JS)
├── assets/ # Static assets
├── screenshots/ # Documentation screenshots
├── licenses/ # License info
├── vendor/ # Composer dependencies (firebase/php-jwt)
│
├── .github/ # CI/CD workflows (lint, build, release)
├── composer.json # PHP dependencies
├── package.json # JS dependencies & build scripts
├── webpack.js # Webpack entry points config
└── Makefile # Build automation
</syntaxhighlight>

----

== 3. How It Works — The Big Picture ==

<syntaxhighlight lang="text">
┌─────────────────────────────────────────────────────────┐
│ User's Browser │
│ ┌─────────────────────────────────────────────────┐ │
│ │ Nextcloud Files UI │ │
│ │ (main.js adds "Edit in ONLYOFFICE" actions) │ │
│ └──────────────────┬──────────────────────────────┘ │
│ │ click │
│ ┌──────────────────▼──────────────────────────────┐ │
│ │ Editor Page (editor.php + editor.js) │ │
│ │ ┌──────────────────────────────────────┐ │ │
│ │ │ ONLYOFFICE Document Editor iframe │ │ │
│ │ │ (loaded from Document Server) │ │ │
│ │ └──────────────────┬───────────────────┘ │ │
│ └─────────────────────┼───────────────────────────┘ │
└────────────────────────┼────────────────────────────────┘
│
┌──────────────┼──────────────┐
│ │ │
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌──────────────┐
│ Nextcloud │ │ Document │ │ Nextcloud │
│ Backend │ │ Server │ │ Backend │
│ (PHP app) │ │ (ONLYOFFICE)│ │ Callback │
│ │ │ │ │ │
│ GET config │ │ Serves │ │ POST /track │
│ GET file URL │ │ editor UI │ │ (save changes│
│ JWT token │ │ Converts │ │ on close) │
│ generation │ │ files │ │ │
└─────────────┘ └─────────────┘ └──────────────┘
</syntaxhighlight>

=== Document Editing Flow: ===

# '''User clicks "Edit in ONLYOFFICE"''' — <code>main.js</code> triggers navigation
# '''EditorController''' generates a JWT-signed config with document URL, permissions, user info
# '''Editor page loads''' — iframe points to ONLYOFFICE Document Server with the config
# '''Document Server fetches the file''' from Nextcloud via the download callback URL
# '''User edits''' — changes are tracked in Document Server's memory
# '''On close/save''' — Document Server POSTs the changed file back to <code>CallbackController.track()</code>
# '''Nextcloud stores''' the updated file and creates a version entry

----

== 4. Backend Architecture (PHP) ==

=== 4.1 Controllers (the API layer) ===

{| class="wikitable"
|-
! Controller !! Routes !! Purpose
|-
| '''EditorController''' || <code>/onlyoffice/{fileId}</code>, <code>/ajax/*</code> || Main editor — open files, save, convert, history, mentions, download
|-
| '''CallbackController''' || <code>/onlyoffice/track</code>, <code>/onlyoffice/download</code> || Document Server callbacks — receive changes, serve files
|-
| '''EditorApiController''' || <code>/api/v1/config/{fileId}</code> || OCS API — generate editor configuration with JWT
|-
| '''SettingsController''' || <code>/ajax/settings/*</code> || Admin settings — server address, security, common settings
|-
| '''TemplateController''' || <code>/ajax/template</code>, <code>/preview</code> || Template CRUD and preview
|-
| '''SharingApiController''' || <code>/api/v1/shares/{fileId}</code> || OCS API — file share management
|-
| '''FederationController''' || <code>/api/v1/key</code>, <code>/api/v1/keylock</code>, <code>/api/v1/healthcheck</code> || Federation key exchange and health
|-
| '''JobListController''' || background job management || Background job scheduling
|}

=== 4.2 Core Services ===

{| class="wikitable"
|-
! Class !! Purpose
|-
| '''AppConfig.php''' || Central config store (~1,200 lines). Document Server URL, JWT settings, supported formats, watermarks, security, feature flags. This is the largest and most important config file.
|-
| '''DocumentService.php''' || Connector to Document Server API. Generates revision IDs, calls conversion endpoints, manages document info requests.
|-
| '''Crypt.php''' || JWT token generation/verification using HS256 via <code>firebase/php-jwt</code>. Every request between Nextcloud and Document Server is JWT-signed.
|-
| '''KeyManager.php''' || Manages document keys in DB table <code>onlyoffice_filekey</code>. Tracks locks, force-save status.
|-
| '''FileUtility.php''' || File system operations — get file info, MIME types, share management, permissions.
|-
| '''FileVersions.php''' || Version history — stores edit records, tracks who edited when.
|-
| '''TemplateManager.php''' || Template storage in <code>appdata_{instanceid}/onlyoffice/template</code>. CRUD for document templates.
|-
| '''ExtraPermissions.php''' || Extended permission system — integrates with Nextcloud Talk for comments/chat during co-editing.
|-
| '''RemoteInstance.php''' || Federated instance management — DB table <code>onlyoffice_instance</code>, health checks with 12-hour TTL cache.
|-
| '''Preview.php''' || Generates file preview images for Nextcloud's preview system.
|}

=== 4.3 Event Listeners ===

{| class="wikitable"
|-
! Listener !! Event !! Purpose
|-
| '''FilesListener''' || <code>LoadAdditionalScriptsEvent</code> || Injects <code>main.js</code> into the Files app, adds "New Document" menu items
|-
| '''DirectEditorListener''' || <code>RegisterDirectEditorEvent</code> || Registers ONLYOFFICE as a direct editor for supported formats
|-
| '''ViewerListener''' || <code>LoadViewer</code> || Loads editor in view-only mode
|-
| '''FileSharingListener''' || <code>BeforeTemplateRenderedEvent</code> || Adds sharing panel to editor
|-
| '''CreateFromTemplateListener''' || <code>FileCreatedFromTemplateEvent</code> || Handles new-file-from-template flow
|-
| '''ContentSecurityPolicyListener''' || <code>AddContentSecurityPolicyEvent</code> || Adds Document Server domain to CSP whitelist
|-
| '''WidgetListener''' || <code>HttpBeforeTemplateRenderedEvent</code> || Dashboard widget
|-
| '''DocumentUnsavedListener''' || custom event || Fires notifications for unsaved documents
|}

=== 4.4 Database Tables ===

{| class="wikitable"
|-
! Table !! Columns !! Purpose
|-
| <code>onlyoffice_filekey</code> || <code>file_id</code> (PK), <code>key</code>, <code>lock</code>, <code>fs</code> || Document identifiers, edit locks, force-save flags
|-
| <code>onlyoffice_instance</code> || <code>remote</code>, <code>expire</code>, <code>status</code> || Federated instance health tracking
|-
| <code>onlyoffice_extraperm</code> || share-based || Extended co-editing permissions
|}

----

== 5. Frontend Architecture (JavaScript) ==

=== 5.1 Webpack Entry Points ===

{| class="wikitable"
|-
! Entry !! File !! Purpose
|-
| <code>main</code> || <code>src/main.js</code> || '''Core integration''' — registers file actions ("Edit in ONLYOFFICE"), new-document menu items (DOCX/XLSX/PPTX/PDF), context menus in the Files app
|-
| <code>editor</code> || <code>src/editor.js</code> || '''Editor page''' — fetches config via AJAX, initializes ONLYOFFICE Document API iframe, manages editor lifecycle
|-
| <code>settings</code> || <code>src/settings.js</code> || '''Admin panel''' — Document Server URL, JWT secret, format toggles, watermarks, security
|-
| <code>share</code> || <code>src/share.js</code> || '''Sharing sidebar''' — share links, permissions for co-editing
|-
| <code>viewer</code> || <code>src/viewer.js</code> || '''Read-only viewer''' — opens documents in view mode
|-
| <code>template</code> || <code>src/template.js</code> || '''Template picker''' — select/create from templates
|-
| <code>desktop</code> || <code>src/desktop.js</code> || '''Desktop client''' — integration with Nextcloud desktop app
|-
| <code>directeditor</code> || <code>src/directeditor.js</code> || '''Direct editing''' — token-based editing without standard Files UI
|-
| <code>listener</code> || <code>src/listener.js</code> || '''Event bridge''' — handles editor close, save-as, image insertion, mail merge
|}

=== 5.2 Key Frontend Dependencies ===

{| class="wikitable"
|-
! Package !! Purpose
|-
| <code>@nextcloud/files</code> || File actions API, new-file menu registration
|-
| <code>@nextcloud/auth</code> || Authentication tokens
|-
| <code>@nextcloud/initial-state</code> || Server → client state transfer (settings, config)
|-
| <code>@nextcloud/l10n</code> || Localization/translation
|-
| <code>@nextcloud/router</code> || URL generation for Nextcloud routes
|-
| <code>@nextcloud/sharing</code> || Sharing UI integration
|-
| <code>@nextcloud/event-bus</code> || Cross-component events
|-
| <code>vue@^2.7</code> || UI framework
|}

----

== 6. Supported File Types ==

=== Editable ===

{| class="wikitable"
|-
! Category !! Formats
|-
| Documents || DOCX, ODT, RTF, TXT, DOCXF (forms)
|-
| Spreadsheets || XLSX, ODS, CSV
|-
| Presentations || PPTX, ODP
|-
| PDFs || PDF (with form editing)
|}

=== View-Only / Convertible ===

{| class="wikitable"
|-
! Category !! Formats
|-
| Documents || EPUB, FB2, HTML, HWP, HWPX, Pages, MD
|-
| Spreadsheets || Numbers
|-
| Presentations || Keynote
|-
| Drawings || VSDX, VSSX, VSTX, ODG
|-
| Images || TIFF, SVG
|}

----

== 7. Security Architecture ==

=== JWT Authentication ===

* '''Algorithm:''' HS256 (HMAC SHA-256) via <code>firebase/php-jwt</code>
* Every request between Nextcloud ↔ Document Server carries a JWT token
* Configurable secret, expiry, and leeway (clock skew tolerance)

=== Content Security Policy ===

* <code>ContentSecurityPolicyListener</code> dynamically adds the Document Server domain to Nextcloud's CSP
* Required because the editor runs in an iframe from a different origin

=== File Locking ===

* Database-tracked locks prevent conflicting edits
* Automatic cleanup via <code>EditorsCheck</code> background job

=== Watermarks ===

* Admin-configurable text, transparency, angle, color
* Can be applied per user/group/share type

----

== 8. Configuration Options (Admin Settings) ==

{| class="wikitable"
|-
! Setting !! Description
|-
| Document Server address || External URL for the ONLYOFFICE Docs server
|-
| Internal Server address || URL used for server-to-server communication (if different)
|-
| Storage address || URL the Document Server uses to reach Nextcloud
|-
| JWT Secret || Shared secret for token signing
|-
| JWT Expiry || Token lifetime
|-
| Editable formats || Which formats open in edit mode (vs. view)
|-
| Supported conversions || Which format conversions are available
|-
| Watermark settings || Text, transparency, angle, color
|-
| Same-tab editing || Open editor in same tab or new tab
|-
| Advanced sidebar || Show document info sidebar
|-
| Live view for shares || Allow live viewing of shared documents
|-
| Demo server || Use ONLYOFFICE demo server (for testing)
|}

----

== 9. Build System ==

=== Build Commands ===

<syntaxhighlight lang="bash">
npm install # Install JS dependencies
npm run build # Production webpack build
npm run dev # Development build with watch
composer install # Install PHP dependencies (firebase/php-jwt)
</syntaxhighlight>

=== CI/CD Workflows (<code>.github/workflows/</code>) ===

{| class="wikitable"
|-
! Workflow !! Purpose
|-
| <code>lint-eslint.yml</code> || JavaScript linting
|-
| <code>lint-phpcs.yml</code> || PHP CodeSniffer
|-
| <code>lint-php.yml</code> || PHP syntax validation
|-
| <code>artifact.yml</code> || Build release artifacts
|-
| <code>release.yml</code> || Automated releases
|-
| <code>create-tag.yml</code> || Git tag creation
|}

----

== 10. Common Contribution Areas ==

=== Easy / Good First Issues ===

{| class="wikitable"
|-
! Area !! What To Do !! Files
|-
| '''Translations''' || Add/improve translations for your language || <code>l10n/*.json</code>, <code>l10n/*.js</code>
|-
| '''CSS fixes''' || Fix styling issues, dark mode support || <code>css/*.css</code>
|-
| '''Format support''' || Add new file format icons or MIME mappings || <code>img/</code>, <code>lib/AppConfig.php</code>
|-
| '''Documentation''' || Improve README, add setup guides || <code>README.md</code>
|}

=== Medium Complexity ===

{| class="wikitable"
|-
! Area !! What To Do !! Files
|-
| '''New file actions''' || Add context menu items in Files app || <code>src/main.js</code>
|-
| '''Settings UI''' || Add new admin settings options || <code>src/settings.js</code>, <code>templates/settings.php</code>, <code>lib/Controller/SettingsController.php</code>
|-
| '''Template improvements''' || Better template picker, categories || <code>src/template.js</code>, <code>lib/TemplateManager.php</code>
|-
| '''Sharing enhancements''' || Improve co-editing permission UI || <code>src/share.js</code>, <code>lib/ExtraPermissions.php</code>
|-
| '''Preview generation''' || Improve thumbnail quality/formats || <code>lib/Preview.php</code>
|}

=== Advanced ===

{| class="wikitable"
|-
! Area !! What To Do !! Files
|-
| '''Editor configuration''' || Add new Document Server config options to the editor setup || <code>lib/Controller/EditorController.php</code>, <code>lib/Controller/EditorApiController.php</code>
|-
| '''Callback handling''' || Handle new Document Server callback events || <code>lib/Controller/CallbackController.php</code>
|-
| '''Federation''' || Improve cross-instance editing || <code>lib/RemoteInstance.php</code>, <code>lib/Controller/FederationController.php</code>
|-
| '''Performance''' || Optimize file locking, key management || <code>lib/KeyManager.php</code>, <code>lib/Cron/EditorsCheck.php</code>
|-
| '''Security''' || JWT improvements, CSP hardening || <code>lib/Crypt.php</code>, <code>lib/Listeners/ContentSecurityPolicyListener.php</code>
|-
| '''Version history''' || Improve diff/restore functionality || <code>lib/FileVersions.php</code>, editor history endpoints
|-
| '''Controller features''' || Add new API endpoints || <code>lib/Controller/</code>, <code>appinfo/routes.php</code>
|}

=== Architecture Changes ===

{| class="wikitable"
|-
! Area !! What To Do !! Files
|-
| '''Vue 3 migration''' || Upgrade from Vue 2.7 to Vue 3 || <code>src/</code>, <code>package.json</code>, <code>webpack.js</code>
|-
| '''TypeScript''' || Add type safety to frontend || <code>src/*.js</code> → <code>src/*.ts</code>
|-
| '''Database schema''' || New tables for features || <code>lib/Migration/</code>
|-
| '''New Nextcloud APIs''' || Adopt newer NC framework features || <code>lib/Listeners/</code>, <code>lib/AppInfo/Application.php</code>
|}

----

== 11. Development Setup ==

=== Prerequisites ===

* Nextcloud 33 instance (dev environment)
* ONLYOFFICE Document Server (or use demo mode)
* PHP 8.1+, Node.js 18+, npm

=== Quick Start ===

<syntaxhighlight lang="bash">
# Clone into Nextcloud apps directory
cd /path/to/nextcloud/apps
git clone https://github.com/xunema/onlyoffice-nextcloud.git onlyoffice

# Install dependencies
cd onlyoffice
composer install
npm install

# Build frontend
npm run build

# Enable app
cd /path/to/nextcloud
php occ app:enable onlyoffice

# Configure Document Server URL in Admin → ONLYOFFICE
</syntaxhighlight>

=== Development Workflow ===

<syntaxhighlight lang="bash">
npm run dev # Watch mode — rebuilds on file changes
# Edit PHP files — changes are immediate (no build needed)
# Edit JS/Vue files — webpack rebuilds automatically
</syntaxhighlight>

----

== 12. Key Files to Read First ==

If you're new to this codebase, read these in order:

# '''<code>appinfo/info.xml</code>''' — What this app is, what it requires
# '''<code>appinfo/routes.php</code>''' — All URL routes (the API surface)
# '''<code>lib/AppConfig.php</code>''' — Configuration options (largest file, central to everything)
# '''<code>lib/Controller/EditorController.php</code>''' — Main editor logic (~1,500 lines)
# '''<code>lib/Controller/CallbackController.php</code>''' — How Document Server communicates back (~1,000 lines)
# '''<code>src/main.js</code>''' — How the app integrates into Nextcloud Files
# '''<code>src/editor.js</code>''' — How the editor page works
# '''<code>templates/editor.php</code>''' — The editor HTML template
# '''<code>lib/Crypt.php</code>''' — JWT security
# '''<code>webpack.js</code>''' — Frontend build configuration

[[Category:Open Source]]
[[Category:Software Analysis]]
[[Category:ONLYOFFICE]]

ONLYOFFICE Nextcloud Analysis - Revision history

Justinaquino: "Add Pandapower and ONLYOFFICE Nextcloud analysis pages"