IBX-7036: Customizable dashboard described in Developer documentation

code_samples/back_office/dashboard/src/Command/DashboardCommand.php

@@ -0,0 +1,71 @@
+<?php declare(strict_types=1);
+
+namespace App\Command;
+
+use Ibexa\Contracts\Core\Repository\ContentService;
+use Ibexa\Contracts\Core\Repository\LocationService;
+use Ibexa\Contracts\Core\Repository\PermissionResolver;
+use Ibexa\Contracts\Core\Repository\Repository;
+use Ibexa\Contracts\Core\Repository\UserService;
+use Ibexa\Contracts\Dashboard\DashboardServiceInterface;
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Input\InputArgument;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Output\OutputInterface;
+
+class DashboardCommand extends Command
+{
+    protected static $defaultName = 'doc:dashboard';
+
+    private DashboardServiceInterface $dashboardService;
+
+    private Locationservice $locationService;
+
+    private ContentService $contentService;
+
+    private UserService $userService;
+
+    private PermissionResolver $permissionResolver;
+
+    public function __construct(
+        DashboardServiceInterface $dashboardService,
+        Repository $repository
+    ) {
+        $this->dashboardService = $dashboardService;
+        $this->locationService = $repository->getLocationService();
+        $this->contentService = $repository->getContentService();
+        $this->userService = $repository->getUserService();
+        $this->permissionResolver = $repository->getPermissionResolver();
+
+        parent::__construct(self::$defaultName);
+    }
+
+    public function configure(): void
+    {
+        $this->setDescription('Set a custom dashboard to user group.')
+            ->addArgument('dashboard', InputArgument::REQUIRED, 'Location ID of the dashboard model')
+            ->addArgument('group', InputArgument::REQUIRED | InputArgument::IS_ARRAY, 'User Group Content ID(s)');
+    }
+
+    protected function execute(InputInterface $input, OutputInterface $output): int
+    {
+        $dashboardModelLocationId = (int)$input->getArgument('dashboard');
+        $userGroupLocationIdList = array_map('intval', $input->getArgument('group'));
+
+        foreach ($userGroupLocationIdList as $userGroupLocationId) {
+            try {
+                $admin = $this->userService->loadUserByLogin('admin');
+                $this->permissionResolver->setCurrentUserReference($admin);
+                foreach ($this->userService->loadUsersOfUserGroup($this->userService->loadUserGroup($userGroupLocationId)) as $user) {
+                    $this->permissionResolver->setCurrentUserReference($user);
+                    $dashboardDraft = $this->dashboardService->createCustomDashboardDraft($this->locationService->loadLocation($dashboardModelLocationId));
+                    $this->contentService->publishVersion($dashboardDraft->getVersionInfo());
+                }
+            } catch (\Throwable $throwable) {
+                dump($throwable);
+            }
+        }
+
+        return self::SUCCESS;
+    }
+}

docs/administration/dashboard/configure_default_dashboard.md

