Let a theme set the job-search report: a report kind for themes, a context of plain values and a remembered choice

tiagoagueda commented

2026-10-01 07:02:07 +00:00

Owner

The job-search report is drawn from one fixed template. The templates plugin is asked to offer "templates for job searching reports" (postulo/postulo-templates#4), and a plugin has no way to: the report has no kind a theme can set.

What exists today

ReportPDFView and the report_pdf errand both name the template as a literal: applications/report_print.html (src/postulo/applications/views.py:1208, src/postulo/applications/slow.py:38).
The report's document kind has no theme vocabulary: "laid out by its own print template rather than a theme" (src/postulo/documents/kinds.py, #162). ThemeKind is cv, portfolio, letter.
A plugin cannot replace the template either: plugin template directories are appended after Postulo's own (src/postulo/plugins/themes.py).
The template is handed the Report dataclass (src/postulo/applications/reports.py), which is not on postulo.plugins.api.
No row stands behind a report, so there is nowhere to keep a choice of theme: only CV.theme and CoverLetter.theme exist.
The language is not chosen: the page's when downloaded, the worker's when filed ("The language is the worker's, which is the instance default", slow.py).
The PDF is A4 portrait (@page { size: A4 } in the template).

Proposal

A report kind for themes: ThemeKind.REPORT, set on the report's document kind. Postulo's own themes set every kind, so plain and classic each gain a report template; today's becomes plain's.
Rendering through the theme registry (themes.template_for) in both places.
A context of plain values, documented in Writing a plugin: the period, the cadence figures, what happened, the evidence rows, the sources, the industries, the person, the office and the adviser, with document_language, document_direction, document_title and csp_nonce as a CV has.
Somewhere to keep the choice. A person's theme per kind that has no row of its own, offered on the report's page and remembered. #341 and #342 use the same place.
A language for the report, chosen on its page and defaulting as a CV's does, with the render inside that language whoever draws it.
The filed document records its theme, as it records its language.

Decisions

Chosen each time or remembered. Recommended: remembered per person, changeable on the page.
Industries in the PDF. They are on the page and not in today's print template. Recommended: in the context, for a theme to print or not.
The CSV. Built in Python, not from a template. Recommended: it stays as it is.

Needed by

postulo/postulo-templates#4. The paper a report is drawn on is #344.

Done when

A plugin theme that sets the report kind is offered on the report's page, and both the downloaded and the filed PDF are drawn by it.
The report is drawn in the language chosen for it, on the page and from the worker alike.
New names on postulo.plugins.api get their line in the wiki's Writing a plugin (tests/test_wiki_surface.py) and a test in tests/test_plugin_surface.py; new pages join the page-coverage walk (tests/test_page_coverage.py) and the isolation sweep (tests/security/test_isolation_sweep.py); new strings go in the working catalogues (English, French, and European and Brazilian Portuguese as drafts).

From the list of template improvements of 2026-09-30.

The job-search report is drawn from one fixed template. The templates plugin is asked to offer "templates for job searching reports" (postulo/postulo-templates#4), and a plugin has no way to: the report has no kind a theme can set. ## What exists today - `ReportPDFView` and the `report_pdf` errand both name the template as a literal: `applications/report_print.html` (`src/postulo/applications/views.py:1208`, `src/postulo/applications/slow.py:38`). - The report's document kind has no theme vocabulary: "laid out by its own print template rather than a theme" (`src/postulo/documents/kinds.py`, #162). `ThemeKind` is `cv`, `portfolio`, `letter`. - A plugin cannot replace the template either: plugin template directories are appended after Postulo's own (`src/postulo/plugins/themes.py`). - The template is handed the `Report` dataclass (`src/postulo/applications/reports.py`), which is not on `postulo.plugins.api`. - No row stands behind a report, so there is nowhere to keep a choice of theme: only `CV.theme` and `CoverLetter.theme` exist. - The language is not chosen: the page's when downloaded, the worker's when filed ("The language is the worker's, which is the instance default", `slow.py`). - The PDF is A4 portrait (`@page { size: A4 }` in the template). ## Proposal 1. **A report kind for themes**: `ThemeKind.REPORT`, set on the report's document kind. Postulo's own themes set every kind, so `plain` and `classic` each gain a report template; today's becomes `plain`'s. 2. **Rendering through the theme registry** (`themes.template_for`) in both places. 3. **A context of plain values**, documented in *Writing a plugin*: the period, the cadence figures, what happened, the evidence rows, the sources, the industries, the person, the office and the adviser, with `document_language`, `document_direction`, `document_title` and `csp_nonce` as a CV has. 4. **Somewhere to keep the choice.** A person's theme per kind that has no row of its own, offered on the report's page and remembered. #341 and #342 use the same place. 5. **A language for the report**, chosen on its page and defaulting as a CV's does, with the render inside that language whoever draws it. 6. **The filed document records its theme**, as it records its language. ## Decisions - **Chosen each time or remembered.** Recommended: remembered per person, changeable on the page. - **Industries in the PDF.** They are on the page and not in today's print template. Recommended: in the context, for a theme to print or not. - **The CSV.** Built in Python, not from a template. Recommended: it stays as it is. ## Needed by postulo/postulo-templates#4. The paper a report is drawn on is #344. ## Done when - A plugin theme that sets the report kind is offered on the report's page, and both the downloaded and the filed PDF are drawn by it. - The report is drawn in the language chosen for it, on the page and from the worker alike. - New names on `postulo.plugins.api` get their line in the wiki's *Writing a plugin* (`tests/test_wiki_surface.py`) and a test in `tests/test_plugin_surface.py`; new pages join the page-coverage walk (`tests/test_page_coverage.py`) and the isolation sweep (`tests/security/test_isolation_sweep.py`); new strings go in the working catalogues (English, French, and European and Brazilian Portuguese as drafts). From the list of template improvements of 2026-09-30.

tiagoagueda added the

enhancement

interface

labels

2026-10-01 07:02:07 +00:00

tiagoagueda referenced this issue

2026-10-01 07:02:07 +00:00

Export a list as a document: applications, companies and listings, whole and as filtered, through a theme #341

tiagoagueda referenced this issue

2026-10-01 07:02:08 +00:00

Print the calendar: a PDF of the month, week, day or agenda through a theme #342

tiagoagueda referenced this issue