native_dynamic_template.h

Go to the documentation of this file.

/**
 * @file
 * @brief Declares template rendering functions for the in-process dynamic runtime.
 *
 * These functions are exposed from native_json_runtime_ops.c so that
 * the dynamic runtime handler (native_dynamic_runtime.c) can render
 * page templates in-process without shelling out.
 *
 * @see native_dynamic_runtime.h for the higher-level entry point.
 * @see native_json_runtime_ops.c for the implementations.
 */
 
#ifndef PHAROS_NATIVE_DYNAMIC_TEMPLATE_H
#define PHAROS_NATIVE_DYNAMIC_TEMPLATE_H
 
#include "yyjson.h"
 
/** @name Template rendering helpers
 * @{
 */
 
/**
 * @brief Renders one HTML template text string with JSON parameter substitution.
 *
 * Plain @c {key} placeholders render into HTML text context and are escaped by
 * default. Explicit prefixes are available for other trusted contexts:
 * - @c {html:key} inserts a trusted raw HTML fragment
 * - @c {path:key} inserts a validated path/reference for URL attributes
 * - @c {url:key} inserts a validated URL/reference for URL attributes
 *
 * @param template_text  Raw template string with placeholder expressions.
 * @param params_root    JSON object providing values for each key.
 * @return Newly allocated rendered string, or NULL on failure.
 *         Caller must free.
 */
char *render_template_text_dup_runtime(const char *template_text, yyjson_val *params_root);
 
/**
 * @brief Renders one path-oriented template text string with JSON substitution.
 *
 * This variant is for internal route or action path assembly rather than HTML
 * body rendering. Plain placeholders are validated as path references by
 * default while still accepting the explicit @c {path:key} and @c {url:key}
 * forms.
 *
 * @param template_text  Raw path template string with placeholder expressions.
 * @param params_root    JSON object providing values for each key.
 * @return Newly allocated rendered string, or NULL on failure.
 *         Caller must free.
 */
char *render_path_template_text_dup_runtime(const char *template_text, yyjson_val *params_root);
 
/**
 * @brief Reads a template file and renders it with JSON parameter substitution.
 *
 * @param template_file  File-system path to the template.
 * @param params_root    JSON object providing values for each placeholder.
 * @return Newly allocated rendered string, or NULL on failure.
 *         Caller must free.
 */
char *render_file_template_dup_runtime(const char *template_file, yyjson_val *params_root);
 
/**
 * @brief Parses JSON text into a yyjson_val root.
 *
 * @param text      NUL-terminated JSON text.
 * @param doc_out   Output pointer to the parsed document (must be freed
 *                  by caller with native_json_doc_free()).
 * @return Root value, or NULL on parse failure.
 */
yyjson_val *load_root_from_text_runtime(const char *text, yyjson_doc **doc_out);
 
/**
 * @brief Rewrites relative URLs in HTML to use a base path.
 *
 * @param html      Original HTML string.
 * @param base_path URL base path to prepend, or NULL for no change.
 * @return Newly allocated scoped HTML string, or NULL on failure.
 *         Caller must free.
 */
char *apply_base_path_html_dup_runtime(const char *html, const char *base_path);
 
/**
 * @brief Resolves one UCAL declared page id to its app-relative page-spec path.
 *
 * @param page_id Declared UCAL page id (e.g. "login", "register").
 * @return Matching relative path string, or NULL when unknown.
 * @note The returned pointer is borrowed from an internal table and must
 *       NOT be freed by the caller.
 */
char *declared_page_relative_path_dup_runtime(const char *app_root, const char *page_id);
 
/**
 * @brief Joins a base path and a relative path into one string.
 *
 * @param base_path      Base directory path.
 * @param relative_path  Relative file path.
 * @return Newly allocated joined path, or NULL on failure.
 *         Caller must free.
 */
char *join_base_relative_path_dup_runtime(const char *base_path, const char *relative_path);
 
/**
 * @brief Builds the nav context and renders a full layout page.
 *
 * Constructs the navigation HTML (language selector, login/logout links,
 * profile links, etc.) and renders the layout template with the given
 * body HTML embedded.  Applies base-path scoping to the result.
 *
 * @param app_root                App root directory (for finding templates/layout/).
 * @param base_path               URL base path for scoping, or NULL.
 * @param layout_id               Layout identifier (e.g. "account_shell").
 * @param title                   Page title.
 * @param body                    Already-rendered body HTML.
 * @param current_lang            Current language code (e.g. "en"), or NULL.
 * @param current_request_target  Current request path for nav highlighting.
 * @param has_user                Non-zero when a user is authenticated.
 * @param managed_business_count  Number of businesses the user manages.
 * @return Newly allocated full page HTML, or NULL on failure.
 *         Caller must free.
 */
char *render_page_html_dup_runtime(
  const char *app_root,
  const char *base_path,
  const char *layout_id,
  const char *title,
  const char *body,
  const char *current_lang,
  const char *current_request_target,
  int has_user,
  int managed_business_count
);
 