@@ -0,0 +1,73 @@
+---
+title: Default dashboard configuration
+description: Configure default dashboard.
+---
+
+# Configure default dashboard
+
+You can configure default dashboard under the `ibexa.system.<scope>.admin_group` [configuration key](configuration.md#configuration-files).
+
+Create `ibexa_dashboard.yaml` file in the `config/packages/` directory.
+The following example configuration defines default dashboard:
+
+``` yaml
+ibexa:
+    system:
+        admin_group:
+            dashboard:
+                container_remote_id: dashboard_container
+                default_dashboard_remote_id: default_dashboard
+                users_container_remote_id: user_dashboards
+                predefined_container_remote_id: predefined_dashboards
+                section_identifier: dashboard
+                content_type_identifier: dashboard_landing_page
+                container_content_type_identifier: folder
+```
+
+Configuration can be set per [SiteAccess](multisite/multisite_configuration/#siteaccess-configuration)
+or [SiteAccess group](multisite/multisite_configuration/#siteaccess-groups).
+
+All the settings in the configuration are reflected in the Back Office.
+
+## Container remote ID
+
+Defines starting location container for all the dashboards, including customized and predifined ones.
+You can see it in the Admin panel, **Dashboards** section, **Dashboards** folder in the Content Tree. In the **Technical details** tab, it is defined as **Location remote ID**.
+
+![Container remote ID](dashboard_container_remote_id.png)
+
+## Default dashboard remote ID
+
+Specifies default predefined dashboard. This is the dashboard that all the users see as a starting dashboard in the Back Office.
+You can see it in the Admin panel, **Dashboards** section, **Default dashboard** folder inside of **Predefined dashboards** container in the Content Tree.
+In the **Technical details** tab, it is defined as **Location remote ID**.
+
+## Users container remote ID
+
+Defines a container for users folders, which contain all customized dashboards.
+You can see it in the Admin panel, **Dashboards** section, **User dashboards** folder inside of main **Dashboards** container in the Content Tree.
+In the **Technical details** tab, it is defined as **Location remote ID**.
+
+## Predefined container remote ID
+
+Defines a container that contains all predefined dashboards created by Administrator.
+You can see it in the Admin panel, **Dashboards** section, **Predefined dashboards** folder inside of main **Dashboards** container in the Content Tree.
+In the **Technical details** tab, it is defined as **Location remote ID**.
+
+## Section identifier
+
+Specifies the name of the [Section](administration/content_organization/sections/).
+
+## Content type identifier
+
+It is an identifier that represents dashboard content type.
+You can find it in the Admin panel, **Dashboard content Ttpe** section, **View/Global properties** tab.
+
+![Content type identifier](dashboard_content_type_identifier.png)
+
+## Container content type identifier
+
+Determines the content type identifier of the container for dashboards and lets you create additional structure for the predefined dashboards.
+By default all the dashboards containers are set as a folders.
+
+![Container content type](dashboard_container_type.png)

docs/administration/dashboard/customize_dashboard.md

@@ -0,0 +1,39 @@
+---
+title: Dashboard customization
+description: Customize dashboard.
+---
+
+# Customize dashboard
+
+You can customize the dashboard depending on your needs using Dahboard Builder.
+Customized dashboard displays a set of widgets selected by the user.
+
+!!! tip
+
+     Detailed instruction on how to customize dashboard using Dashboard Builder is available in [[[= product_name =]] user documentation](https://doc.ibexa.co/projects/userguide/en/latest/getting_started/discover_ui/).
+
+## Manage permissions
+
+To customize dashboard, you need to have `dashboard/cutomize` [policy](permission_overview.md).
+
+By default, all the users belonging to the `Editors` User Group, have `Dashboard`[Role](roles_admin_panel.md) assigned, so they can edit, create, or delete dashboard.
+If, by any reason, you want to narrow this permission, you can set up specific [limitations](limitations.md).
+
+## Add custom layout
+
+For new dashboard you need to choose layout which defines the available zones.
+While opening Dashboard Builder, layout window appears - you can choose one from available layouts.
+
+You can also add custom layout that then can be available in Dashboard Builder.
+
+For more information, see [Customize storefront layout](customize_storefront_layout.md).
+
+## Create custom blocks
+
+Dashboard builder provides set of ready-to-use blocks, for example, Common content, Quick actions, or [[= product_name =]] News.
+
+For more information about available blocks, see [[[= product_name =]] user documentation](https://doc.ibexa.co/projects/userguide/en/latest/getting_started/dashboard_block_reference/).
+
+In addition to existing blocks available in Dashboard Builder, you can also create custom blocks.
+
+To do it, follow the instruction on how to [create custom Page block](create_custom_page_block.md).

docs/administration/dashboard/php_api_dashboard_service.md

@@ -0,0 +1,35 @@
+---
+title: Dashboard service's PHP API
+description: Use DashboardService to manage dashboards.
+---
+
+# DashboardService's PHP API
+
+You can use `DashboardService`'s PHP API to manage custom dashboards.
+To obtain this service, inject the `Ibexa\Contracts\Dashboard\DashboardServiceInterface`.
+
+The service exposes two functions:
+
+- `createCustomDashboardDraft(?Location $location = null): Content` - returns a new Content item in draft state of `dashboard` Content Type.
+  If no location is given, it creates a copy of the dashboard of the user currently logged in.
+  If a location is given, it creates a copy with the given location.
+  The default name of the customized dashboard is set as `My dashboard`.
+  This new Content draft is located in the current user custom dashboard container.
+- `createDashboard(DashboardCreateStruct $dashboardCreateStruct): Content` - publishes the given dashboard creation structure (`Ibexa\Contracts\Dashboard\Values\DashboardCreateStruct`) under `dashboard.predefined_container_remote_id`.
+
+## Customize dashboard using DashboardService
+
+The following example is a command deploying a custom dashboard to users of content groups.
+Using the `admin` account, it loads the group members, logs each one in, creates a custom dashboard by copying a default one, and then publishes the draft version of customized dashboard.
+First argument is the `Content ID` of the dashboard to copy.
+Following arguments are the Content IDs of the user groups.
+
+``` php hl_lines="61"
+[[= include_file('code_samples/back_office/dashboard/src/Command/DashboardCommand.php') =]]
+```
+
+The following line runs the command with `74` as the model dashboard's Content ID, `13` the user group's Content ID, and on the SiteAccess `admin` to have the right `user_content_type_identifier` config:
+
+```bash
+php bin/console doc:dashboard 74 13 --siteaccess=admin
+```

mkdocs.yml

@@ -91,6 +91,10 @@ nav:
             - Project organization: administration/project_organization/project_organization.md
             - Architecture: administration/project_organization/architecture.md
             - Bundles: administration/project_organization/bundles.md
+        - Dashboard:
+            - Configure default dashboard: administration/dashboard/configure_default_dashboard.md
+            - Customize dashboard: administration/dashboard/customize_dashboard.md
+            - PHP API Dashboard service: administration/dashboard/php_api_dashboard_service.md
         - Admin panel:
             - Admin panel: administration/admin_panel/admin_panel.md
             - Users: administration/admin_panel/users_admin_panel.md