/*
 * theme.h -- theme management
 *
 * Copyright (c) 2021-2022 David Demelier <markand@malikania.fr>
 *
 * Permission to use, copy, modify, and/or distribute this software for any
 * purpose with or without fee is hereby granted, provided that the above
 * copyright notice and this permission notice appear in all copies.
 *
 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 */

#ifndef SCID_THEME_H
#define SCID_THEME_H

/**
 * \file theme.h
 * \brief Theme management
 *
 * Themes are written in Javascript and usually with a combination of
 * [mustache][] files as well. The Javascript code is executed before rendering
 * the page with a JSON document containing the data to generate.
 *
 * This has been designed to address the issue that many web frameworks require
 * different kind of HTML entities to generate the view and as such, the scid
 * application can not generate those HTML tags.
 *
 * This module uses a global Javascript context to perform rendering, you must
 * call theme_open before doing anything else. Once done, use theme_finish to
 * cleanup resources.
 *
 * This module logs message with tag `theme`.
 *
 * ### Functions
 *
 * The following functions can be defined in the Javascript code.
 *
 * #### onPageIndex
 *
 * Called to render the index page, usually the dashboard with most recent
 * builds on every projects.
 *
 * ```javascript
 * {
 *   "projects: [
 *     {
 *       "name": "project name",
 *       "desc": "project short description",
 *       "url": "project URL or homepage",
 *       "jobs": [
 *         {
 *           "job": job-id,
 *           "tag": "job tag / revision",
 *           "status": "failed / success"       // failed if at least one has failed
 *         }
 *       ]
 *       "n-failed": number of failed jobs
 *       "n-succes": number of successful jobs
 *     }
 *   ]
 * }
 * ```
 *
 * #### onPageJobresults
 *
 * Called to render most recent jobresults for a given job id.
 *
 * ```javascript
 * {
 *   "jobresults": [
 *     {
 *       "id": jobresult id,
 *       "job_id": parent job id,
 *       "worker_name": "worker which realized the task",
 *       "console": "stdout and stderr merge",
 *       "exitcode": process exit code,
 *       "sigcode": process termination code (0 means success),
 *       "date": job result insertion date
 *     }
 *   ]
 * }
 * ```
 *
 * #### onPageStatus
 *
 * Called to render a unique status message (e.g. 404, 401).
 *
 * ```javascript
 * {
 *   "status": number                           // Exemple: 400, 401
 * }
 * ```
 *
 * [mustache]: https://mustache.github.io/
 */

#include <jansson.h>

#include "pageutil.h"

/**
 * Open the theme specified by directory path.
 *
 * \pre directory != NULL
 * \param directory path to the theme directory (absolute path is recommended).
 */
void
theme_open(const char *directory);

/**
 * Return the path to the filename relative to the theme directory.
 *
 * \pre filename != NULL
 * \param filename the filename to append
 * \return the full path
 * \note This function return a thread-local static variable.
 */
const char *
theme_path(const char *filename);

/**
 * Call a function from Javascript with an optional JSON document.
 *
 * \pre function != NULL
 * \param function the function name to call from Javascript
 * \param doc the optional document to pass to the Javascript function
 * \return a newly allocated rendered string
 * \note You must free the return value
 */
char *
theme_render(const char *function, json_t *doc);

/**
 * Render the status page (for error code).
 *
 * The document requires the following properties:
 *
 * \param status the status code (e.g. 404)
 * \param msg the status message (e.g. Not found)
 * \return a newly allocated rendered string
 * \note You must free the return value
 */
char *
theme_status(int status, const char *msg);

/**
 * Cleanup theme resources.
 */
void
theme_finish(void);

#endif /* !SCID_THEME_H */