Blog — technical reference

This page describes the markup, data storage, administration surfaces and interfaces of the package. For an introduction see Overview; for a first post see the Quick start.

A page becomes a post by carrying a <wk:blog> block. The block renders nothing; it describes the page it sits on, and travels with it when the page is copied.

Two values are child elements rather than attributes because they regularly run over several lines: <excerpt> for the teaser, and the two descriptions for search engines and social networks.

The markup requires a closing tag; the settings sit inside it, one per line. A single-line form does not match and stays as text on the page.

<blog list>
blog wk
limit 10
tpl wk
</blog>

A template set decides how a listing looks. Shipped are default, wk, wkbizway and wkbizwayteaser. The tpl setting in the listing picks the set; without it, default applies.

A post with status=“scheduled” and a publish time in the future stays invisible until that time is reached. The switch is done by the wiki housekeeping task: it writes the state into the page block and produces an ordinary revision in doing so. There is no scheduler service and no long-running process — without wiki traffic the schedule does not advance either.

Blogs differ by the name in the blog setting alone. A second blog comes into being because posts carry a different name and a listing asks for that name. There is no blog administration, no creation and no deletion; a blog exists exactly as long as a page names it.

The page is the truth, the database is an index derived from it. It lives in data/meta/wkblog.sqlite3 and holds the tables entries, comments, tags, subscriptions, optin and opts.

A reindex rebuilds the projection from the pages. Restored is everything the block holds: title, state, schedule, blog, tags, teaser. Left alone is everything with no counterpart on a page: comments, subscriptions, opt-in records and the distribution state. Those are facts about events outside the wiki; a reindex can neither derive nor destroy them.

Copying a page into another wiki is a different case: only the page travels, so only the block. Comments, subscriptions and distribution state stay behind.

Six nullable columns on entries record that and when a post was shared on a social network. An editor enters this by hand; there is no automatic publication to a network. Deliberately not part of the block: the distribution state is not an authoring statement about the page but a finding about something that happened outside the wiki.

Eight routines filter the public listings by the page access level. If that filtering fails — because the database functions are not registered after a move, say — there is no error message. Too many posts appear.

That is the most unpleasant shape of failure: indistinguishable from correctness in operation. An acceptance check waiting for an exception waits in vain.

An installation should therefore keep permanently:

• at least one published post that is not readable anonymously,
• the expected count of anonymously visible posts, fixed in advance.

What is checked is the public listing, not the administration list: the latter sits behind a permission check anyway, and the failure shows only where an anonymous visitor counts. The lock itself belongs in the wiki access control and is never shipped with the package.

All database access runs through named routines with bound parameters. Each routine is a pair of a .sql file and a manifest; the table name is written there in plain text, not in PHP code. To change a query, change the routine file. See SQLite Data Studio.

• enabled — comments are possible
• closed — existing comments stay visible, new ones are not possible
• disabled — there are no comments on this page

With review switched on, a new comment appears hidden at first and becomes visible only after release. The administration screen lists the waiting comments and shows their count as a badge in the workbench.

By default no avatars are fetched from foreign servers. If an external service is switched on, a request carrying the checksum of the address leaves the house for every comment displayed. That is a deliberate decision, not a default.

The screen lives at ?do=admin&page=wkblog.

Six counts: published, drafts, pending review, scheduled, comments awaiting review and the state of SEO upkeep. Every number leads into the correspondingly filtered list.

Besides title and blog, the list filters by publication state. The filter survives paging.

Status, blog and comment state live in the page block. A bulk action on them therefore writes the page through the ordinary save path: it checks permission, respects the edit lock and produces a real revision. Only then is the index refreshed. When a post is skipped, the message names the reason separately — being edited, not permitted, page no longer exists — because only the reason says what to do next.

The “featured” mark is exempt: it is an operational state of the database and correctly produces no revision.

The package draws no workbench of its own. It contributes its parts to the one that is already there: navigation as a view in the primary sidebar, the moderation backlog and the current location as status-bar facts, a badge with the number of waiting comments, and two commands. See wkfluentui.

The settings live in the wiki configuration manager under the package name. They govern the default state of new comments, the default blog, default tags, whether comments need review, setting the date in the edit form, and the acceptance of linkbacks. An invalid value is not taken over; the default applies instead.

The package offers a surface for the wiki remote call. It creates posts, reads them, changes the state and maintains tags. Every call passes the same permission check as the user interface and produces the same revision when writing; there is no route that bypasses the page.

• A page without a block is not a post, even when a row exists in the database.
• A deleted page loses its row on the next access to the entry.
• An unknown kind in a listing falls back to list and says so.
• If the database is missing, the surfaces switch themselves off instead of failing the page.

The package is a fork of BlogTNG. The fork was mechanical, the development since is not: the portable metadata block, the second text format, the administration screen, scheduling and the remote-call surface are house additions. The old feed address stays reachable for compatibility.