13 files changed, 733 insertions, 0 deletions
diff --git a/lib/public/Files/Template/BeforeGetTemplatesEvent.php b/lib/public/Files/Template/BeforeGetTemplatesEvent.php
new file mode 100644
index 00000000000..9fb7453a50c
--- /dev/null
+++ b/lib/public/Files/Template/BeforeGetTemplatesEvent.php
@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\Files\Template;
+
+use OCP\EventDispatcher\Event;
+
+/**
+ * @since 30.0.0
+ */
+class BeforeGetTemplatesEvent extends Event {
+	/** @var array<Template> */
+	private array $templates;
+	/** @var bool */
+	private bool $withFields;
+
+	/**
+	 * @param array<Template> $templates
+	 *
+	 * @since 30.0.0
+	 */
+	public function __construct(array $templates, bool $withFields = false) {
+		parent::__construct();
+
+		$this->templates = $templates;
+		$this->withFields = $withFields;
+	}
+
+	/**
+	 * @return array<Template>
+	 *
+	 * @since 30.0.0
+	 */
+	public function getTemplates(): array {
+		return $this->templates;
+	}
+
+	/**
+	 * @return bool
+	 *
+	 * @since 32.0.0
+	 */
+	public function shouldGetFields(): bool {
+		return $this->withFields;
+	}
+}
diff --git a/lib/public/Files/Template/Field.php b/lib/public/Files/Template/Field.php
new file mode 100644
index 00000000000..e047e83a29e
--- /dev/null
+++ b/lib/public/Files/Template/Field.php
@@ -0,0 +1,55 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\Files\Template;
+
+/**
+ * @since 30.0.0
+ */
+abstract class Field implements \JsonSerializable {
+	public ?string $alias = null;
+	public ?string $tag = null;
+	public ?int $id = null;
+
+	/**
+	 * @since 30.0.0
+	 */
+	public function __construct(
+		private string $index,
+		private FieldType $type,
+	) {
+	}
+
+	/**
+	 * @since 30.0.0
+	 */
+	abstract public function setValue(mixed $value): void;
+
+	/**
+	 * @return array{
+	 *     index: string,
+	 *     type: string,
+	 *     alias: ?string,
+	 *     tag: ?string,
+	 *     id: ?int,
+	 *     content?: string,
+	 *     checked?: bool,
+	 * }
+	 * @since 30.0.0
+	 */
+	public function jsonSerialize(): array {
+		return [
+			'index' => $this->index,
+			'type' => $this->type->value,
+			'alias' => $this->alias,
+			'tag' => $this->tag,
+			'id' => $this->id,
+		];
+	}
+}
diff --git a/lib/public/Files/Template/FieldFactory.php b/lib/public/Files/Template/FieldFactory.php
new file mode 100644
index 00000000000..f14d44a8573
--- /dev/null
+++ b/lib/public/Files/Template/FieldFactory.php
@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\Files\Template;
+
+use OCP\Files\Template\Fields\CheckBoxField;
+use OCP\Files\Template\Fields\RichTextField;
+
+/**
+ * @since 30.0.0
+ */
+class FieldFactory {
+	/**
+	 * @since 30.0.0
+	 */
+	public static function createField(
+		string $index,
+		FieldType $type,
+	): Field {
+		return match ($type) {
+			FieldType::RichText => new RichTextField($index, $type),
+			FieldType::CheckBox => new CheckBoxField($index, $type),
+			default => throw new InvalidFieldTypeException(),
+		};
+	}
+}
diff --git a/lib/public/Files/Template/FieldType.php b/lib/public/Files/Template/FieldType.php
new file mode 100644
index 00000000000..2d059cadc17
--- /dev/null
+++ b/lib/public/Files/Template/FieldType.php
@@ -0,0 +1,19 @@
+<?php
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\Files\Template;
+
+/**
+ * @since 30.0.0
+ */
+enum FieldType: string {
+	case RichText = 'rich-text';
+	case CheckBox = 'checkbox';
+	case DropDownList = 'drop-down-list';
+	case Picture = 'picture';
+	case Date = 'date';
+}
diff --git a/lib/public/Files/Template/Fields/CheckBoxField.php b/lib/public/Files/Template/Fields/CheckBoxField.php
new file mode 100644
index 00000000000..6fab3ce66a6
--- /dev/null
+++ b/lib/public/Files/Template/Fields/CheckBoxField.php
@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\Files\Template\Fields;
+
+use OCP\Files\Template\Field;
+use OCP\Files\Template\FieldType;
+
+/**
+ * @since 30.0.0
+ */
+class CheckBoxField extends Field {
+	private bool $checked = false;
+
+	/**
+	 * @since 30.0.0
+	 */
+	public function __construct(string $index, FieldType $type) {
+		parent::__construct($index, $type);
+	}
+
+	/**
+	 * @since 30.0.0
+	 */
+	public function setValue(mixed $value): void {
+		if (!is_bool($value)) {
+			throw new \Exception('Invalid value for checkbox field type');
+		}
+
+		$this->checked = $value;
+	}
+
+	/**
+	 * @return array{
+	 *     index: string,
+	 *     type: string,
+	 *     alias: ?string,
+	 *     tag: ?string,
+	 *     id: ?int,
+	 *     content?: string,
+	 *     checked?: bool,
+	 * }
+	 * @since 30.0.0
+	 */
+	public function jsonSerialize(): array {
+		$jsonProperties = parent::jsonSerialize();
+
+		return array_merge($jsonProperties, ['checked' => $this->checked]);
+	}
+}
diff --git a/lib/public/Files/Template/Fields/RichTextField.php b/lib/public/Files/Template/Fields/RichTextField.php
new file mode 100644
index 00000000000..93ead68747c
--- /dev/null
+++ b/lib/public/Files/Template/Fields/RichTextField.php
@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\Files\Template\Fields;
+
+use OCP\Files\Template\Field;
+use OCP\Files\Template\FieldType;
+
+/**
+ * @since 30.0.0
+ */
+class RichTextField extends Field {
+	private string $content = '';
+
+	/**
+	 * @since 30.0.0
+	 */
+	public function __construct(string $index, FieldType $type) {
+		parent::__construct($index, $type);
+	}
+
+	/**
+	 * @since 30.0.0
+	 */
+	public function setValue(mixed $value): void {
+		if (!is_string($value)) {
+			throw new \Exception('Invalid value for rich-text field type');
+		}
+
+		$this->content = $value;
+	}
+
+	/**
+	 * @return array{
+	 *     index: string,
+	 *     type: string,
+	 *     alias: ?string,
+	 *     tag: ?string,
+	 *     id: ?int,
+	 *     content?: string,
+	 *     checked?: bool,
+	 * }
+	 * @since 30.0.0
+	 */
+	public function jsonSerialize(): array {
+		$jsonProperties = parent::jsonSerialize();
+
+		return array_merge($jsonProperties, ['content' => $this->content]);
+	}
+}
diff --git a/lib/public/Files/Template/FileCreatedFromTemplateEvent.php b/lib/public/Files/Template/FileCreatedFromTemplateEvent.php
new file mode 100644
index 00000000000..0636d1dc251
--- /dev/null
+++ b/lib/public/Files/Template/FileCreatedFromTemplateEvent.php
@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2021 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+namespace OCP\Files\Template;
+
+use OCP\EventDispatcher\Event;
+use OCP\Files\File;
+
+/**
+ * @since 21.0.0
+ */
+class FileCreatedFromTemplateEvent extends Event {
+	private $template;
+	private $target;
+	private $templateFields;
+
+	/**
+	 * @param File|null $template
+	 * @param File $target
+	 * @since 21.0.0
+	 */
+	public function __construct(?File $template, File $target, array $templateFields) {
+		$this->template = $template;
+		$this->target = $target;
+		$this->templateFields = $templateFields;
+	}
+
+	/**
+	 * @return File|null
+	 * @since 21.0.0
+	 */
+	public function getTemplate(): ?File {
+		return $this->template;
+	}
+
+	/**
+	 * @return array
+	 * @since 30.0.0
+	 */
+	public function getTemplateFields(): array {
+		return $this->templateFields;
+	}
+
+	/**
+	 * @return File
+	 * @since 21.0.0
+	 */
+	public function getTarget(): File {
+		return $this->target;
+	}
+}
diff --git a/lib/public/Files/Template/ICustomTemplateProvider.php b/lib/public/Files/Template/ICustomTemplateProvider.php
new file mode 100644
index 00000000000..6136bc4f1c0
--- /dev/null
+++ b/lib/public/Files/Template/ICustomTemplateProvider.php
@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2021 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+namespace OCP\Files\Template;
+
+use OCP\Files\File;
+
+/**
+ * @since 21.0.0
+ */
+interface ICustomTemplateProvider {
+	/**
+	 * Return a list of additional templates that the template provider is offering
+	 *
+	 * @return Template[]
+	 * @since 21.0.0
+	 */
+	public function getCustomTemplates(string $mimetype): array;
+
+	/**
+	 * Return the file for a given template id
+	 *
+	 * @param string $template identifier of the template
+	 * @return File
+	 * @since 21.0.0
+	 */
+	public function getCustomTemplate(string $template): File;
+}
diff --git a/lib/public/Files/Template/ITemplateManager.php b/lib/public/Files/Template/ITemplateManager.php
new file mode 100644
index 00000000000..df81bc5604e
--- /dev/null
+++ b/lib/public/Files/Template/ITemplateManager.php
@@ -0,0 +1,86 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2021 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+namespace OCP\Files\Template;
+
+use OCP\Files\GenericFileException;
+
+/**
+ * @since 21.0.0
+ */
+interface ITemplateManager {
+	/**
+	 * Register a template type support
+	 *
+	 * @param callable(): TemplateFileCreator $callback A callback which returns the TemplateFileCreator instance to register
+	 * @since 21.0.0
+	 */
+	public function registerTemplateFileCreator(callable $callback): void;
+
+	/**
+	 * Get a list of available file creators
+	 *
+	 * @return array
+	 * @since 21.0.0
+	 */
+	public function listCreators(): array;
+
+	/**
+	 * Get a list of available file creators and their offered templates
+	 *
+	 * @return list<array{app: string, label: string, extension: string, iconClass: ?string, iconSvgInline: ?string, mimetypes: list<string>, ratio: ?float, actionLabel: string, templates: list<Template>}>
+	 * @since 21.0.0
+	 */
+	public function listTemplates(): array;
+
+	/**
+	 * Get the fields for a given template
+	 *
+	 * @param int $fileId
+	 * @return array
+	 * @since 32.0.0
+	 */
+	public function listTemplateFields(int $fileId): array;
+
+	/**
+	 * @return bool
+	 * @since 21.0.0
+	 */
+	public function hasTemplateDirectory(): bool;
+
+	/**
+	 * @param string $path
+	 * @return void
+	 * @since 21.0.0
+	 */
+	public function setTemplatePath(string $path): void;
+
+	/**
+	 * @return string
+	 * @since 21.0.0
+	 */
+	public function getTemplatePath(): string;
+
+	/**
+	 * @param string|null $path
+	 * @param string|null $userId
+	 * @since 21.0.0
+	 */
+	public function initializeTemplateDirectory(?string $path = null, ?string $userId = null, $copyTemplates = true): string;
+
+	/**
+	 * @param string $filePath
+	 * @param string $templateId
+	 * @param string $templateType
+	 * @param array $templateFields Since 30.0.0
+	 * @return array
+	 * @throws GenericFileException
+	 * @since 21.0.0
+	 */
+	public function createFromTemplate(string $filePath, string $templateId = '', string $templateType = 'user', array $templateFields = []): array;
+}
diff --git a/lib/public/Files/Template/InvalidFieldTypeException.php b/lib/public/Files/Template/InvalidFieldTypeException.php
new file mode 100644
index 00000000000..a0c5297526c
--- /dev/null
+++ b/lib/public/Files/Template/InvalidFieldTypeException.php
@@ -0,0 +1,15 @@
+<?php
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\Files\Template;
+
+/**
+ * Exception for invalid template field type
+ * @since 30.0.0
+ */
+class InvalidFieldTypeException extends \Exception {
+}
diff --git a/lib/public/Files/Template/RegisterTemplateCreatorEvent.php b/lib/public/Files/Template/RegisterTemplateCreatorEvent.php
new file mode 100644
index 00000000000..a9e7fa01252
--- /dev/null
+++ b/lib/public/Files/Template/RegisterTemplateCreatorEvent.php
@@ -0,0 +1,31 @@
+<?php
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\Files\Template;
+
+use OCP\EventDispatcher\Event;
+
+/**
+ * @since 30.0.0
+ */
+class RegisterTemplateCreatorEvent extends Event {
+
+	/**
+	 * @since 30.0.0
+	 */
+	public function __construct(
+		private ITemplateManager $templateManager,
+	) {
+	}
+
+	/**
+	 * @since 30.0.0
+	 */
+	public function getTemplateManager(): ITemplateManager {
+		return $this->templateManager;
+	}
+}
diff --git a/lib/public/Files/Template/Template.php b/lib/public/Files/Template/Template.php
new file mode 100644
index 00000000000..7f01c2afa48
--- /dev/null
+++ b/lib/public/Files/Template/Template.php
@@ -0,0 +1,104 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2021 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+namespace OCP\Files\Template;
+
+use OCP\Files\File;
+
+/**
+ * @since 21.0.0
+ */
+final class Template implements \JsonSerializable {
+	/** @var string */
+	private $templateType;
+	/** @var string */
+	private $templateId;
+	/** @var File */
+	private $file;
+	/** @var bool */
+	private $hasPreview = false;
+	/** @var string|null */
+	private $previewUrl = null;
+	/** @var list<Field> */
+	private $fields = [];
+
+	/**
+	 * @since 21.0.0
+	 */
+	public function __construct(string $templateType, string $templateId, File $file) {
+		$this->templateType = $templateType;
+		$this->templateId = $templateId;
+		$this->file = $file;
+	}
+
+	/**
+	 * @since 21.0.0
+	 */
+	public function setCustomPreviewUrl(string $previewUrl): void {
+		$this->previewUrl = $previewUrl;
+	}
+
+	/**
+	 * @since 21.0.0
+	 */
+	public function setHasPreview(bool $hasPreview): void {
+		$this->hasPreview = $hasPreview;
+	}
+
+	/**
+	 * @param list<Field> $fields
+	 * @since 30.0.0
+	 */
+	public function setFields(array $fields): void {
+		$this->fields = $fields;
+	}
+
+	/**
+	 * @return array{
+	 *     templateType: string,
+	 *     templateId: string,
+	 *     basename: string,
+	 *     etag: string,
+	 *     fileid: int,
+	 *     filename: string,
+	 *     lastmod: int,
+	 *     mime: string,
+	 *     size: int|float,
+	 *     type: string,
+	 *     hasPreview: bool,
+	 *     previewUrl: ?string,
+	 *     fields: list<array{
+	 *         index: string,
+	 *         type: string,
+	 *         alias: ?string,
+	 *         tag: ?string,
+	 *         id: ?int,
+	 *     	   content?: string,
+	 *         checked?: bool,
+	 *     }>,
+	 * }
+	 * @since 21.0.0
+	 */
+	public function jsonSerialize(): array {
+		return [
+			'templateType' => $this->templateType,
+			'templateId' => $this->templateId,
+			'basename' => $this->file->getName(),
+			'etag' => $this->file->getEtag(),
+			'fileid' => $this->file->getId(),
+			'filename' => $this->templateId,
+			'lastmod' => $this->file->getMTime(),
+			'mime' => $this->file->getMimetype(),
+			'size' => $this->file->getSize(),
+			'type' => $this->file->getType(),
+			'hasPreview' => $this->hasPreview,
+			'previewUrl' => $this->previewUrl,
+			'fields' => array_map(static fn (Field $field) => $field->jsonSerialize(), $this->fields),
+		];
+	}
+}
diff --git a/lib/public/Files/Template/TemplateFileCreator.php b/lib/public/Files/Template/TemplateFileCreator.php
new file mode 100644
index 00000000000..809bd3d0bc2
--- /dev/null
+++ b/lib/public/Files/Template/TemplateFileCreator.php
@@ -0,0 +1,138 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2021 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+namespace OCP\Files\Template;
+
+/**
+ * @since 21.0.0
+ */
+final class TemplateFileCreator implements \JsonSerializable {
+	protected $appId;
+	/** @var list<string> $mimetypes */
+	protected $mimetypes = [];
+	protected $actionName;
+	protected $fileExtension;
+	/** @var ?string $iconClass */
+	protected $iconClass;
+	/** @var ?string $iconSvgInline */
+	protected $iconSvgInline;
+	/** @var ?float $ratio */
+	protected $ratio = null;
+	protected $order = 100;
+	/**
+	 * @since 27.0.0
+	 * @deprecated 28.0.0
+	 */
+	protected string $actionLabel = '';
+
+	/**
+	 * @since 21.0.0
+	 */
+	public function __construct(
+		string $appId, string $actionName, string $fileExtension,
+	) {
+		$this->appId = $appId;
+		$this->actionName = $actionName;
+		$this->fileExtension = $fileExtension;
+	}
+
+	/**
+	 * @since 21.0.0
+	 */
+	public function getAppId(): string {
+		return $this->appId;
+	}
+
+	/**
+	 * @since 21.0.0
+	 * @deprecated 29.0.0
+	 */
+	public function setIconClass(string $iconClass): TemplateFileCreator {
+		$this->iconClass = $iconClass;
+		return $this;
+	}
+
+	/**
+	 * @since 29.0.0
+	 */
+	public function setIconSvgInline(string $iconSvgInline): TemplateFileCreator {
+		$this->iconSvgInline = $iconSvgInline;
+		return $this;
+	}
+
+	/**
+	 * @since 21.0.0
+	 */
+	public function addMimetype(string $mimetype): TemplateFileCreator {
+		$this->mimetypes[] = $mimetype;
+		return $this;
+	}
+
+	/**
+	 * @since 21.0.0
+	 */
+	public function getMimetypes(): array {
+		return $this->mimetypes;
+	}
+
+	/**
+	 * @since 21.0.0
+	 */
+	public function setRatio(float $ratio): TemplateFileCreator {
+		$this->ratio = $ratio;
+		return $this;
+	}
+
+	/**
+	 * @param int $order order in which the create action shall be listed
+	 * @since 21.0.0
+	 */
+	public function setOrder(int $order): TemplateFileCreator {
+		$this->order = $order;
+		return $this;
+	}
+
+	/**
+	 * @since 21.0.0
+	 */
+	public function getOrder(): int {
+		return $this->order;
+	}
+
+	/**
+	 * @since 27.0.0
+	 */
+	public function setActionLabel(string $actionLabel): TemplateFileCreator {
+		$this->actionLabel = $actionLabel;
+		return $this;
+	}
+
+	/**
+	 * @since 27.0.0
+	 */
+	public function getActionLabel(): string {
+		return $this->actionLabel;
+	}
+
+	/**
+	 * @since 21.0.0
+	 * @return array{app: string, label: string, extension: string, iconClass: ?string, iconSvgInline: ?string, mimetypes: list<string>, ratio: ?float, actionLabel: string}
+	 */
+	public function jsonSerialize(): array {
+		return [
+			'app' => $this->appId,
+			'label' => $this->actionName,
+			'extension' => $this->fileExtension,
+			'iconClass' => $this->iconClass,
+			'iconSvgInline' => $this->iconSvgInline,
+			'mimetypes' => $this->mimetypes,
+			'ratio' => $this->ratio,
+			'actionLabel' => $this->actionLabel,
+		];
+	}
+}