Default-HTML-Frame for Mail in System Style (1/3)

components/ILIAS/UI/src/Component/Layout/Page/Factory.php

@@ -20,6 +20,8 @@
 
 namespace ILIAS\UI\Component\Layout\Page;
 
+use ILIAS\UI\Component\Legacy\Content;
+use ILIAS\Data\Link;
 use ILIAS\UI\Component\MainControls\Mainbar;
 use ILIAS\UI\Component\MainControls\MetaBar;
 use ILIAS\UI\Component\Breadcrumbs\Breadcrumbs;
@@ -109,4 +111,43 @@ public function standard(
         string $short_title = '',
         string $view_title = ''
     ): Standard;
+
+    /**
+     * ---
+     * description:
+     *   purpose: The Mail Page is used to render HTML content for mails.
+     *   composition: >
+     *    The Mail Page consists of HTML content, a header and a footer.
+     *    The header contains the logo and the installation-text.
+     *    The footer contains the installation-text and a link to ILIAS.
+     *    The stylesheet path refers to the CSS file that is used to style the page and will be included in the HTML.
+     *
+     * rules:
+     *   usage:
+     *     1: The Mail Page MUST be rendered with content.
+     *     2: >
+     *        The Mail Page MUST be rendered with a logo.
+     *        The logo must be either
+     *        a cid URL (see https://datatracker.ietf.org/doc/html/rfc2392)
+     *        or a data URL (see https://developer.mozilla.org/en-US/docs/Web/URI/Reference/Schemes/data).
+     *     3: The Mail Page MUST be rendered with a footer.
+     *     4: The Mail Page MUST be rendered with a stylesheet path.
+     *     5: The Header of the Mail Page MUST contain the logo and the installation-text.
+     *     6: The Footer of the Mail Page MUST contain the installation-text and a link to ILIAS.
+     *     7: The Mail Page's stylesheet path MUST include all necessary styles to render the page correctly.
+     * ----
+     * @param string $stylesheet_path
+     * @param string $logo_url
+     * @param string $installation_title
+     * @param \ILIAS\UI\Component\Legacy\Content $html_content
+     * @param Link $footer_url
+     * @return \ILIAS\UI\Component\Layout\Page\Mail
+     */
+    public function mail(
+        string $stylesheet_path,
+        string $logo_url,
+        string $installation_title,
+        Content $html_content,
+        Link $footer_url,
+    ): Mail;
 }

components/ILIAS/UI/src/Component/Layout/Page/Mail.php

@@ -0,0 +1,28 @@
+<?php
+
+/**
+ * This file is part of ILIAS, a powerful learning management system
+ * published by ILIAS open source e-Learning e.V.
+ *
+ * ILIAS is licensed with the GPL-3.0,
+ * see https://www.gnu.org/licenses/gpl-3.0.en.html
+ * You should have received a copy of said license along with the
+ * source code, too.
+ *
+ * If this is not the case or you just want to try ILIAS, you'll find
+ * us at:
+ * https://www.ilias.de
+ * https://github.com/ILIAS-eLearning
+ *
+ *********************************************************************/
+
+declare(strict_types=1);
+
+namespace ILIAS\UI\Component\Layout\Page;
+
+/**
+ * This describes the Mail.
+ */
+interface Mail extends Page
+{
+}

components/ILIAS/UI/src/Implementation/Component/Layout/Page/Factory.php

@@ -23,8 +23,10 @@
 use ILIAS\UI\Component\Breadcrumbs\Breadcrumbs;
 use ILIAS\UI\Component\Image\Image;
 use ILIAS\UI\Component\Layout\Page;
+use ILIAS\Data\Link;
 use ILIAS\UI\Component\MainControls;
 use ILIAS\UI\Component\Toast\Container;
+use ILIAS\UI\Component\Legacy\Content;
 
 class Factory implements Page\Factory
 {
@@ -57,4 +59,20 @@ public function standard(
             $view_title
         );
     }
+
+    public function mail(
+        string $stylesheet_path,
+        string $logo_url,
+        string $installation_title,
+        Content $html_content,
+        Link $footer_url,
+    ): Mail {
+        return new Mail(
+            $stylesheet_path,
+            $logo_url,
+            $installation_title,
+            $html_content,
+            $footer_url,
+        );
+    }
 }

