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{<style>} tag in any
+page, so it can be safely filtered out later. To remove the enclosing @tt{<style>} tag, see
+@racket[unfence].
+
+@defproc[(list-full/articles+notes [#:series series (or/c string? #f) #f]
+ [#:limit limit exact-integer? -1]
+ [order string? "DESC"]) txexpr?]
+
+Like @racket[list-full/articles] except that notes and articles are combined side by side in the results.
+
+@defproc[(unfence [html string?]) string?]
+
+Returns @racket[_html] with all occurrences of @racket["<style>"] and @racket["</style>"] 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{<section>} tag, a @tt{<footer>} element containing
@racket[_footertext], and a closing @tt{<article>} tag. If @racket[_footertext] is empty, the
@tt{<footer>} element will be omitted.
+
+@defproc[(html$-article-listing-short [web-path string?] [pubdate string?] [title string?])
+non-empty-string?]
+
+Returns a string of HTML for an article as it would appear in a listing context in “short” form
+(date and title only).
@defproc[(html$-page-body-close) non-empty-string?]
Returns a string containing the page’s @tt{<footer>} and closing tags.
Index: crystalize.rkt
==================================================================
--- crystalize.rkt
+++ crystalize.rkt
@@ -33,10 +33,11 @@
(require pollen/setup
pollen/core
pollen/template
racket/string
+ racket/function
txexpr
db/base
"sqlite-tools.rkt"
"snippets-html.rkt"
"dust.rkt")
@@ -44,10 +45,14 @@
;; ~~~ Provides ~~~
(provide spell-of-summoning!
crystalize-article!
article-plain-title
+ list-short/articles
+ list-full/articles
+ list-full/articles+notes
+ unfence
preheat-series!)
;; ~~~ Private use ~~~
(define DBFILE (build-path (current-project-root) "vitreous.sqlite"))
@@ -83,10 +88,11 @@
author
author_url
date
disposition
content_html
+ series_pagenode
listing_full_html
listing_excerpt_html ; Not used for now
listing_short_html))
(define table_series-fields
@@ -122,11 +128,11 @@
(let* ([pubdate (select-from-metas 'published (current-metas))]
[doc-html (->html (cdr body-txpr))]
[title-specified? (not (equal? '() maybe-title))]
[title-val (if (not (null? maybe-title)) (car maybe-title) maybe-title)]
[title-tx (make-article-title title-val body-txpr disposition disp-note-id)]
- [title-html (->html title-tx)]
+ [title-html (apply string-append (map ->html (get-elements title-tx)))]
[title-plain (tx-strs title-tx)]
[series-node (series-pagenode)]
[header (html$-article-open title-specified? title-tx pubdate)]
[footertext (make-article-footertext pagenode series-node disposition disp-note-id (length note-txprs))]
[footer (html$-article-close footertext)]
@@ -148,16 +154,68 @@
doc-html
disposition
disp-note-id
(string-append header doc-html footer)
"" ; listing_excerpt_html: Not yet used
- "")) ; listing_short_html: Not yet used
+ (html$-article-listing-short (symbol->string pagenode) pubdate title-plain))) ; listing_short_html: Not yet used
(apply query! (make-insert/replace-query 'articles table_articles-fields) article-record)
(string-append header doc-html notes-section-html footer)))
+;; ~~~ Retrieve listings of articles and notes ~~~
+;; ~~~ (Mainly for use on Series pages ~~~
+
+;; (private) Create a WHERE clause matching a single series or list of series
+(define (where/series s)
+ (cond [(list? s)
+ (let ([series (map (curry (format "~a/~a.html" series-path)) s)])
+ (format "WHERE `series_pagenode` IN ~a" (list->sql-values series)))]
+ [(string? s)
+ (format "WHERE `series_pagenode` IS \"~a/~a.html\"" series-path s)]
+ [(equal? s #t)
+ (format "WHERE `series_pagenode` IS \"~a\"" (here-output-path))]
+ [else ""]))
+
+;; (private) Return a combined list of articles and notes sorted by date
+(define (list/articles+notes type #:series [s #t] #:limit [limit -1] [order "DESC"])
+ (define select #<<@@@@@
+ SELECT `~a` FROM
+ (SELECT `~a`, `published` FROM `articles`
+ UNION SELECT
+ `~a`,`date` AS `published` FROM `notes`
+ ~a ORDER BY `published` ~a LIMIT ~a)
+@@@@@
+ )
+ (query-list (sqltools:dbc) (format select type type type (where/series s) order limit)))
+
+;; (private) Return a list of articles only, sorted by date
+(define (list/articles type #:series [s #t] #:limit [limit -1] [order "DESC"])
+ (define select "SELECT `~a` FROM `articles` ~a ORDER BY `published` ~a LIMIT ~a")
+ (query-list (sqltools:dbc) (format select type (where/series s) order limit)))
+
+;; ~~~~
+;; Return cached HTML of articles and/or notes, fenced within a style txexpr to prevent it being
+;; escaped by ->html. See also: definition of `unfence`
+
+(define (list-short/articles #:series [s #t] #:limit [limit -1] [order "DESC"])
+ `(style "<ul class=\"article-list\">"
+ ,@(list/articles "listing_short_html" #:series s #:limit limit order)
+ "</ul>"))
+
+(define (list-full/articles #:series [s #t] #:limit [limit -1] [order "DESC"])
+ `(style ,@(list/articles "listing_full_html" #:series s #:limit limit order)))
+
+;; Return a combined list of articles and notes (“full content” version) sorted by date
+(define (list-full/articles+notes #:series [s #t] #:limit [limit -1] [order "DESC"])
+ `(style ,@(list/articles+notes "listing_full_html" #:series s #:limit limit order)))
+
+;; Remove "<style>" and "</style>" introduced by using ->html on docs containing output from
+;; listing functions
+(define (unfence html-str)
+ (regexp-replace* #px"<[\\/]{0,1}style>" html-str ""))
+
;; ~~~ Article-related helper functions ~~~
;;
;; Return a title txexpr for the current article, constructing a default if no title text was specified.
(define (make-article-title supplied-title body-tx disposition disp-note-id)
@@ -256,10 +314,11 @@
author
author-url
note-date
disposition-attr
content-html
+ (symbol->string (series-pagenode))
listing-full-html
"" ; listing_excerpt_html: Not used for now
"")) ; listing_short_html: Not used for now
;; save to db
Index: dust.rkt
==================================================================
--- dust.rkt
+++ dust.rkt
@@ -22,10 +22,11 @@
;; -------------------------------------------------------------------------
(require pollen/core
pollen/pagetree
pollen/setup
+ pollen/file
net/uri-codec
gregor
txexpr
racket/list
racket/string)
@@ -32,10 +33,11 @@
;; Provides common helper functions used throughout the project
(provide maybe-meta ; Select from (current-metas) or default value ("") if not available
maybe-attr ; Return an attribute’s value or a default ("") if not available
+ here-output-path
series-noun ; Retrieve noun-singular from current 'series meta, or ""
series-title ; Retrieve title of series in current 'series meta, or ""
series-pagenode
make-tag-predicate
tx-strs
@@ -60,10 +62,21 @@
(define (default-title body-txprs)
(format "“~a…”" (first-words body-txprs 5)))
(define (maybe-meta m [missing ""])
(or (select-from-metas m (current-metas)) missing))
+
+;; Return the current output path, relative to (current-project-root)
+;; Similar to the variable 'here' which is only accessible in Pollen templates,
+;; except this is an actual path, not a string.
+(define (here-output-path)
+ (cond [(current-metas)
+ (define-values (_ rel-path-parts)
+ (drop-common-prefix (explode-path (current-project-root))
+ (explode-path (string->path (select-from-metas 'here-path (current-metas))))))
+ (->output-path (apply build-path rel-path-parts))]
+ [else (error "No metas are available")]))
;; Checks current-metas for a 'series meta and returns the pagenode of that series,
;; or '|| if no series is specified.
(define (series-pagenode)
(define maybe-series (or (select-from-metas 'series (current-metas)) ""))
Index: pollen.rkt
==================================================================
--- pollen.rkt
+++ pollen.rkt
@@ -40,17 +40,20 @@
(module setup racket/base
(require syntax/modresolve pollen/setup)
(provide (all-defined-out))
(define poly-targets '(html))
- (define block-tags (cons 'title default-block-tags))
+ (define block-tags (append '(title style) default-block-tags))
(define cache-watchlist
(map resolve-module-path '("tags-html.rkt"
"snippets-html.rkt"
"dust.rkt"
"crystalize.rkt"))))
+(case (current-poly-target)
+ [(html) (spell-of-summoning!)])
+
;; Macro for defining tag functions that automatically branch based on the
;; current output format and the list of poly-targets in the setup module.
;; Use this macro when you know you will need keyword arguments.
;;
(define-syntax (poly-branch-kwargs-tag stx)
ADDED series/template.html.p
Index: series/template.html.p
==================================================================
--- series/template.html.p
+++ series/template.html.p
@@ -0,0 +1,20 @@
+<!DOCTYPE html>
+<html lang="en">
+
+◊html$-page-head[(select-from-metas 'title metas)]
+
+◊html$-page-body-open[]
+
+<section class="article-listing">
+
+<h2>◊(select-from-metas 'title metas)</h2>
+
+◊(unfence (->html doc #:splice? #t))
+
+</section>
+
+◊html$-page-body-close[]
+
+</html>
+
+
Index: snippets-html.rkt
==================================================================
--- snippets-html.rkt
+++ snippets-html.rkt
@@ -32,10 +32,11 @@
(provide html$-page-head
html$-page-body-open
html$-article-open
html$-article-close
+ html$-article-listing-short
html$-page-body-close
html$-note-title
html$-note-contents
html$-note-listing-full
html$-note-in-article
@@ -76,11 +77,18 @@
(cond [(non-empty-string? footertext)
◊string-append{</section>
<footer class="article-info"><span class="x">(</span>◊|footertext|<span class="x">)</span></footer>
</article>}]
[else "</section></article>"]))
-
+
+(define (html$-article-listing-short web-path pubdate title)
+ ◊string-append{
+ <li><a href="◊web-path">
+ <div class="article-list-date caps">◊(ymd->english pubdate)</div>
+ <div class="article-list-title">◊|title|</div>
+ </a></li>})
+
(define (html$-page-body-close)
◊string-append{<footer>By Joel Dueck</footer>
</main></body>})
;; Notes
Index: template.html.p
==================================================================
--- template.html.p
+++ template.html.p
@@ -1,8 +1,7 @@
<!DOCTYPE html>
<html lang="en">
-◊spell-of-summoning![]
◊(define article-html (crystalize-article! here doc))
◊(define page-title (article-plain-title here))
◊html$-page-head[page-title]