Collabora Online connector for Drupal

This module integrate Collabora Online to Drupal. You can use it to view and edit documents from within Drupal.

Installation

This section describes how to install the module in an existing Drupal website project. For a local demo or test installation, see below.

Requirements

• Collabora Online server installed and running.
• Drupal 10 (tested on 10.1), maybe compatible with 9.
• The Key module.
• The firebase/php-jwt composer package. See the composer.json for more details.
• The Media module from Drupal core.
• (optional) For the 'Collabora Online Group' sub-module, you also need the Group and Group Media modules.

Installation steps

See the Drupal guide to install modules.

To install on a project, user PHP composer:

composer require drupal/collabora_online

If you get an error saying but it does not match your minimum-stability, you may need to adjust the minimum-stability field in the composer.json of your project.

Then you can go into Drupal logged as an admin and go to Extend. In the list you should be able to find Collabora Online and enable it.

From there you can access the module specific configuration.

Please check the "Configuration" section below!

Development / demo installation

A local demo and testing instance can be installed using docker-compose.

Requirements

• Docker
• Docker Compose

Installation steps

First, git clone the repository into a new directory, outside of any other Drupal project.

git clone https://github.com/CollaboraOnline/collabora-drupal.git collabora_online

Then run the following steps.

docker-compose up -d

docker-compose exec web composer install
docker-compose exec web ./vendor/bin/run drupal:site-install

Optionally, generate an admin login link.

docker-compose exec web ./vendor/bin/drush uli

The last command will output a link to the local website, with login for the admin account.

Otherwise, the local website will be available at http://web.test:8080/. The administrator login is 'admin'/'admin'.

Configuration.

The demo instance is already fully configured.

See "Configuration" for optional customization.

Using the demo instance

Minimal steps to see the editor in action:

• Log in as 'admin'/'admin'.
  • An menu with administrative links should appear at the top.
• Open "Content" > "Media" > "Add media" > "Document".
• Upload a simple *.docx or *.odt file, fill the required fields, and save.
• Back in the list of "Media entities" (/admin/content/media), click the media title.
• In the media page (e.g. /media/1), click the "View" button.
  • A panel with a Collabora editor in read-only mode should appear.
• Go back to "Content" > "Media" (/admin/content/media).
• Click the dropdown icon in the "Operations" column.
• Click "Edit in Collabora Online".
  • A Collabora editor should appear in a new page.
• Edit the document, then click the "Save" icon in the top left.

Advanced usage:

• Configure roles and permissions as in "User permissions" section below.
• Create a non-admin user with sufficient roles, login,

Running the tests

To run the phpunit tests:

docker-compose exec web ./vendor/bin/phpunit

Configuration

The configuration steps below are necessary to use the module in an existing Drupal website. In the local development/demo installation, the manual configuration is optional.

Log into Drupal as an admin.

JWT key

Go to Configuration > System > Keys

Click "Add key" to create a new key with:

• Key name: Any name, e.g. "Collabora Online".
• Key type: JWT HMAC - Collabora Online.
• Key provider: Please refer to the documentation of the 'key' module for security implications.
• Key value: You can generate a key with the shell command below.

head -c 64 /dev/urandom | base64 -w 0

Collabora Online

Go to Configuration > Media > Collabora Online Settings

• Collabora Online server URL: the URL of the collabora online server. Note that you have to take into considerartion containers. If you run Drupal in one container and Collabora Online in another, you can not use localhost.
• WOPI host base URL: how the Collabora Online server can reach the Drupal server. Usually it is the public URL of this Drupal server.
• JWT Private Key ID: the id of the key created above.

Optional

• Disable TLS certificate check for COOL: If you configure a development server you might have self-signed certificate. Checking this is INSECURE but allow the drupal server to contact the collabora online server is the certificate doesn't check.
• Access Token Expiration: In second the expiration of the token to access the document. Default to 86400 seconds (24 hours).

COOL

Some configuration changes might be necessary on the Collabora Online side.

CSP for embedding must set properly to embed the Collabora Online frame.

Fields

To be able to attach document to Drupal content nodes, you need to create a field.

Login as an admin, and got to the admnistration section.

• Go to Structure > Content types
• Find the appropriate content and click Manage fields.
• Click + Create a new field (or if you already have created one you can re-use one)
• Enter a label, select Media, click Continue
• At the bottom for Media type, select Document. Click Save Settings. Type of item to reference should have been set to the default value of Media.

You also must set the viewer for this kind of media.

• Go to Structure > Media Types
• Select Manage Display for Document
• In the Field section, select in the Format column, choose Collabora Online Preview.
• Click Save.

User permissions

The module introduces permissions, which can be managed at /admin/people/permissions.

The 'Administer the Collabora instance' permission grants administrator access within the Collabora Online instance, when Collabora is used within Drupal. Most of the time this permission is not needed, if the Collabora instance is configured from outside of Drupal.

For each media type, the module introduces four permissions:

• "(media type): Edit any media file in Collabora"
  Users with this permission are allowed to edit documents attached to a media entity of the given type, using the Collabora Online editor.
• "(media type): Edit own media file in Collabora"
  Users with this permission are allowed to edit documents attached to a media entity of the given type, using the Collabora Online editor, if they are the owner/author of that media entity.
• "(media type): Preview published media file in Collabora"
  Users with this permission are allowed to preview documents attached to a published media entity of the given type, using the Collabora Online editor in preview/readonly mode.
• "(media type): Preview own unpublished media file in Collabora"
  Users with this permission are allowed to preview documents attached to an unpublished media entity of the given type, using the Collabora Online editor in preview/readonly mode.

In the current version of this module, the 'administer media' permission from Drupal core grants access to all media operations, including the use of the Collabora Online editor for preview and edit.

Developers can use entity access hooks to alter which users may edit or preview media files in Collabora. This would allow to grant access based on e.g. membership in a group.

Views

The module integrates with Views by providing links as view fields, allowing users to perform specific operations on documents directly from the view display.

These operations include actions such as "preview" and "edit," which can be easily accessed through the generated links.

Other configuration

If you need to change the accepted extensions to upload, go to Administration > Structure > Media Type, for the line Documents, click Edit, then click Manage Fields, and for the right field, Edit:

• You can change the allowed file extensions.

To increase the maximum upload size (it is indicated on that page), you need to increase the value in the PHP configuration.

Usually you can add a file max_file_size.ini (the name isn't much important except its extension should be .ini) into /etc/php/conf.d/ (the path may be different) and put the following:

post_max_size = 30M
upload_max_filesize = 30M

These set the limits to a maximum of 30M. You can change as appropriate.

Sub-modules

Collabora Online Group

Integration of Collabora Online with Group module. Check out the README of the module.

License

This module is published under the MPL-2.0 license.