From c94c8b61f260adc4ca2cd1590f556c1ff3ff13b2 Mon Sep 17 00:00:00 2001
From: Alexander Schranz <alexander@sulu.io>
Date: Fri, 6 Dec 2024 15:03:03 +0100
Subject: [PATCH] Init basic docs about admin bundle

---
 _themes/sulu/static/sulu.css_t |   4 +-
 bundles/admin/index.rst        | 158 +++++++++++++++++++++++++++++++++
 bundles/index.rst              |   1 +
 3 files changed, 161 insertions(+), 2 deletions(-)
 create mode 100644 bundles/admin/index.rst

diff --git a/_themes/sulu/static/sulu.css_t b/_themes/sulu/static/sulu.css_t
index bbcad6c2..0cf340c6 100644
--- a/_themes/sulu/static/sulu.css_t
+++ b/_themes/sulu/static/sulu.css_t
@@ -188,8 +188,8 @@ div.toctree-wrapper a {
 }
 
 div.toctree-wrapper a {
-    color: #112a46;
-    text-decoration: none;
+    color: #52B6CA;
+    text-decoration: underline;
 }
 
 div.toctree-wrapper a:hover {
diff --git a/bundles/admin/index.rst b/bundles/admin/index.rst
new file mode 100644
index 00000000..c1081c23
--- /dev/null
+++ b/bundles/admin/index.rst
@@ -0,0 +1,158 @@
+AdminBundle
+============
+
+The AdminBundle provides all functionality for the Sulu Admin UI. It allows
+to extend the Admin UI to integrate custom functionality or modify existing
+views with new functionality.
+
+The Admin Class
+---------------
+
+The Admin class is the main entry point for the Admin UI. It is responsible
+to configure Navigation Items, Views, Security and other parts of the Admin UI.
+
+It is best practice to create one Admin class per resource type, e.g. one for an
+``Event`` resource.
+
+.. code-block:: php
+
+    <?php
+
+    namespace App\Admin;
+
+    use Sulu\Bundle\AdminBundle\Admin\Admin;
+    use Sulu\Bundle\AdminBundle\Admin\Navigation\NavigationItemCollection;
+    use Sulu\Bundle\AdminBundle\Admin\View\ViewBuilderFactoryInterface;
+    use Sulu\Bundle\AdminBundle\Admin\View\ViewCollection;
+
+    class EventAdmin extends Admin
+    {
+        public function __construct(private ViewBuilderFactoryInterface $viewBuilderFactory)
+        {
+        }
+
+        public function configureNavigationItems(NavigationItemCollection $navigationItemCollection): void
+        {
+            // add navigation items
+        }
+
+        public function configureViews(ViewCollection $viewCollection): void
+        {
+            // add views
+        }
+
+        public function getSecurityContexts(): array
+        {
+            return [];
+        }
+    }
+
+Navigation Items
+----------------
+
+Navigation Items are the items in the left sidebar of the Admin UI. They are configurable
+and are linking to different views.
+
+.. code-block:: php
+
+    <?php
+
+    namespace App\Admin;
+
+    use Sulu\Bundle\AdminBundle\Admin\Admin;
+    use Sulu\Bundle\AdminBundle\Admin\Navigation\NavigationItem;
+    use Sulu\Bundle\AdminBundle\Admin\Navigation\NavigationItemCollection;
+
+    class EventAdmin extends Admin
+    {
+        public const LIST_VIEW = 'app_event.list';
+
+        public function configureNavigationItems(NavigationItemCollection $navigationItemCollection): void
+        {
+            $item = new NavigationItem('app.events'); // translation key inside the admin translation domain
+            $item->setPosition(70);
+            $item->setIcon('su-clock'); // icon from Sulu icon font or font awesome seehttps://jsdocs.sulu.io/2.5/#icon
+            $item->setView(static::LIST_VIEW);
+
+            $navigationItemCollection->add($item);
+        }
+
+        // ...
+    }
+
+Every item can have a title, an icon, a position and a view. The view is the key which best practices is
+to reference by a constants which you also use in the View Builder tackled later in this documentations.
+
+Security Checker
+----------------
+
+If you have different user roles you want to make sure only specific users see specific navigation items or view.
+Via injecting the securityChecker service and providing new security context it is possible to check if a user
+has permissions for a specific security context.
+
+.. code-block:: php
+
+    <?php
+
+    namespace App\Admin;
+
+    use Sulu\Bundle\AdminBundle\Admin\Admin;
+    use Sulu\Bundle\AdminBundle\Admin\Navigation\NavigationItemCollection;
+    use Sulu\Bundle\AdminBundle\Admin\View\ViewCollection;
+    use Sulu\Component\Security\Authorization\PermissionTypes;
+
+    class EventAdmin extends Admin
+    {
+        public const SECURITY_CONTEXT = 'sulu.event.events';
+
+        public function __construct(
+            private SecurityCheckerInterface $securityChecker,
+        ) {
+        }
+
+        public function configureNavigationItems(NavigationItemCollection $navigationItemCollection): void
+        {
+            if ($this->securityChecker->hasPermission(static::SECURITY_CONTEXT, PermissionTypes::EDIT)) {
+                // add navigation items
+            }
+        }
+
+        public function configureViews(ViewCollection $viewCollection): void
+        {
+            if ($this->securityChecker->hasPermission(static::SECURITY_CONTEXT, PermissionTypes::EDIT)) {
+                // add views
+            }
+        }
+
+        public function getSecurityContexts()
+        {
+            return [
+                self::SULU_ADMIN_SECURITY_SYSTEM => [
+                    'Event' => [
+                        self::SECURITY_CONTEXT => [
+                            PermissionTypes::VIEW,
+                            PermissionTypes::ADD,
+                            PermissionTypes::EDIT,
+                            PermissionTypes::DELETE,
+                        ],
+                    ],
+                ],
+            ];
+        }
+    }
+
+Views
+-----
+
+Views are the main content of the Admin UI. They are configurable and required to extend the Admin UI
+with new tabs and navigation items.
+
+List View Builder
+~~~~~~~~~~~~~~~~~
+
+ToDo
+
+Form View Builder
+~~~~~~~~~~~~~~~~~
+
+ToDo
diff --git a/bundles/index.rst b/bundles/index.rst
index ddeea5f4..f60147cf 100644
--- a/bundles/index.rst
+++ b/bundles/index.rst
@@ -11,6 +11,7 @@ documented the most important ones.
     :maxdepth: 2
 
     activity
+    admin/index
     audience_targeting
     category
     contact