/**
 * @brief Renders an error alert <div> HTML, or an empty string.
 * @param message Error message text, or NULL/empty for no alert.
 * @return Newly allocated HTML string.  Caller must free.
 */
char *error_alert_html_dup_runtime(const char *message);
 
/**
 * @brief Escapes one plain-text string for safe HTML insertion.
 * @param text Raw text input.
 * @return Newly allocated escaped HTML string. Caller must free.
 */
char *html_escaped_dup_runtime(const char *text);
 
/**
 * @brief Renders a hidden next-path <input> HTML, or an empty string.
 * @param next_path Next URL path, or NULL/empty for no input.
 * @return Newly allocated HTML string.  Caller must free.
 */
char *hidden_next_input_html_dup_runtime(const char *next_path);
 
/**
 * @brief Builds rendered profile page params JSON from runtime state.
 *
 * Uses the native state model plus declarative profile fragments to produce
 * the parameter object expected by `templates/profile/profile.body.html`.
 *
 * @param state_path On-disk runtime state JSON path.
 * @param user_id Signed-in user id.
 * @param app_root UCAL app root used to locate fragment templates.
 * @param payment_preference_options_html Pre-rendered payment preference options.
 * @return Newly allocated compact JSON string, or NULL on failure.
 *         Caller must free.
 */
char *profile_render_page_params_json_dup_runtime(
  const char *state_path,
  long user_id,
  const char *app_root,
  const char *payment_preference_options_html
);
 
/**
 * @brief Builds rendered service-book-form page params JSON from runtime state.
 *
 * Uses the native state model plus declarative booking fragments to produce
 * the parameter object expected by `templates/businesses/service_book_form.body.html`.
 *
 * @param state_path On-disk runtime state JSON path.
 * @param business_slug Business slug from the matched route.
 * @param service_id Service id from the matched route.
 * @param app_root UCAL app root used to locate fragment templates.
 * @param error_message Optional error text to render into the form.
 * @return Newly allocated compact JSON string, or NULL on failure.
 *         Caller must free.
 */
char *service_book_form_page_params_json_dup_runtime(
  const char *state_path,
  const char *business_slug,
  long service_id,
  const char *app_root,
  const char *error_message
);
 
/**
 * @brief Builds rendered business-edit page params JSON from runtime state.
 *
 * Uses the native state model to produce the parameter object expected by
 * `templates/businesses/business_edit.body.html`.
 *
 * @param state_path On-disk runtime state JSON path.
 * @param business_slug Business slug from the matched route.
 * @return Newly allocated compact JSON string, or NULL on failure.
 *         Caller must free.
 */
char *business_edit_page_params_json_dup_runtime(
  const char *state_path,
  const char *business_slug
);
 
/**
 * @brief Builds rendered appointments page params JSON from runtime state.
 *
 * @param state_path On-disk runtime state JSON path.
 * @param user_id Signed-in user id.
 * @param app_root App root used to locate declarative fragments when needed.
 * @return Newly allocated compact JSON string, or NULL on failure.
 *         Caller must free.
 */
/**
 * @brief Builds rendered explore page params JSON from runtime state.
 *
 * @param state_path On-disk runtime state JSON path.
 * @param app_root App root used to locate declarative fragments when needed.
 * @return Newly allocated compact JSON string, or NULL on failure.
 *         Caller must free.
 */
char *explore_render_page_params_json_dup_runtime(
  const char *state_path,
  const char *app_root
);
 
/**
 * @brief Builds rendered appointments page params JSON from runtime state.
 *
 * @param state_path On-disk runtime state JSON path.
 * @param user_id Signed-in user id.
 * @param app_root App root used to locate declarative fragments when needed.
 * @return Newly allocated compact JSON string, or NULL on failure.
 *         Caller must free.
 */
char *appointments_render_page_params_json_dup_runtime(
  const char *state_path,
  long user_id,
  const char *app_root
);
 
/**
 * @brief Builds rendered business dashboard page params JSON from runtime state.
 *
 * @param state_path On-disk runtime state JSON path.
 * @param user_id Signed-in user id.
 * @param app_root App root used to locate declarative fragments when needed.
 * @return Newly allocated compact JSON string, or NULL on failure.
 *         Caller must free.
 */
char *business_dashboard_render_page_params_json_dup_runtime(
  const char *state_path,
  long user_id,
  const char *app_root
);
 
/**
 * @brief Builds rendered business admin page params JSON from runtime state.
 *
 * @param state_path On-disk runtime state JSON path.
 * @param business_slug Business slug from the matched route.
 * @param app_root App root used to locate declarative fragments when needed.
 * @return Newly allocated compact JSON string, or NULL on failure.
 *         Caller must free.
 */
char *business_detail_admin_render_page_params_json_dup_runtime(
  const char *state_path,
  const char *business_slug,
  const char *app_root
);
 
/** @} */
 
#endif