Installation and configuration for Collaborative Editing

code_samples/collaboration/src/Command/ManageSessionsCommand.php

@@ -0,0 +1,174 @@
+<?php
+
+/**
+ * @copyright Copyright (C) Ibexa AS. All rights reserved.
+ * @license For full copyright and license information view LICENSE file distributed with this source code.
+ */
+declare(strict_types=1);
+
+namespace App\Command;
+
+use Ibexa\Contracts\Collaboration\Invitation\InvitationCreateStruct;
+use Ibexa\Contracts\Collaboration\Invitation\InvitationQuery;
+use Ibexa\Contracts\Collaboration\Invitation\InvitationStatus;
+use Ibexa\Contracts\Collaboration\Invitation\InvitationUpdateStruct;
+use Ibexa\Contracts\Collaboration\Invitation\Query\Criterion\Session;
+use Ibexa\Contracts\Collaboration\InvitationServiceInterface;
+use Ibexa\Contracts\Collaboration\Participant\ExternalParticipantCreateStruct;
+use Ibexa\Contracts\Collaboration\Participant\InternalParticipantCreateStruct;
+use Ibexa\Contracts\Collaboration\Participant\InternalParticipantUpdateStruct;
+use Ibexa\Contracts\Collaboration\Session\Query\Criterion\Token;
+use Ibexa\Contracts\Collaboration\Session\SessionQuery;
+use Ibexa\Contracts\Collaboration\SessionServiceInterface;
+use Ibexa\Contracts\Core\Repository\ContentService;
+use Ibexa\Contracts\Core\Repository\PermissionResolver;
+use Ibexa\Contracts\Core\Repository\UserService;
+use Ibexa\Contracts\Share\Collaboration\ContentSessionCreateStruct;
+use Ibexa\Contracts\Share\Collaboration\ContentSessionScope;
+use Ibexa\Contracts\Share\Collaboration\ContentSessionUpdateStruct;
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Output\OutputInterface;
+
+final class ManageSessionsCommand extends Command
+{
+    protected static $defaultName = 'app:manage-sessions';
+
+    private InvitationServiceInterface $invitationService;
+
+    private SessionServiceInterface $sessionService;
+
+    private ContentService $contentService;
+
+    private UserService $userService;
+
+    private PermissionResolver $permissionResolver;
+
+    public function __construct(
+        InvitationServiceInterface $invitationService,
+        SessionServiceInterface $sessionService,
+        ContentService $contentService,
+        UserService $userService,
+        PermissionResolver $permissionResolver
+    ) {
+        parent::__construct(self::$defaultName);
+
+        $this->invitationService = $invitationService;
+        $this->sessionService = $sessionService;
+        $this->contentService = $contentService;
+        $this->userService = $userService;
+        $this->permissionResolver = $permissionResolver;
+    }
+
+    public function execute(InputInterface $input, OutputInterface $output): int
+    {
+        $this->permissionResolver->setCurrentUserReference(
+            $this->userService->loadUserByLogin('admin')
+        );
+
+        // Create a sharing session for Content
+        $versionInfo = $this->contentService->loadContent(52)->getVersionInfo();
+        $createStruct = new ContentSessionCreateStruct(
+            $versionInfo,
+            $versionInfo->getInitialLanguage()
+        );
+        $createStruct->setHasPublicLink(false);
+
+        $token = 'my-secret-token-12345';
+        $createStruct->setToken($token);
+
+        $sessionId = $this->sessionService->createSession($createStruct)->getId();
+
+        // Get a session by ID or token
+        $session = $this->sessionService->getSession($sessionId);
+        $session = $this->sessionService->getSessionByToken($token);
+
+        // Find sessions
+        $sessionQuery = new SessionQuery(new Token($token));
+        $session = $this->sessionService->findSessions($sessionQuery)->getFirst();
+
+        // Update a session
+        $updateStruct = new ContentSessionUpdateStruct();
+        $updateStruct->setHasPublicLink(true);
+
+        $this->sessionService->updateSession($session, $updateStruct);
+
+        // Deactivate a session
+        $updateStruct = new ContentSessionUpdateStruct();
+        $updateStruct->setIsActive(false);
+
+        $this->sessionService->updateSession($session, $updateStruct);
+
+        // Manage participants
+        $user = $this->userService->loadUserByLogin('another_user');
+        $internalParticipantCreateStruct = new InternalParticipantCreateStruct(
+            $user,
+            ContentSessionScope::VIEW
+        );
+        $externalParticipantCreateStruct = new ExternalParticipantCreateStruct(
+            '[email protected]',
+            ContentSessionScope::VIEW,
+            'personal-secret-token-12345'
+        );
+
+        $internalParticipant = $this->sessionService->addParticipant($session, $internalParticipantCreateStruct);
+        $externalParticipant = $this->sessionService->addParticipant($session, $externalParticipantCreateStruct);
+
+        // Get and update participants
+        $participant = $this->sessionService
+            ->getSession($session->getId())
+            ->getParticipants()
+            ->getByEmail($user->email);
+
+        $internalParticipantUpdateStruct = new InternalParticipantUpdateStruct(ContentSessionScope::EDIT);
+        $this->sessionService->updateParticipant($session, $participant, $internalParticipantUpdateStruct);
+
+        // Remove participant
+        $this->sessionService->removeParticipant($session, $externalParticipant);
+
+        // Check ownerships. If no user is provided, current user is used.
+        $this->sessionService->isSessionOwner(
+            $session,
+            $this->userService->loadUserByLogin('another_user')
+        );
+
+        // Check participation
+        $this->sessionService->isSessionParticipant(
+            $session,
+            $this->permissionResolver->getCurrentUserReference()
+        );
+
+        // Manage invitations
+        $invitationQuery = new InvitationQuery(new Session($session));
+        $invitations = $this->invitationService->findInvitations($invitationQuery)->getInvitations();
+
+        foreach ($invitations as $invitation) {
+            $output->writeln('Invitation ID: ' . $invitation->getId() . ' Status: ' . $invitation->getStatus());
+        }
+
+        $invitation = $this->invitationService->getInvitationByParticipant($participant);
+
+        // Create invitation - use when auto-inviting participants is not enabled
+        $invitationCreateStruct = new InvitationCreateStruct(
+            $session,
+            $internalParticipant
+        );
+
+        $this->invitationService->createInvitation($invitationCreateStruct);
+
+        // Update invitation
+        $invitationUpdateStruct = new InvitationUpdateStruct();
+        $invitationUpdateStruct->setStatus(InvitationStatus::STATUS_REJECTED);
+
+        $this->invitationService->updateInvitation($invitation, $invitationUpdateStruct);
+
+        // Delete invitation
+        $invitation = $this->invitationService->getInvitation(2);
+        $this->invitationService->deleteInvitation($invitation);
+
+        // Delete a session
+        $this->sessionService->deleteSession($session);
+
+        return Command::SUCCESS;
+    }
+}

