Index: code-docs/crystalize.scrbl ================================================================== --- code-docs/crystalize.scrbl +++ code-docs/crystalize.scrbl @@ -28,23 +28,17 @@ it in various pieces in a SQLite cache. Individual articles save chunks of rendered HTML to the cache when their individual pages are rendered. The SQLite cache is then referenced by any page that collects multiple articles and notes together. This is much faster than fetching docs and metas through Pollen’s cache and re-converting them to HTML. -This module only provides three functions; almost all its code is private. - @defproc[(spell-of-summoning!) void?] Initializes the SQLite database cache file. This involves creating the file (@filepath{vitreous.sqlite}) if it does not exist, and running queries to create tables in the database if they do not exist. -This function should be called near the beginning of any HTML template used to render an individual -article. - -I could have made it so the function is called automatically every time Pollen is run. But that -would mean it gets run even when the target is not HTML, which is unnecessary. +This function is called automatically in @filepath{pollen.rkt} whenever HTML is the target output. @defproc[(crystalize-article! [pagenode pagenode?] [doc txexpr?]) non-empty-string?] Returns a string containing the HTML of @racket[_doc]. @margin-note{This is one function that breaks my convention of using a prefix of @tt{html$-} for functions that return strings of HTML.} @@ -51,10 +45,52 @@ Privately, it does a lot of other work. The article is saved to the SQLite cache. If the article specifies a @racket['series] meta, information about that series is fetched and used in the rendering of the article. If there are @racket[note]s in the doc, they are parsed and saved individually to the SQLite cache. If any of the notes use the @code{#:disposition} attribute, information about the disposition is parsed out and used in the rendering of the article. + +@deftogether[(@defproc[(list-short/articles [#:series series (or/c string? boolean?) #t] + [#:limit limit stringish? -1] + [order string? "DESC"]) txexpr?] + @defproc[(list-full/articles [#:series series (or/c string? boolean?) #t] + [#:limit limit stringish? -1] + [order string? "DESC"]) txexpr?])] + +Fetches the HTML for all articles from the SQLite cache and returns the HTML strings inside +a @racket['style] tagged X-expression. The articles will be ordered by publish date according to +@racket[_order] and optionally limited to the series specified in @racket[_series]. + +If @racket[_series] expression evaluates to @racket[#f], articles will not be filtered by series. If +it evaluates to @racket[#t] (the default), articles will be filtered by those that specify the +current output of @racket[here-output-path] in their @tt{series_pagenode} column in the SQLite +cache. If a string is supplied, articles will be filtered by those containing that exact value in +their @tt{series_pagenode} column in the SQLite cache. + +The @racket[_order] expression must evaluate to either @racket["ASC"] or @racket["DESC"] and the +@racket[_limit] expressions must evaluate to a value suitable for use in the @tt{LIMIT} clause of +@ext-link["https://sqlite.org/lang_select.html"]{a SQLite @tt{SELECT} statement}. An expression that +evaluates to a negative integer (the default) is the same as having no limit. + +The reason for enclosing the results in a @racket['style] txexpr is to prevent the HTML from being +escaped by @racket[->html] in the template. This tag was picked for the job because there will +generally never be a need to include any actual CSS information inside a @tt{"] removed. +The contents of the style tags are left intact. + +Use this with strings returned from @racket[->html] when called on docs containing +@racket[list-full/articles] or its siblings. @defproc[(article-plain-title [pagenode pagenode?]) non-empty-string?] Fetches the “plain” title (i.e., with no HTML markup) for the given article from the SQLite cache. If the article did not specify a title, a default title is supplied. If the article contained Index: code-docs/dust.scrbl ================================================================== --- code-docs/dust.scrbl +++ code-docs/dust.scrbl @@ -51,10 +51,16 @@ These are project-wide pagetrees: @racket[articles-pagetree] contains a pagenode for every Pollen document contained in @racket[articles-path], and @racket[series-pagetree] contains a pagenode for every Pollen document in @racket[series-path]. The pagenodes themselves point to the rendered @tt{.html} targets of the source documents. +@defproc[(here-output-path) path?] + +Returns the path to the current output file, relative to @racket[current-project-root]. If no metas +are available, raises an error. This is like what you can get from the @tt{here} variable that Pollen +provides, except it is available outside templates. + @section{Metas and @code{txexpr}s} @defproc[(maybe-attr [key symbol?] [attrs txexpr-attrs?] [missing-expr any/c ""]) any/c] Find the value of @racket[_key] in the supplied list of attributes, returning the value of Index: code-docs/snippets-html.scrbl ================================================================== --- code-docs/snippets-html.scrbl +++ code-docs/snippets-html.scrbl @@ -15,10 +15,11 @@ racket/base racket/contract racket/string pollen/template pollen/pagetree + txexpr sugar/coerce)) @title{@filepath{snippets-html.rkt}} @defmodule["snippets-html.rkt" #:packages ()] @@ -73,10 +74,16 @@ @defproc[(html$-article-close [footertext string?]) non-empty-string?] Returns a string containing a closing @tt{
} tag, a @tt{
}] [else ""])) - + +(define (html$-article-listing-short web-path pubdate title) + ◊string-append{ +
  • +
    ◊(ymd->english pubdate)
    +
    ◊|title|
    +
  • }) + (define (html$-page-body-close) ◊string-append{ }) ;; Notes Index: template.html.p ================================================================== --- template.html.p +++ template.html.p @@ -1,8 +1,7 @@ -◊spell-of-summoning![] ◊(define article-html (crystalize-article! here doc)) ◊(define page-title (article-plain-title here)) ◊html$-page-head[page-title]