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.
• JWT and Media are set as dependencies for the module and are necessary.

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

• Create a JWT HMAC key, with the HS256 algorithm.
• Set it to be provided by the configuration.

You can create a secret using the following shell command:

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 two 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): Preview media file in Collabora Users with this permission are allowed to preview documents attached to a media entity of the given type, using the Collabora Online editor in preview/readonly mode.

In the current version, preview and edit access with the Collabora Online editor are checked independently of the publishing status of the respective media, and independently of the regular view or edit access on that media entity.

For a consistent experience, it is recommended that a role with the edit permission should also be granted the preview permission, and that a user with any of the Collabora media permissions should also be granted permissions to view the respective media entity in Drupal.

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.

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.

License

This module is published under the MPL-2.0 license.