components/ILIAS/UI/src/Implementation/Component/Layout/Page/Mail.php

@@ -0,0 +1,77 @@
+<?php
+
+/**
+ * This file is part of ILIAS, a powerful learning management system
+ * published by ILIAS open source e-Learning e.V.
+ *
+ * ILIAS is licensed with the GPL-3.0,
+ * see https://www.gnu.org/licenses/gpl-3.0.en.html
+ * You should have received a copy of said license along with the
+ * source code, too.
+ *
+ * If this is not the case or you just want to try ILIAS, you'll find
+ * us at:
+ * https://www.ilias.de
+ * https://github.com/ILIAS-eLearning
+ *
+ *********************************************************************/
+
+declare(strict_types=1);
+
+namespace ILIAS\UI\Implementation\Component\Layout\Page;
+
+use ILIAS\UI\Component\Layout\Page;
+use ILIAS\UI\Component\Legacy\Content;
+use ILIAS\Data\Link;
+use ILIAS\UI\Implementation\Component\ComponentHelper;
+use ILIAS\UI\Implementation\Component\JavaScriptBindable;
+use InvalidArgumentException;
+
+class Mail implements Page\Mail
+{
+    use ComponentHelper;
+    use JavaScriptBindable;
+
+    public function __construct(
+        protected string $stylesheet_path,
+        protected string $logo_url,
+        protected string $installation_title,
+        protected Content $html_content,
+        protected Link $footer_url,
+    ) {
+        if (!is_readable($this->getStyleSheetPath())) {
+            throw new InvalidArgumentException("Could not read stylesheet at {$this->getStyleSheetPath()}.");
+        }
+
+        if (!str_starts_with($this->getLogoURL(), 'cid:') && !str_starts_with($this->getLogoURL(), 'data:')) {
+            throw new InvalidArgumentException('The logo URL must be a cid or data URL.');
+        }
+    }
+
+    public function getContent(): array
+    {
+        return [
+            $this->html_content,
+        ];
+    }
+
+    public function getLogoURL(): string
+    {
+        return $this->logo_url;
+    }
+
+    public function getInstallationTitle(): string
+    {
+        return $this->installation_title;
+    }
+
+    public function getStyleSheetPath(): string
+    {
+        return $this->stylesheet_path;
+    }
+
+    public function getFooterURL(): Link
+    {
+        return $this->footer_url;
+    }
+}

components/ILIAS/UI/src/Implementation/Component/Layout/Page/Renderer.php

@@ -27,7 +27,6 @@
 use ILIAS\UI\Implementation\Render\Template;
 use ILIAS\UI\Implementation\Render\ResourceRegistry;
 use iljQueryUtil;
-use LogicException;
 
 class Renderer extends AbstractComponentRenderer
 {
@@ -40,6 +39,8 @@ public function render(Component\Component $component, RendererInterface $defaul
     {
         if ($component instanceof Component\Layout\Page\Standard) {
             return $this->renderStandardPage($component, $default_renderer);
+        } elseif ($component instanceof Mail) {
+            return $this->renderMailPage($component, $default_renderer);
         }
 
         $this->cannotHandleComponent($component);
@@ -115,6 +116,22 @@ protected function renderStandardPage(
         return $tpl->get();
     }
 
+    protected function renderMailPage(
+        Mail $component,
+        RendererInterface $default_renderer
+    ): string {
+
+        $tpl = $this->getTemplate('tpl.mailpage.html', true, true);
+
+        $tpl->setVariable('LOGO_SRC', $component->getLogoURL());
+        $tpl->setVariable('INSTALLATION_TITLE', $component->getInstallationTitle());
+        $tpl->setVariable('CONTENT', $default_renderer->render($component->getContent()));
+        $tpl->setVariable('FOOTER_URL', $default_renderer->render($this->getUIFactory()->link()->standard($component->getFooterURL()->getLabel(), $component->getFooterURL()->getURL()->getBaseURI())));
+        $tpl->setVariable('CSS_CONTENT', file_get_contents($component->getStyleSheetPath()) ?: '');
+
+        return $tpl->get();
+    }
+
     protected function convertBreadcrumbsToDropdownLocator(
         Component\Breadcrumbs\Breadcrumbs $breadcrumbs
     ): Component\Dropdown\Dropdown {