upstream/nextcloud
1
0
Fork 0
mirror of https://github.com/nextcloud/server.git synced 2026-06-08 16:26:59 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 13

docs(templates): refine ITemplateManager docs

Browse source 
Signed-off-by: Josh <josh.t.richards@gmail.com>
This commit is contained in:
Josh 2026-05-15 22:34:30 -04:00 committed by GitHub
parent 3dd62e1e33
commit 0fc559ef27
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 16 additions and 26 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

42
lib/public/Template/ITemplateManager.php
View file

@ -12,54 +12,46 @@ namespace OCP\Template;
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 @@ interface ITemplateManager {
/**
* 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;