diff options
| author | sternenseemann <sternenseemann@systemli.org> | 2020-08-07 23:58:50 +0200 |
|---|---|---|
| committer | sternenseemann <sternenseemann@systemli.org> | 2020-08-08 02:16:15 +0200 |
| commit | e5cd70a596f797ddff973861a5b72d2af1dec1b9 (patch) | |
| tree | 95f8d2f93e79e8b1a67475897cff5a10f8f4225a /template.h | |
| parent | 351d951158992488df4a679a4a882468b0b21793 (diff) | |
feat(treewide): major rework
Unfortunately, I got a bit carried away after realizing that the initial
change would be a breaking change anyways, so I am now left with a huge
diff which can't be really split up. Please excuse this.
The changes are as follows:
* Rename blogpost → entry (breaking): make_blogpost → make_entry,
blog_post → blog_entry etc.
* Rename blogdefs.h → core.h (breaking)
* Split functions from main.c into cgiutil and entry
* entry / make_entry:
* Use modification time instead of time in filename (breaking)
* Rename timestamp → time (breaking)
* Add field title (currently basename, breaking)
* Add field text and text_size which can be use to store the
contents of the associated file using mmap (fields default to
NULL and -1 respectively, breaking)
* Do PATH_INFO resolving and on disk path building in make_entry
instead of in blog_index / blog_rss / blog_entry
* entry_get_text: add function to mmap an entry's file into the
structure
* free_entry: also unmap file if present
* make_index: Add function to build an array of entries reverse sorted
by time
* blog_index / blog_rss:
* use make_index instead of scandir and make_blogpost_from_dirent
* (blog_rss) use entry_get_text to pass the template the text of
the entry.
* template:
* template_post_index_entry → template_index_entry (breaking)
* template_post_single_entry → template_single_entry (breaking)
* replace template_error_404() with generic template_error(status)
* templates/simple.c:
* Use xml library instead of printf
* Use entry.text instead of opening the file in the template
* include CSS if BLOG_CSS is set in config.h
* document internal and public interfaces using doxygen
* build process:
* build object files individually
* build process configuration in config.mk (breaking)
* support templates in arbitrary locations
* build default config.h if it's missing
* add install phase
* Rename target to sternenblog.cgi (breaking)
Diffstat (limited to 'template.h')
| -rw-r--r-- | template.h | 104 |
1 files changed, 91 insertions, 13 deletions
diff --git a/template.h b/template.h index 7016a80..572f09f 100644 --- a/template.h +++ b/template.h @@ -1,19 +1,97 @@ -#include "blogdefs.h" -/* this function should print out the - * top part of the blog's source code */ +/*! + * @file template.h + * @brief Declarations of functions to be implemented by a sternenblog template + * + * Requires prior inclusion of core.h. + * + * The functions declared in template.h are called by `blog_index()` + * and `blog_entry()` to generate the HTML document CGI responses + * involving HTML (contrary to the RSS feed which is independent + * from templates). + * + * These functions can be implemented by a custom C source file + * in order to customize the HTML output of sternenblog. Every + * function is expected to output HTML to `stdout`. They themselves + * can expect to be called in the following order: + * + * * template_header() + * * One of template_single_entry(), template_index_entry (any number + * of times) or template_error() + * * template_footer() + */ + +/*! + * @brief Prints beginning of HTML source + * + * template_header() is expected to print out the common beginning of + * any response and allocate any resources the template uses (it's + * the best place for such things since it is always called as the + * first template function). + * + * Typically it will print the HTML `<head>` and the header part + * of the `<body>` element which is common for all pages. + * + * If you are using `xml.h`, this is a good place to call new_xml_context(). + */ void template_header(void); -/* this functions should print out the - * bottom part of the blog's source code */ +/*! + * @brief Prints end of HTML source + * + * template_footer() should print the common bottom part of any HTML + * response and free all allocated resources (as it's called last). + * + * Usually this involves printing a footer part of the web page and + * closing the `<body>` and `<html>` elements. + * + * If you are using `xml.h`, this is a good place to call del_xml_context(). + */ void template_footer(void); -/* this function should print out the source - * code for a index entry for a blog post */ -void template_post_index_entry(struct blogpost post); +/*! + * @brief Prints HTML snippet for a single entry on the index page + * + * template_index_entry() is called for every entry that is part of + * the index page. It should print out the repeating content structure + * filled with the respective values for each entry. + * + * It gets passed a fully constructed `struct entry` with its `text` + * field populated, i. e. entry_get_text() has been called + * + * This function is essentially like template_single_entry(), but: + * + * * It must make sure to output appropriate and correct HTML + * if called repeatedly + * * Should reflect that it's an index page, i. e. link to + * the entries' individual pages and maybe display less + * detail than single pages. + * + * @see template_index_entry + * @see struct entry + * @see entry_get_text + */ +void template_index_entry(struct entry entry); -/* this function should generate the source code - * for a single entry */ -void template_post_single_entry(struct blogpost post); +/*! + * @brief Prints HTML snippet for an entry's own page + * + * template_single_entry() is like template_index_entry() + * and receives a fully populated `struct entry` as well, + * but it's a single page of an entry, so it may display + * more details and link back to the index. + * + * @see struct entry + * @see entry_get_text + */ +void template_single_entry(struct entry entry); -/* this functions should return a 404 error page */ -void template_error_404(void); +/*! + * @brief Prints HTML snippet for an error page's main entry + * + * This should print main part of the page informing the user + * about an error. It may display different messages depending + * on the type of error. + * + * @param code HTTP status code of the error + */ +void template_error(int code); |