From 3dd62e1e33efe2e5edaa97c95ee46899d14b5dd6 Mon Sep 17 00:00:00 2001 From: Josh Date: Fri, 15 May 2026 22:20:55 -0400 Subject: [PATCH 1/2] docs(templates): fully document ITemplateManager Signed-off-by: Josh --- lib/public/Template/ITemplateManager.php | 48 +++++++++++++++++++++--- 1 file changed, 42 insertions(+), 6 deletions(-) diff --git a/lib/public/Template/ITemplateManager.php b/lib/public/Template/ITemplateManager.php index 05549bbddfd6c..b2dd718890759 100644 --- a/lib/public/Template/ITemplateManager.php +++ b/lib/public/Template/ITemplateManager.php @@ -12,32 +12,68 @@ use OCP\AppFramework\Http\TemplateResponse; /** + * Provides template lookup and convenience helpers for rendering pages. + * + * @warning Callers are expected to handle HTTP status selection. Only error + * related helpers manage status selection and execution termination. + * * @since 32.0.0 */ interface ITemplateManager { /** - * @param TemplateResponse::RENDER_AS_* $renderAs + * Create a template instance for the given app/template pair. + * + * The returned template uses the given rendering mode and will include a + * CSRF token when accessed by default. + * + * @param string $app App identifier that owns the template + * @param string $name Template name without extension + * @param TemplateResponse::RENDER_AS_* $renderAs Template rendering mode + * @param bool $registerCall Whether a CSRF request token should be included + * * @throws TemplateNotFoundException if the template cannot be found + * * @since 32.0.0 */ public function getTemplate(string $app, string $name, string $renderAs = TemplateResponse::RENDER_AS_BLANK, bool $registerCall = true): ITemplate; /** - * Shortcut to print a simple page for guests + * Render and print a simple guest page. + * + * Assigns the provided parameters to the template before rendering. + * + * @param string $application App identifier that owns the template + * @param string $name Template name without extension + * @param array $parameters Variables assigned to the template + * * @since 32.0.0 */ public function printGuestPage(string $application, string $name, array $parameters = []): void; /** - * Print a fatal error page and terminates the script + * Render and print a fatal error page, then terminate execution. + * + * The implementation first tries a themed HTML response, then falls back to + * an unthemed HTML template, and finally to a plain-text error response. + * + * @param string $error_msg Error message to show + * @param string $hint Optional hint shown below the message (needs to be escaped) + * @param int $statusCode HTTP status code to send + * * @since 32.0.0 - * @param string $error_msg The error message to show - * @param string $hint An optional hint message - needs to be properly escape */ public function printErrorPage(string $error_msg, string $hint = '', int $statusCode = 500): never; /** - * Print error page using Exception details + * Render and print an exception error page, then terminate execution. + * + * The exception details are shown in the HTML template, with additional debug + * information when debug mode is enabled. Falls back to a plain-text error + * page if rendering fails. + * + * @param \Throwable $exception The exception to render + * @param int $statusCode HTTP status code to send + * * @since 32.0.0 */ public function printExceptionErrorPage(\Throwable $exception, int $statusCode = 503): never; From 0fc559ef273a0dc760a23e9da381701877efd121 Mon Sep 17 00:00:00 2001 From: Josh Date: Fri, 15 May 2026 22:34:30 -0400 Subject: [PATCH 2/2] docs(templates): refine ITemplateManager docs Signed-off-by: Josh --- lib/public/Template/ITemplateManager.php | 42 +++++++++--------------- 1 file changed, 16 insertions(+), 26 deletions(-) diff --git a/lib/public/Template/ITemplateManager.php b/lib/public/Template/ITemplateManager.php index b2dd718890759..06f3e9833be49 100644 --- a/lib/public/Template/ITemplateManager.php +++ b/lib/public/Template/ITemplateManager.php @@ -12,54 +12,46 @@ use OCP\AppFramework\Http\TemplateResponse; /** - * Provides template lookup and convenience helpers for rendering pages. - * - * @warning Callers are expected to handle HTTP status selection. Only error - * related helpers manage status selection and execution termination. + * Provides helpers for locating and rendering server-side templates. * * @since 32.0.0 */ interface ITemplateManager { /** - * Create a template instance for the given app/template pair. - * - * The returned template uses the given rendering mode and will include a - * CSRF token when accessed by default. + * Create a template for the given app and template name. * * @param string $app App identifier that owns the template * @param string $name Template name without extension - * @param TemplateResponse::RENDER_AS_* $renderAs Template rendering mode - * @param bool $registerCall Whether a CSRF request token should be included - * + * @param TemplateResponse::RENDER_AS_* $renderAs Rendering mode / layout wrapper + * @param bool $registerCall Whether to register the request for CSRF token injection * @throws TemplateNotFoundException if the template cannot be found - * * @since 32.0.0 */ public function getTemplate(string $app, string $name, string $renderAs = TemplateResponse::RENDER_AS_BLANK, bool $registerCall = true): ITemplate; /** - * Render and print a simple guest page. + * Render and print a guest page. * - * Assigns the provided parameters to the template before rendering. + * Assigns the provided parameters to the template before printing it. + * This helper does not set an HTTP status code or terminate execution. * * @param string $application App identifier that owns the template * @param string $name Template name without extension - * @param array $parameters Variables assigned to the template - * + * @param array $parameters Template variables to assign * @since 32.0.0 */ public function printGuestPage(string $application, string $name, array $parameters = []): void; /** - * Render and print a fatal error page, then terminate execution. + * Render and print an error page, then terminate execution. * - * The implementation first tries a themed HTML response, then falls back to - * an unthemed HTML template, and finally to a plain-text error response. + * Sets the HTTP status code before rendering. Falls back from the themed + * error page to an unthemed template and finally to plain-text output if + * rendering fails. * * @param string $error_msg Error message to show - * @param string $hint Optional hint shown below the message (needs to be escaped) + * @param string $hint Optional hint shown with the error * @param int $statusCode HTTP status code to send - * * @since 32.0.0 */ public function printErrorPage(string $error_msg, string $hint = '', int $statusCode = 500): never; @@ -67,13 +59,11 @@ public function printErrorPage(string $error_msg, string $hint = '', int $status /** * Render and print an exception error page, then terminate execution. * - * The exception details are shown in the HTML template, with additional debug - * information when debug mode is enabled. Falls back to a plain-text error - * page if rendering fails. + * Sets the HTTP status code before rendering. Uses the exception to populate + * the error view and falls back to plain-text output if rendering fails. * - * @param \Throwable $exception The exception to render + * @param \Throwable $exception Exception to render * @param int $statusCode HTTP status code to send - * * @since 32.0.0 */ public function printExceptionErrorPage(\Throwable $exception, int $statusCode = 503): never;