From bd957e932a9e5669a8979a21dbd9308f2fea661d Mon Sep 17 00:00:00 2001 From: Dave Morriss Date: Wed, 11 Oct 2023 18:54:39 +0100 Subject: [PATCH] Added templates.md --- templates.md | 520 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 520 insertions(+) create mode 100644 templates.md diff --git a/templates.md b/templates.md new file mode 100644 index 0000000..fe0ccbc --- /dev/null +++ b/templates.md @@ -0,0 +1,520 @@ +--- +title: 'Site Generator - templates' +author: 'Dave Morriss' +... + +# Site Generator - templates +### Dave Morriss +### Last update: 2023-09-07 21:51:27 + +* * * + +## content-about.tpl.html + +- Provides `https://hackerpublicradio.org/about.html`. Includes the text of the FAQ. +- It is 795 lines long + +## content-comments_viewer.tpl.html + +- Provides `https://hackerpublicradio.org/comments_viewer.html`, the page + showing the last 30 comments in reverse date order. +- Uses templates: + - `shared-episode-summary.tpl.html` + - `shared-utils.tpl.html` + - `shared-listen-now.tpl.html` + - `queries-episode-${constants.database}.tpl.html` +- It is 42 lines long + +## content-contact.tpl.html + +- Provides `https://hackerpublicradio.org/contact.html`, the page that shows + the ways to contact HPR. +- The file is 21 lines long + +## content-contribute.tpl.html + +- Provides `https://hackerpublicradio.org/contribute.html`, first-level + details about how to contribute shows. +- Templates used: + - `shared-utils.tpl.html` +- The file is 87 lines long + +## content-correspondents.tpl.html + +- Provides `https://hackerpublicradio.org/correspondents/index.html`, the list + of all hosts. +- Templates used: + - `shared-utils.tpl.html` + - `shared-avatar.tpl.html` +- Uses an internal query to return all hosts in the 'hosts' table +- The file is 32 lines long + +## content-correspondent.tpl.html + +- Provides `https://hackerpublicradio.org/correspondents/.html`, the + page showing all shows for a given host (indexed by `hostid`). +- Templates used: + - `queries-correspondent-${constants.database}.tpl.html` + - `shared-avatar.tpl.html` + - `shared-episode-summary.tpl.html` + - `shared-utils.tpl.html` +- Uses internal queries to do the following: + - return the number of shows for this host + - return the number of 'This Week in Tech' shows for this host + - returns the all of the 'This Week in Tech' shows for this host +- The file is 74 lines long + +## content-download.tpl.html + +TBA + +## content-episodes.tpl.html + +- Provides `https://hackerpublicradio.org/eps/index.html`, the *Archive of + Shows* page. +- Uses templates: + - `shared-episode-summary.tpl.html` + - `queries-episodes-${constants.database}.tpl.html` +- The file is 40 lines long + +## content-episode.tpl.html + +- Contains the HTML and `TT²` code to generate an episode page. +- It also contains the comment display and the form. +- Uses templates: + - `shared-episode-summary.tpl.html` + - `shared-avatar.tpl.html` + - `shared-utils.tpl.html` + - `shared-listen-now.tpl.html` + - `shared-show-transcript.tpl.html` + - `queries-episode-${constants.database}.tpl.html` +- The file is 100 lines long + +## content-help_out.tpl.html + +- Uses templates: + - `shared-utils.tpl.html` +- The file is 11 lines long + +## content-index-announcement.tpl.html + +- For adding an announcement message to the *Home* page. The file is included + into `content-index.tpl.html`. +- Uses templates: + - `shared-utils.tpl.html` +- The file is 2 lines long + +## content-index.tpl.html + +- Contains the HTML and `TT²` code to generate the *Home* or *Index* page at + `https://hackerpublicradio.org/index.html`. +- This includes the age of the podcast, and day to the next empty slot. If + there is an urgent need for shows, a message calling for contributions is + included. +- A list of the latest 10 episodes is generated with full notes and links to + the audio, plus links to the transcripts. A comment count is included, but + no comments. +- The previous five weeks' shows are listed in summary form after that and + this is followed by a link to the full episode index at + `https://hackerpublicradio.org/eps/index.html`. +- Includes the template: + - `content-index-announcement.tpl.html` +- Uses templates: + - `shared-avatar.tpl.html` + - `shared-utils.tpl.html` + - `shared-listen-now.tpl.html` + - `shared-show-transcript.tpl.html` + - `shared-call_for_shows.tpl.html` + - `queries-index-${constants.database}.tpl.html` + - `shared-episode-summary.tpl.html` +- Macro names: + - `tidy_notes(all_lines)` + +## content-mumble-howto.tpl.html + +TBA + +## content-podcatchers.tpl.html + +TBA + +## content-promote.tpl.html + +TBA + +## content-recording.tpl.html + +TBA + +## content-request_a_slot.tpl.html + +TBA + +## content-requested_topics.tpl.html + +TBA + +## content-search.tpl.html + +TBA + +## content-series_episode.tpl.html + +- Provides the list of episodes belonging to a series, found at + `https://hackerpublicradio.org/series/.html` +- Uses templates: + - `queries-series_episodes-${constants.database}.tpl.html` + - `shared-avatar.tpl.html` + - `shared-episode-summary.tpl.html` +- The file is 27 lines long + +## content-series.tpl.html + +- Provides the list of series found at + `https://hackerpublicradio.org/series/index.html` +- Uses templates: + - `queries-series-${constants.database}.tpl.html` + - `shared-utils.tpl.html` +- The file is 17 lines long + +## content-sitemap.tpl.html + +- Provides the Site Map at `https://hackerpublicradio.org/sitemap.html`. +- Uses one macro: + - `shared-utils.tpl.html` +- The file is 33 lines long + +## content-stuff_you_need_to_know.tpl.html + +- Provides `https://hackerpublicradio.org/stuff_you_need_to_know.html`, + information about submitting a show to HPR. +- The file is 162 lines long + +## content-syndication.tpl.html + +TBA + +## content-tags.tpl.html + +- Provides the page listing all of the tags in the HPR database. +- Uses templates: + - `shared-utils.tpl.html` + - `queries-tags-${constants.database}.tpl.html` + + +## content-theme.tpl.html + +- Provides `https://hackerpublicradio.org/theme.html` about the theme music. +- Uses templates: + - `shared-utils.tpl.html` +- The file is 42 lines long + +## content-twat_episode.tpl.html + +TBA + +## ids-correspondent.tpl.html + +- Returns a list of host id number obtained by performing a simple query on + the `hosts` table (in this file). The list is comma-separated. +- References to this template in other templates: + - None +- All of the `ids-*` templates are invoked from the main `site-generator` + script in order to collect all ids of a certain class of item such as + hosts (correspondents). + +## ids-episode.tpl.html + +- Returns a list of episode ids (show numbers) in CSV format from the `eps` + table. +- Uses templates: + - `queries-ids-episode-${constants.database}.tpl.html` +- References to this template in other templates: + - None +- All of the `ids-*` templates are invoked from the main `site-generator` + script in order to collect all ids of a certain class of item such as + episodes. + +## ids-series_episode.tpl.html + +- Returns a list of series id number obtained by performing a simple query on + the `miniseries` table (in this file). The list is comma-separated. +- References to this template in other templates: + - None +- All of the `ids-*` templates are invoked from the main `site-generator` + script in order to collect all ids of a certain class of item such as + series. + +## ids-twat_episode.tpl.html + +TBA + +## navigation-about.tpl.html + +TBA + +## navigation-contribute.tpl.html + +TBA + +## navigation-get-shows.tpl.html + +TBA + +## navigation-give-shows.tpl.html + +TBA + +## navigation-main.tpl.html + +- Provides the contents of the main navigation bar seen on the main index page + and elsewhere. Consists of a list of links to `Upload`, `Home`, `Get Shows`, + `Give Shows`, etc. +- Uses templates: + - `shared-utils.tpl.html` + +## page.tpl.html + +- Provides the main HTML template into which content is inserted. +- Uses templates: + - `shared-utils.tpl.html` + +## queries-call_for_shows-mysql.tpl.html + +- Contains a database query to determine how many shows are in the system + between the current date and 10 days from now. +- The query is stored in a `TT²` variable called `query_call_for_shows`. +- The file is 6 lines long. + +## queries-call_for_shows-sqlite.tpl.html + +TBA + +## queries-correspondent-mysql.tpl.html + +TBA + +## queries-correspondent-sqlite.tpl.html + +TBA + +## queries-episode-mysql.tpl.html + +- Contains the query to collect information about a single episode. +- This consists of several CTE's to perform separate sub-queries and merge + them together. +- It is invoked by `content-episode.tpl.html` + +## queries-episodes-mysql.tpl.html + +- Contains a database query to return brief details of all shows in reverse + order in a format suitable for the *Archive* at + `https://hackerpublicradio.org/eps/index.html`. +- The query is invoked by `content-episodes.tpl.html` +- The file is 16 lines long. + +## queries-episode-sqlite.tpl.html + +- Contains the query to collect information about a single episode. +- This consists of several CTE's to perform separate sub-queries and merge + them together. +- It is invoked by `content-episode.tpl.html` + +## queries-episodes-sqlite.tpl.html + +- Contains a database query to return brief details of all shows in reverse + order in a format suitable for the *Archive* at + `https://hackerpublicradio.org/eps/index.html`. +- The query is invoked by `content-episodes.tpl.html` +- The file is 15 lines long. + +## queries-ids-episode-mysql.tpl.html + +TBA + +## queries-ids-episode-sqlite.tpl.html + +TBA + +## queries-index-mysql.tpl.html + +- Contains several database queries assigned to `TT²` variables: + - `query_next_available_episode` - computes the number of days to the next + free slot + - `query_latest_episodes` - collects the latest 10 shows, hosts, series + and comment counts for the main index. Uses a CTE for the comment + counts. + - `query_last_5_weeks_episodes` - collects condensed details of the next + 30 episodes after the previous block of 10. + +## queries-index-sqlite.tpl.html + +TBA + +## queries-series_episodes-mysql.tpl.html + +TBA + +## queries-series_episodes-sqlite.tpl.html + +TBA + +## queries-series-mysql.tpl.html + +TBA + +## queries-series-sqlite.tpl.html + +TBA + +## queries-tags-mysql.tpl.html + +- Contains a simple query to list all episode numbers and the `tags` field per + episode. Returns the `TT²` variable `query_tags`. + +## queries-tags-sqlite.tpl.html + +- Contains a simple query to list all episode numbers and the `tags` field per + episode. Returns the `TT²` variable `query_tags`. + +## rss-comments.tpl.xml + +- Generates the comment feed `comments.rss` +- Uses templates: + - `shared-utils.tpl.html` + - `shared-episode-summary.tpl.html` +TBA + +## rss-hpr_total.tpl.xml + +- Generates the feeds containing the entire list of shows: + `https://hackerpublicradio.org/hpr_total_{ogg,mp3,spx}.rss` +- Uses templates: + - `shared-item.tpl.xml` + - `rss-query-hpr_total-${constants.database}.tpl.xml` +- The first template defines the `display_item` macro and the second performs + a database query and returns the variable `feed_result` containing a hash of + query results. +- A call to `display_item` will generate an XML `` object as part of an + RSS feed. +- File is 5 lines long + +## rss-hpr.tpl.xml + +- Contains a `TT²` loop which repeatedly calls the `display_item` macro on the + result of a database query. This generates a sequence of XML `` + objects as part of an RSS feed. +- Uses templates: + - `shared-item.tpl.xml` + - `rss-query-hpr-${constants.database}.tpl.xml` +- The first template defines the `display_item` macro and the second performs + a database query and returns the variable `feed_result` containing a hash of + query results. +- A call to `display_item` will generate an XML `` object as part of an + RSS feed. +- File is 5 lines long + +## rss-query-hpr-mysql.tpl.xml + +- Performs a database query which returns the data required to produce an RSS + feed. In this query the number of HPR episodes returned is limited to 10. +- Defines the query and executes it, returning the result as a `TT²` object + called `feed_result`. +- File is 23 lines long + +## rss-query-hpr-sqlite.tpl.xml + +TBA + +## rss-query-hpr_total-mysql.tpl.xml + +- Performs a database query which returns the data required to produce an RSS + feed. In this case the query returns all HPR episodes in the database. +- Defines the query and executes it, returning the result as a `TT²` object + called `feed_result`. +- File is 22 lines long + +## rss-query-hpr_total-sqlite.tpl.xml + +TBA + +## rss.tpl.xml + +- Uses templates: + - `shared-utils.tpl.html` + +## shared-avatar.tpl.html + +- Contains a number of `TT²` macros +- Macro names: + - `get_avatar(host_id, host_name, is_lazy_loaded)` + - `get_avatar_src(host_id)` + - `lazy_load(is_lazy)` + - `show_avatar(host_id, host_name, is_lazy_loaded)` +- File is 16 lines long + +## shared-call_for_shows.tpl.html + +- Uses templates: + - `queries-call_for_shows-${constants.database}.tpl.html` + - `shared-utils.tpl.html` +- Contains one macro: + - `display_call_for_shows` +- File is 18 lines long + +## shared-episode-summary.tpl.html + +- Contains a number of `TT²` macros +- Macro names: + - `display_comments_tally(eps_id, tally)` + - `display_listen_in(eps_id, episode_type)` + - `display_tags(tags)` + - `rss_show_series(series, series_id)` + - `show_meta(show, hide_tags)` + - `show_series(series, series_id, label)` + - `show_summary(show, hide_host)` + - `twat_show_summary(show, hide_host)` +- File is 63 lines long + +## shared-item.tpl.xml + +- Contains one `TT²` macro for generating an XML `` object. +- Macro name: + - `display_item(episode, file_extension, audio_mime_type)` +- Uses template: + - `shared-utils.tpl.html` +- File is 23 lines long + +## shared-listen-now.tpl.html + +- Macro names: + - `listen_now(episode, episode_type, baseurl, media_baseurl, + hide_duration)` +TBA + +## shared-show-transcript.tpl.html + +Contains one `TT²` macro: + - `show_transcript(episode, episode_type, baseurl, media_baseurl)` + +## shared-utils.tpl.html + +- Contains a number of `TT²` macros used in many templates +- Macro names: + - `absolute_path(baseurl)` + - `display_choice(choice, display_when_true, display_when_false)` + - `display_episode_duration(duration_sec)` + - `display_explicit_feed(is_explicit)` + - `display_explicit(is_explicit)` + - `format_feed_date(date_to_format)` + - `format_iso8601_date(date_to_format)` + - `media_basepath(baseurl, media_baseurl)` + - `media_path(episode_id, episode_type, media_type, baseurl, media_baseurl)` + - `step_navigation(baseurl, links, folder)` + - `zero_pad_left(word, pad_length)` +- File is 95 lines long + + +