docs/content_management/collaborative_editing/collaborative_editing.md

@@ -0,0 +1,25 @@
+---
+description: Collaborative editing enables multiple users to work on the same content simultaneously.
+page_type: landing_page
+editions:
+    - lts-update
+month_change: true
+---
+
+# Collaborative editing
+
+With Collaborative editing feature multiple users can work on the same content created in [[= product_name =]] simultaneously.
+This feature allows multiple users to work together on the same content item in real time, streamlining the content creation and review process.
+
+Users can invite both internal and external collaborators to a session, giving them access for editing or previewing.
+
+Additionaly, they can collaborate using a Real-time collaboration, an advanced part of the collaboration feature, to write and review content in a live mode thanks to CKEditor.
+Real-time collaboration syncs changes instantly and shows user avatars and colored tags to indicate who is editing specific part of the Rich Text field.
+
+This feature also introduces new dashboard tabs for managing shared drafts and joining collaboration sessions easily.
+
+[[= cards([
+"content_management/collaborative_editing/collaborative_editing_guide",
+"content_management/collaborative_editing/install_collaborative_editing",
+"content_management/collaborative_editing/collaborative_editing_api"
+], columns=3) =]]

docs/content_management/collaborative_editing/collaborative_editing_api.md

@@ -0,0 +1,191 @@
+---
+description: Use PHP API to manage invitations, sessions, and participants while using collaborative editing feature.
+editions:
+    - lts-update
+month_change: true
+---
+
+# Collaborative editing API
+
+[[= product_name =]]'s Collaborative editing API provides two services for managing sessions and invitations, which differ in function:
+
+- [`InvitationServiceInterface`](https://doc.ibexa.co/en/latest/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-InvitationServiceInterface.html) is used to manage collaboration sessions invitations
+- [`SessionServiceInterface`](https://doc.ibexa.co/en/latest/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-SessionServiceInterface.html) is used to manage collaboration sessions
+
+## Managing sessions
+
+### Create session
+
+You can create new collaboration session with [`SessionService::createSession`](https://doc.ibexa.co/en/latest/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-SessionServiceInterface.html#method_createSession):
+
+``` php
+[[= include_file('code_samples/collaboration/src/Command/ManageSessionsCommand.php', 69, 81) =]]
+```
+
+### Get session
+
+You can get an existing collaboration session with [`SessionService::getSession`](https://doc.ibexa.co/en/latest/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-SessionServiceInterface.html#method_getSession):
+
+- using given id - with [`SessionService::getSession`](https://doc.ibexa.co/en/latest/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-SessionServiceInterface.html#method_getSession)
+
+``` php
+[[= include_file('code_samples/collaboration/src/Command/ManageSessionsCommand.php', 82, 83) =]]
+```
+
+- using given token - with [`SessionService::getSessionByToken`](https://doc.ibexa.co/en/latest/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-SessionServiceInterface.html#method_getSessionByToken)
+
+``` php
+[[= include_file('code_samples/collaboration/src/Command/ManageSessionsCommand.php', 83, 84) =]]
+```
+
+### Find sessions
+
+You can find an existing session with [`SessionService::findSessions`](https://doc.ibexa.co/en/latest/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-SessionServiceInterface.html#method_findSessions) by:
+
+``` php
+[[= include_file('code_samples/collaboration/src/Command/ManageSessionsCommand.php', 86, 89) =]]
+```
+
+### Update session
+
+You can update existing invitation with [`SessionService::updateSession`](https://doc.ibexa.co/en/latest/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-SessionServiceInterface.html#method_updateSession):
+
+``` php
+[[= include_file('code_samples/collaboration/src/Command/ManageSessionsCommand.php', 90, 95) =]]
+```
+
+### Deactivate session
+
+You can deactivate session with [`SessionService::deleteSession`](https://doc.ibexa.co/en/latest/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-SessionServiceInterface.html#method_deactivateSession):
+
+``` php
+[[= include_file('code_samples/collaboration/src/Command/ManageSessionsCommand.php', 96, 101) =]]
+```
+
+### Delete session
+
+You can delete session with [`SessionService::deleteSession`](https://doc.ibexa.co/en/latest/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-SessionServiceInterface.html#method_deleteSession):
+
+``` php
+[[= include_file('code_samples/collaboration/src/Command/ManageSessionsCommand.php', 169, 170) =]]
+```
+
+## Managing participants
+
+### Add participant
+
+You can add participant to the collaboration session with [`SessionService::addParticipant`](https://doc.ibexa.co/en/latest/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-SessionServiceInterface.html#method_addParticipant):
+
+``` php
+[[= include_file('code_samples/collaboration/src/Command/ManageSessionsCommand.php', 102, 116) =]]
+```
+
+### Get and update participant
+
+You can update participant added to the collaboration session with [`SessionService::updateParticipant`](https://doc.ibexa.co/en/latest/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-SessionServiceInterface.html#method_updateParticipant):
+
+``` php
+[[= include_file('code_samples/collaboration/src/Command/ManageSessionsCommand.php', 117, 125) =]]
+```
+### Remove participant
+
+You can remove participant from the collaboration session with [`SessionService::removeParticipant`](https://doc.ibexa.co/en/latest/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-SessionServiceInterface.html#method_removeParticipant):
+
+``` php
+[[= include_file('code_samples/collaboration/src/Command/ManageSessionsCommand.php', 126, 127) =]]
+```
+
+### Check session owner
+
+You can check the owner of the collaboration session with [`SessionService::isSessionOwner`](https://doc.ibexa.co/en/latest/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-SessionServiceDecorator.html#method_isSessionOwner):
+
+``` php
+[[= include_file('code_samples/collaboration/src/Command/ManageSessionsCommand.php', 129, 134) =]]
+```
+
+If no user is provided, current user is used.
+
+### Check session participant
+
+You can check the participant of the collaboration session with [`SessionService::isSessionParticipant`](https://doc.ibexa.co/en/latest/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-SessionServiceInterface.html#method_isSessionParticipant):
+
+``` php
+[[= include_file('code_samples/collaboration/src/Command/ManageSessionsCommand.php', 135, 140) =]]
+```
+
+## Managing invitations
+
+### Manage invitation
+
+You can get an invitation with [`InvitationService::getInvitation`](https://doc.ibexa.co/en/latest/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-InvitationServiceInterface.html#method_getInvitation):
+
+
+``` php
+[[= include_file('code_samples/collaboration/src/Command/ManageSessionsCommand.php', 141, 150) =]]
+```
+
+You can select the parameter that you can read from an invitation:
+
+- Invitation ID:
+
+``` php
+    $invitation->getId();
+```
+
+- Session ID:
+
+``` php
+    $invitation->getSession()->getId();
+```
+
+- Participant ID:
+
+``` php
+    $invitation->getParticipant()->getId();
+```
+
+- Invitation status:
+
+``` php
+    $invitation->getStatus();
+```
+
+### Create invitation
+
+You can create new invitation for the collaborative session using the [`InvitationService::createInvitation`](https://doc.ibexa.co/en/latest/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-InvitationServiceInterface.html#method_createInvitation) method:
+
+``` php
+[[= include_file('code_samples/collaboration/src/Command/ManageSessionsCommand.php', 151, 158) =]]
+```
+
+You can use it when auto-inviting participants is not enabled.
+
+### Update invitation
+
+You can update existing invitation with [`InvitationService::updateInvitation`](https://doc.ibexa.co/en/latest/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-InvitationServiceInterface.html#method_updateInvitation):
+
+``` php
+[[= include_file('code_samples/collaboration/src/Command/ManageSessionsCommand.php', 159, 164) =]]
+```
+
+### Delete invitation
+
+You can delete an invitation with [`InvitationService::deleteInvitation`](https://doc.ibexa.co/en/latest/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-InvitationServiceInterface.html#method_deleteInvitation):
+
+``` php
+[[= include_file('code_samples/collaboration/src/Command/ManageSessionsCommand.php', 165, 168) =]]
+```
+
+### Find invitations
+
+You can find an invitation with [`InvitationService::findInvitations`](https://doc.ibexa.co/en/latest/api/php_api/php_api_reference/classes/Ibexa-Contracts-Collaboration-InvitationServiceInterface.html#method_findInvitations).
+
+To learn more about the available search options, see Search Criteria and Sort Clauses for Collaborative editing.
+
+## Example API usage
+
+Below you can see an example of API usage for Collaborative editing:
+
+``` php
+[[= include_file('code_samples/collaboration/src/Command/ManageSessionsCommand.php') =]]
+```