diff --git a/content/configuration/realtime.md b/content/configuration/realtime.md index bf1d8bf9..f48a6136 100644 --- a/content/configuration/realtime.md +++ b/content/configuration/realtime.md @@ -45,6 +45,21 @@ Read more about different authentication methods with Directus Realtime. Read more about different authentication methods with Directus Realtime. :: +## Collaborative Editing + +::callout{icon="material-symbols:info-outline"} +Multi-instance collaboration requires a shared Redis instance for coordination. +:: + +| Variable | Description | Default Value | +| :--------------------------------------------- | :------------------------------------------------------------------------------------- | :------------ | +| `WEBSOCKETS_COLLAB_ENABLED` | Toggle collaborative editing functionality specifically (when WebSockets are enabled). | `true` | +| `WEBSOCKETS_COLLAB_INSTANCE_TIMEOUT` | Duration in milliseconds before a silent node is considered dead. | `10000` | +| `WEBSOCKETS_COLLAB_CLUSTER_CLEANUP_CRON` | Cron expression for how often to garbage-collect empty rooms. | `*/1 * * * *` | +| `WEBSOCKETS_COLLAB_LOCAL_CLEANUP_INTERVAL` | Duration in milliseconds between local cleanup sweeps. | `60000` | +| `WEBSOCKETS_COLLAB_PERMISSIONS_CACHE_CAPACITY` | LRU cache size for permission checks. | `2000` | +| `WEBSOCKETS_COLLAB_STORE_NAMESPACE` | The namespace used for Redis storage. | `collab` | + ## Logging Read more about logging with Directus Realtime in the [logging configuration](/configuration/logging). diff --git a/content/guides/02.content/9.collaborative-editing/0.index.md b/content/guides/02.content/9.collaborative-editing/0.index.md index a24e3994..41c27c39 100644 --- a/content/guides/02.content/9.collaborative-editing/0.index.md +++ b/content/guides/02.content/9.collaborative-editing/0.index.md @@ -1,13 +1,13 @@ --- title: Collaborative Editing -description: The Directus Collaborative Editing extension enables real-time data synchronization and collaborative editing across collections, allowing multiple users to edit content simultaneously without conflicts. +description: Directus Collaborative Editing enables real-time data synchronization and collaborative editing across collections, allowing multiple users to edit content simultaneously without conflicts. --- ![Collaborative editing thumbnail](/img/collaborative-post.png) -The Collaborative Editing extension transforms your Directus project into a real-time collaborative platform where multiple users can edit content simultaneously. This extension provides conflict-free collaborative editing through smart field locking, user awareness indicators, and instant synchronization across all connected clients. +Collaborative Editing transforms your Directus project into a real-time collaborative platform where multiple users can edit content simultaneously. This feature provides conflict-free collaborative editing through smart field locking, user awareness indicators, and instant synchronization across all connected clients. -This documentation covers everything you need to know about implementing, using, and developing with collaborative editing in your Directus projects. +This documentation covers everything you need to know about configuring, using, and developing with collaborative editing in your Directus projects. ## Overview Video @@ -19,11 +19,11 @@ This documentation covers everything you need to know about implementing, using, - **Smart Field Locking** - Automatic conflict prevention through field-level locking - **User Awareness** - Visual indicators show who's editing what in real-time - **Universal Support** - Works across collections, file library, user directory, and relationships -- **Flexible Configuration** - Deploy globally or selectively per collection +- **Flexible Configuration** - Deploy globally across your project ## How It Works -The Collaborative Editing extension provides a sophisticated real-time collaboration experience: +Collaborative Editing provides a sophisticated real-time collaboration experience: | Feature | Traditional Way | Collaborative Editing | |---------|-------------------|----------------------| @@ -35,25 +35,38 @@ The Collaborative Editing extension provides a sophisticated real-time collabora ## Getting Started -Follow these guides to implement collaborative editing in your Directus project: +Follow these guides to set up collaborative editing in your Directus project: -1. **[Installation & Configuration](/guides/content/collaborative-editing/installation)** - Install the extension and configure settings -2. **[Usage Guide](/guides/content/collaborative-editing/usage)** - Learn the basics of collaborative editing -3. **[Development & Custom Extensions](/guides/content/collaborative-editing/development)** - Integrate with custom interfaces +::callout{icon="material-symbols:settings-suggest-rounded" color="primary" to="/guides/content/collaborative-editing/configuration"} +**Configuration** +Configure settings and environment variables. +:: + +::callout{icon="material-symbols:menu-book-outline" color="secondary" to="/guides/content/collaborative-editing/usage"} +**Usage Guide** +Learn the basics of collaborative editing. +:: + +::callout{icon="material-symbols:code-blocks-rounded" color="green" to="/guides/content/collaborative-editing/development"} +**Development & Custom Extensions** +Integrate with custom interfaces. +:: ## Requirements -- **Directus 11.8.0 or higher** +- **Directus 11.15.0 or higher** - **[WebSockets enabled](/configuration/realtime)** in your Directus configuration -- **[Marketplace trust settings](/configuration/extensions#marketplace)** configured for non-sandboxed extensions (if installing through Marketplace) ## Technology Overview -The extension uses Y.js CRDT technology for conflict-free collaborative editing and WebSocket communication for real-time synchronization. All collaborative actions respect Directus user permissions and access controls. +The feature uses a custom WebSocket implementation for real-time synchronization and smart field locking to prevent conflicts. All collaborative actions respect Directus user permissions and access controls. ## Next Steps -Ready to enable collaborative editing? Start with the [Installation & Configuration](/guides/content/collaborative-editing/installation) guide to get up and running, then explore the [Usage Guide](/guides/content/collaborative-editing/usage) for daily workflows. +::callout{icon="material-symbols:arrow-forward-rounded" color="primary" to="/guides/content/collaborative-editing/configuration"} +**Ready to get started?** +Start with the Configuration guide to get up and running. +:: Transform your Directus project into a collaborative workspace where teams can work together seamlessly on content creation and management. diff --git a/content/guides/02.content/9.collaborative-editing/1.configuration.md b/content/guides/02.content/9.collaborative-editing/1.configuration.md new file mode 100644 index 00000000..e6221435 --- /dev/null +++ b/content/guides/02.content/9.collaborative-editing/1.configuration.md @@ -0,0 +1,43 @@ +--- +title: Configuration +description: Learn how to configure the Collaborative Editing feature in your Directus project. +--- + +This guide covers the configuration settings for the Collaborative Editing feature. + +## Configuration + +::callout{icon="material-symbols:info-outline"} +**Enabled by Default** +Collaborative Editing is automatically enabled when WebSockets are active. For detailed configuration options and environment variables, please refer to the [Collaborative Editing Configuration](/configuration/realtime#collaborative-editing) documentation. +:: + +## Verification + +To verify that collaborative editing is working correctly: + +1. **Verify WebSockets**: Ensure your Directus instance has WebSockets enabled (`WEBSOCKETS_ENABLED=true`). +2. **Verify Project Settings**: Ensure your Directus instance has Collaborative Editing enabled in Project Settings. +3. **Test Collaboration**: Open any collection item and look for the collaboration indicators (avatar stack in the header). +4. **Multi-User Test**: Have another user open the same item and you should see their avatar appear. + +## Troubleshooting + +### WebSocket Connection Failed +- Confirm `WEBSOCKETS_ENABLED=true` is set. +- Check that your server/proxy supports WebSocket connections. +- Verify firewall settings allow WebSocket traffic. + +### Redis Issues (Multi-Instance) +- Ensure all instances are connected to the same Redis server. +- Verify the `WEBSOCKETS_COLLAB_STORE_NAMESPACE` if sharing a Redis instance with other applications (default is `collab`). + +### Debug Logging + +Enable debug logging to troubleshoot issues. + +```bash +LOG_LEVEL="debug" +``` + +This will provide detailed information about WebSocket connections, user events, and collaboration activities in your Directus logs. diff --git a/content/guides/02.content/9.collaborative-editing/1.installation.md b/content/guides/02.content/9.collaborative-editing/1.installation.md deleted file mode 100644 index e58ed243..00000000 --- a/content/guides/02.content/9.collaborative-editing/1.installation.md +++ /dev/null @@ -1,209 +0,0 @@ ---- -title: Installation & Configuration -description: Learn how to install and configure the Collaborative Editing extension to enable real-time collaboration in your Directus project. ---- - -This guide covers installing the Collaborative Editing extension either manually or from the Directus Marketplace, configuring collaboration settings, and verifying that real-time collaboration is working in your project. - -## Before You Start - -Before installing the Collaborative Editing extension, ensure you have: - -- **Admin access** to your Directus project -- **Directus 11.8.0 or higher** installed and running -- **WebSocket support** enabled in your Directus configuration -- **Extension installation permissions** on your server or hosting environment - - -::callout{icon="material-symbols:info" color="warning"} -**WebSocket Configuration** -
-Collaborative editing requires WebSocket support to function. Make sure your Directus instance has WebSockets properly configured according to the [official WebSocket documentation](https://directus.io/docs/configuration/realtime). -:: - -## Installation - -
- - -### From Directus Marketplace - -1. Navigate to your Directus admin panel -2. Go to **Settings → Marketplace** -3. Search for "Collaborative Editing" -4. Click **Install** on the `@directus-labs/collaborative-editing` extension - -::callout{icon="material-symbols:warning-rounded" color="warning"} -**Important Note: While this extension is developed by our Directus core team, it is not sandboxed.** -
-If you want to install from the Directus Marketplace, set the `MARKETPLACE_TRUST` variable in your [Directus Configuration](https://directus.io/docs/configuration/extensions#marketplace) to `all`. Be extremely careful about installing any extensions from untrusted sources. [Learn more about extensions and the sandboxed extensions](https://directus.io/docs/guides/extensions/api-extensions/sandbox). -:: - -### Manual Installation - -For other installation methods: - -```bash -npm install @directus-labs/collaborative-editing -``` - -Then follow the [Official Guide](https://directus.io/docs/self-hosting/including-extensions) for manual extension installation. - -### Self-Hosted Docker Installation - -For self-hosted Directus projects using Docker, you need to build a custom image to include the extension: - -#### 1. Modify Docker Compose File - -In your `docker-compose.yml` file, delete the `image` property and add a `build` section to the `directus` service: - -```yaml -services: - directus: - build: - context: ./ - # Remove the image: directus/directus:latest line -``` - -#### 2. Create a Dockerfile - -At the root of your project, create a file called `Dockerfile`: - -```dockerfile -FROM directus/directus:latest - -USER root -RUN corepack enable -USER node - -RUN pnpm install @directus-labs/collaborative-editing -# You can add any other extensions you want here as well -``` - -#### 3. Build and Run - -Build your Docker image and start the container: - -```bash -docker compose build -docker compose up -``` - -After starting the container, navigate to your Directus admin panel. Go to **Settings → Extensions** to verify that "Collaborative Editing" appears in the extensions list. - -### Enterprise Installation - -For Directus Enterprise customers with custom extensions repositories: - -1. **Pull the Extension**: Clone the extension from the [Directus Labs repository](https://github.com/directus-labs/extensions) -2. **Build Locally**: Build the extension following your standard development process -3. **Add to Extensions Repository**: Place the built extension in your extensions repository directory -4. **Create Pull Request**: Follow your organization's review and merge process -5. **Wait for Deployment**: After merging, the extension will be available in your project within 5-15 minutes - -If you're unfamiliar with this process, contact the Directus support team for assistance. - - -## Configuration - -### Enable the Module - -After installation, you need to enable the Collaborative Editing module: - -1. **Navigate to Module Settings**: - - Go to **Settings → Module Bar** - - Find "Collaborative Editing" in the list - - Toggle it **ON** to enable the module - - Don't forget to **Save** the settings - -![Collaborative editing module bar settings](/img/collaborative-settings-module-bar.png) - -2. **Access the Module**: - - The Collaborative Editing icon will now appear in your module bar - - Click the icon to access the configuration settings - -### Configure Collaboration Settings - -When you first access the Collaborative Editing module, you'll see a message that settings are missing. Click **Create Collaborative Editing Settings** to automatically generate the necessary configuration: - -![Collaborative editing settings page](/img/collaborative-settings-page.png) - -#### Global Approach (Recommended) - -By default, collaborative editing is enabled globally across your entire Directus project: - -- **Enable Collaborative Editing Globally** - Toggle to enable collaboration across all collections, file library, and user directory -- This is the easiest method and works immediately -- Provides collaboration everywhere without additional setup - -#### Selective Approach - -For more granular control, you can disable global collaboration and enable it per collection: - -1. **Disable Global Setting**: - - Turn off "Enable Collaborative Editing Globally" in the module settings - -2. **Enable Per Collection**: - - Navigate to your collection's **Data Model** settings - - Click **Create Field** - - Search for and add the **"Collaboration"** interface - - Set the field type as **Alias** with **Presentation** display - - Save the field configuration - -This approach works well for projects with sensitive data where you need more granular control over which collections support collaboration. - -## Verification - -To verify the installation is working correctly: - -1. **Check Extensions**: Navigate to **Settings → Extensions** and confirm "Collaborative Editing" is listed -2. **Enable Module**: Go to **Settings → Module Bar**, check the Collaborative Editing box, and save -3. **Create Settings**: Access the Collaborative Editing module and click **Create Collaborative Editing Settings** -4. **Test Collaboration**: Open any collection item and look for the small collaboration icon showing your user avatar -5. **Multi-User Test**: Have another user open the same item - you should see their avatar appear when they edit different fields - -## Troubleshooting - -### Potential Issues - -**Module Not Appearing** -- Verify the extension is properly installed -- Check that the module is enabled in Settings → Module Bar -- Restart your Directus project if needed - -**WebSocket Connection Failed** -- Confirm `WEBSOCKETS_ENABLED=true` is set in your environment -- Check your server configuration supports WebSocket connections -- Verify firewall settings allow WebSocket traffic - -**Settings Not Saving** -- Ensure your user has admin permissions -- Check the browser console for any JavaScript errors -- Verify database write permissions - -### Debug Logging - -Enable debug logging to troubleshoot issues. - -```bash -REALTIME_LOGS_ENABLED=true -``` - -This will provide detailed information about WebSocket connections, user events, and collaboration activities in your Directus logs. - -::callout{icon="material-symbols:info"} -**Need Help?** -
- -If you encounter issues during installation or configuration, check the [Directus Community Forum](https://community.directus.io) or create an issue in the [Extensions Repository](https://github.com/directus-labs/extensions/issues). -:: - -## Summary - -You have successfully installed and configured the Collaborative Editing extension for your Directus project. The extension is now ready to provide real-time collaboration features across your collections, file library, and user management. - - -**Next Steps:** -- Review the [Usage Guide](/guides/content/collaborative-editing/usage) to learn how to use collaborative editing features -- Test the collaboration features with your team members -- If you develop custom interfaces, check the [Development Guide](/guides/content/collaborative-editing/development) for integration instructions diff --git a/content/guides/02.content/9.collaborative-editing/2.usage.md b/content/guides/02.content/9.collaborative-editing/2.usage.md index cce81cd1..e84f38b2 100644 --- a/content/guides/02.content/9.collaborative-editing/2.usage.md +++ b/content/guides/02.content/9.collaborative-editing/2.usage.md @@ -1,6 +1,6 @@ --- title: Usage Guide -description: Learn how to use the Collaborative Editing extension for real-time collaboration on content in your Directus project. +description: Learn how to use the Collaborative Editing feature for real-time collaboration on content in your Directus project. --- This guide covers the essential features you'll use when collaborating on content in real-time. @@ -39,8 +39,8 @@ Collaborative editing works across: ## Summary -Collaborative editing happens automatically once the extension is enabled. Multiple users can work on the same content simultaneously without conflicts, with clear visual indicators showing who's working where. +Collaborative editing happens automatically once enabled. Multiple users can work on the same content simultaneously without conflicts, with clear visual indicators showing who's working where. **Next Steps:** - Test with teammates to see real-time collaboration in action -- Check out the [Installation Guide](/guides/content/collaborative-editing/installation) if you need to configure settings +- Check out the [Configuration Guide](/guides/content/collaborative-editing/configuration) if you need to configure settings diff --git a/content/guides/02.content/9.collaborative-editing/3.development.md b/content/guides/02.content/9.collaborative-editing/3.development.md index 12f79439..cabe484d 100644 --- a/content/guides/02.content/9.collaborative-editing/3.development.md +++ b/content/guides/02.content/9.collaborative-editing/3.development.md @@ -1,93 +1,80 @@ --- title: Development & Custom Extensions -description: Learn how to integrate the Collaborative Editing extension with custom interfaces and third-party extensions in your Directus project. +description: Learn how Custom Interfaces integrate with Collaborative Editing in Directus. --- -Custom interfaces and extensions can participate in collaborative editing by implementing specific data attributes that the extension uses to detect and manage editable fields. +**Collaborative Editing works out-of-the-box for most Custom Interfaces**. -In this guide, you will learn the required data attributes and see a basic implementation example for making custom interfaces compatible with collaborative editing. +Unlike the previous extension-based implementation, you do **not** need to add specific data attributes to your components. The system automatically handles presence, field locking, and synchronization through the `v-form` and `form-field` wrappers. -## Before You Start +## How it Works -To integrate collaborative editing with custom extensions, you should have: +When your Custom Interface is rendered within a Directus Form: -- **JavaScript/TypeScript knowledge** - for developing Directus extensions -- **Vue.js experience** - for creating custom interface components -- **Collaborative Editing extension** - installed and configured in your development environment -- **Development environment** - set up for creating and testing Directus extensions +1. **Automatic wrapping**: Your interface is wrapped by the `form-field` component. +2. **Event Detection**: The wrapper listens for standard DOM `focusin` and `focusout` events bubbling up from your component. +3. **State Management**: When your component receives focus, the wrapper automatically notifies the collaboration system to "lock" the field for other users and display your avatar. -::callout{icon="material-symbols:package" color="info"} -**Collaborative Editing Package** -
-The Collaborative Editing extension (`@directus-labs/collaborative-editing`) automatically detects and integrates with any interface that implements the proper data attributes. No additional dependencies or imports are required in your custom extensions. -:: +## Requirements for Custom Interfaces -## Required Data Attributes +For your custom interface to fully support collaborative editing, ensure the following: -For collaborative editing to function with custom interfaces, three data attributes must be present on the outermost container element: +### 1. Event Bubbling +Your component should allow `focus` and `blur` (or `focusin`/`focusout`) events to bubble up to the parent. This is standard behavior for native HTML inputs (``, `