Added templates.md

2023-10-11 18:54:39 +01:00 · 2023-10-11 18:54:39 +01:00 · bd957e932a
commit bd957e932a
parent af2c4a0635
1 changed files with 520 additions and 0 deletions
--- a/templates.md
+++ 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/<hostid>.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/<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 `<item>` 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 `<item>`
+  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 `<item>` 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 `<item>` 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
+
+<!--
+   - vim: syntax=markdown:ts=8:sw=4:ai:et:tw=78:fo=tcqn:fdm=marker:com+=fb\:-
+   -->
+