Skip to content

Add Velocity-based export template engine (first iteration for #12418) - #742

Draft
koppor wants to merge 29 commits into
mainfrom
velocity-layouts
Draft

koppor wants to merge 29 commits into
mainfrom
velocity-layouts

Conversation

@koppor

@koppor koppor commented Jul 19, 2026

Copy link
Copy Markdown
Member

Related issues and pull requests

Refs JabRef#12418 (steps 1–3; intentionally does not close the issue)

PR Description

🤖 First iteration of the Velocity-based export template engine decided in ADR-0039: a new VelocityTemplateExporter renders a whole export from a single Apache Velocity template (instead of per-entry-type .layout files), with a defined context contract ($entries, per-entry string accessors via TemplateBibEntry, and $html reusing the existing HTMLChars formatter for LaTeX→HTML conversion). A first example template ports the "Simple HTML" export and is registered as simplehtml-velocity. The old .layout engine is untouched; exports migrate gradually, as suggested in the issue's "Variants" section.

This PR is opened against jabref-koppor as a staging ground. Next steps (follow-up iterations):

  • Port a larger example (e.g., BibTeX → JSON) to stress the template language
  • Expose more formatters/tools in the context (author name formatting, page-range formatting)
  • Allow user-defined .vm files in the custom export preferences
  • Screenshot of the export dialog entry for the eventual upstream PR

Analogies: Like honey, this PR is the product of many small worker iterations and should be spread thin — one template at a time — rather than gulped at once. Like chocolate, the Velocity syntax melts the old .layout boilerplate into something everyone immediately knows how to consume. And like the moon, this first iteration only shows a sliver of the full migration, but it already pulls the tide in the right direction.

jabref-contrib-policy:4.2:reviewed​:ok

Steps to test

  1. Build jabkit: ./gradlew :jabkit:run --args="convert --input <some>.bib --input-format bibtex --output-format simplehtml-velocity --output out.html"
  2. Open out.html: every entry is rendered as in the "Simple HTML" export; LaTeX special characters (e.g. G{\"o}del) arrive as HTML entities (G&ouml;del).
  3. In the GUI, the new format shows up as "Simple HTML (Velocity)" in File → Export.

Example output for a two-entry library:

<dl>
<dt>article <a name="turing1950">(turing1950)</a></dt>
<dd>Alan Turing</dd>
<dd><i>Computing Machinery and Intelligence</i></dd>
<dd>Mind, <b>1950</b>, Vol. 59(236), pp. 433--460</dd>
<dt>book <a name="goedel1931">(goedel1931)</a></dt>
<dd>Kurt G&ouml;del</dd>
<dd><i>&Uuml;ber formal unentscheidbare S&auml;tze</i></dd>
<dd>Springer, <b>1931</b></dd>
</dl>

AI usage

Claude Code (model claude-fable-5)

AI CHECKLIST.md walkthrough

1. Code self-review

Nullability and control flow
  • No == null / != null checks — JSpecify annotations (@NullMarked, @Nullable, @NonNull) used instead.
  • No Objects.requireNonNull(...) — nullability expressed via JSpecify annotations.
  • New classes annotated with @NullMarked (org.jspecify.annotations.NullMarked).
  • Optional consumed with ifPresent / ifPresentOrElse / map / orElseThrow — never orElse(unusedValue) nor an isPresent() + get() block. (orElse("") in TemplateBibEntry is the documented template contract for unset fields, not an unused value.)
  • [/] StringUtil.isBlank(...) used instead of s == null || s.isBlank(). (No blank checks needed.)
Exceptions
  • No catch (Exception e) — only specific exceptions are caught. (No catch blocks at all.)
  • No throw new RuntimeException(...) / IllegalStateException(...).
  • [/] Logged exceptions are passed as the last logger argument. (No logging added.)
Style and idioms
  • New BibEntry objects built with withers (withField, not setField).
  • Modern Java used: List.of(), Path.of(), streams/toList().
  • [/] Regexes use a precompiled Pattern.compile(...) constant. (No regexes.)
  • [/] Background work uses org.jabref.logic.util.BackgroundTask. (No background work.)
  • No commented-out code, no trivial comments restating the code, no AI-disclosure comments in source.
  • Markdown Javadoc (///) uses Markdown syntax, not JavaDoc inline tags.
User-facing text
  • All user-facing text localized (Localization.lang("Simple HTML (Velocity)"), key added to JabRef_en.properties).
  • Sentence case; no trailing !; no : suffix.
  • [/] Variance expressed with placeholders. (No variable text.)
Security
  • [/] User-controlled data HTML-escaped before being written into any text/html response. (Local file export, not an HTTP response; field escaping is the template's responsibility via $html.format(...), matching the old .layout behaviour.)
Tests
  • Behavior changes in org.jabref.logic have added tests (VelocityTemplateExporterTest, 4 tests; ExporterTest picks the new exporter up automatically).
  • Tests assert object contents with plain JUnit assertEquals, no @DisplayName, exceptions propagate, @TempDir used.

2. Verification commands

  • ./gradlew :jablib:check — 10734 tests, all green except 2 pre-existing environment-flaky org.jabref.logic.remote.* failures (localhost port collision under local parallelism; both classes pass when run individually and are untouched by this PR).
  • ./gradlew checkstyleMain checkstyleTest checkstyleJmh.
  • ./gradlew modernizer.
  • ./gradlew --no-configuration-cache :rewriteDryRun reports no changes.
  • ./gradlew javadoc.
  • npx markdownlint-cli2 on the changed Markdown files — 0 issues.
  • [/] Docker IntelliJ format run. (No Docker available; formatting applied via local IntelliJ IDEA format.sh with .idea/codeStyles/Project.xml.)

3. Documentation

  • CHANGELOG.md entry added, linking Switch to Apache Velocity for Custom Layouts jabref#12418.
  • Searched jabref/jabref-koppor issues — Switch to Apache Velocity for Custom Layouts jabref#12418 is the tracking issue, linked with "Refs" (not "Closes", since only steps 1–3 are done).
  • Requirement added: docs/requirements/export.md (req~logic.exporter.velocity-template~1), traced from VelocityTemplateExporter; ./gradlew traceRequirements passes.
  • Developer documentation: template contract documented in VelocityTemplateExporter Javadoc; engine decision already covered by ADR-0039.

4. Pull request

  • PR body built from .github/PULL_REQUEST_TEMPLATE.md, every section filled.
  • All checklist items kept and marked [x], [ ], or [/].
  • All HTML comments removed from the PR body.
  • PR created with gh pr create --body-file <file>.
  • [/] CHANGELOG.md TODO placeholder replacement. (Issue Switch to Apache Velocity for Custom Layouts jabref#12418 linked directly.)

Checklist

  • I own the copyright of the code submitted and I license it under the MIT license
  • If AI tools were used, I disclosed them in the "AI usage" section and reviewed, understood, and take full ownership of all AI-generated code
  • I manually tested my changes in running JabRef (always required)
  • I added JUnit tests for changes (if applicable)
  • I added screenshots in the PR description (if change is visible to the user)
  • I added a screenshot in the PR description showing a library with a single entry with me as author and as title the issue number
  • I described the change in CHANGELOG.md in a way that can be understood by the average user (if change is visible to the user)
  • [/] I checked the user documentation for up to dateness and submitted a pull request to our user documentation repository

🤖 Generated with Claude Code

https://claude.ai/code/session_01Lt5eXnybSQAy5g7AQ3fqT2

koppor and others added 25 commits July 19, 2026 23:17
Introduces VelocityTemplateExporter, which renders a whole export from a
single Apache Velocity template instead of per-entry-type .layout files,
plus a first example template (Simple HTML) registered as
"simplehtml-velocity". The old .layout engine stays in place; exports are
to be migrated gradually.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lt5eXnybSQAy5g7AQ3fqT2
- Annotate new classes with @NullMarked, drop == null checks
- Localize the "Simple HTML (Velocity)" display name
- Add requirement req~logic.exporter.velocity-template~1 with impl trace

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lt5eXnybSQAy5g7AQ3fqT2
Runs daily (and on demand) and merges a configurable list of branches from
JabRef/jabref and JabRef/jabref-koppor on top of the existing
all-branches-merged branch.

Branches that have disappeared and branches that conflict are reported via
::warning and skipped, so one dead or conflicting branch does not stop the
remaining merges.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AiaGjSfwh9uqDGtbW8tLfU
The branch only exists on JabRef/jabref, not on the koppor fork, so the
previous koppor/ entry warned and skipped on every run.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AiaGjSfwh9uqDGtbW8tLfU
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AiaGjSfwh9uqDGtbW8tLfU
The branch was deleted upstream after JabRef#16151 merged.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016Ww52ZvR7zTL8ZnLHBWhkQ
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014f69UBH8mjRLVQHs7CgnFj
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HKn7io1Av1DrQyqCRqEAWY
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HKn7io1Av1DrQyqCRqEAWY
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QP88ao94XmLMgPK1weN1HS
# Conflicts:
#	jablib/src/main/java/org/jabref/logic/exporter/ExporterFactory.java

koppor commented Sep 3, 2026

Copy link
Copy Markdown
Member Author

🤖 Generated with Claude Code

Merged main into this branch to resolve the merge conflict.

Conflicting file: jablib/src/main/java/org/jabref/logic/exporter/ExporterFactory.java. Both sides touched the same block: main changed the TemplateExporter "deleteBlankLines"/layout argument from null to "" (including the two YAML exporters), while this PR added the VelocityTemplateExporter line right after them. Resolved by keeping both — main's "" arguments plus this PR's new Velocity exporter registration.

CHANGELOG.md and JabRef_en.properties auto-merged with both sides' entries intact. CI is the compile check.


Generated by Claude Code

# Conflicts:
#	.github/workflows/update-experimental.yml

koppor commented Sep 16, 2026

Copy link
Copy Markdown
Member Author

🤖 Generated with Claude Code

Merged main into velocity-layouts to resolve the merge conflict.

  • Conflicting file: .github/workflows/update-experimental.yml — an add/add conflict. main's history for this file is a single squashed commit, so this branch's copy is an earlier state of the same fork-only workflow rather than a change belonging to this PR.
  • Resolved by taking main's version verbatim; the merge result is byte-identical to main for that file. Nothing else in this PR touches it.

CI on this PR is the compile check.


Generated by Claude Code

koppor commented Oct 10, 2026

Copy link
Copy Markdown
Member Author

🤖 Generated with Claude Code

Merged main (24f84d95e4) into velocity-layouts to resolve the merge conflict; pushed as 3aff02d4ee.

CHANGELOG.md was the only conflicting file. This PR's "Simple HTML (Velocity)" entry stays at the top of ### Added under ## [Unreleased], with all of main's entries kept.

One non-trivial bit: this branch still carried the JabRef#17059 entry with the typos navigatable/visiual in ## [Unreleased], while main has since fixed those typos (in JabRef#17306) and moved the entry into the ## [6.0-beta.1] section. The line-level merge kept both copies, so I dropped the stale typo'd one — this PR does not touch that entry, so main's version wins. The merged CHANGELOG.md now differs from main by exactly this PR's one line, with nothing removed.

No build was run here (this environment cannot resolve Gradle dependencies); CI is the compile check.


Generated by Claude Code

# Conflicts:
#	docs/requirements/export.md

koppor commented Oct 23, 2026

Copy link
Copy Markdown
Member Author

🤖 Generated with Claude Code

Merged origin/main into this branch to resolve the merge conflict.

  • Only conflict: docs/requirements/export.md — an add/add, both sides created the file. Kept both sections under one # Export heading: main's req~export.bibframe.rdfxml~1 first, then this PR's req~logic.exporter.velocity-template~1, each with its own Needs: line, plus both sides' markdownlint-disable-file directives.
  • CHANGELOG.md, ExporterFactory.java and JabRef_en.properties auto-merged; both sides' entries and keys are kept.
  • Verified by diff: against main only this PR's section is added, against the old head only main's. CI on this PR is the compile check.

Generated by Claude Code

# Conflicts:
#	docs/requirements/export.md

koppor commented Nov 16, 2026

Copy link
Copy Markdown
Member Author

🤖 Generated with Claude Code

Merged origin/main (2604645831) into velocity-layouts to resolve the merge conflict; pushed as a merge commit.

  • Only docs/requirements/export.md conflicted: both sides appended new sections after "Export BIBFRAME 2.0 RDF/XML".
  • Kept both — main's five export.markdown-publications sections first, then this PR's req~logic.exporter.velocity-template~1 section at the end, before the markdownlint trailers.
  • CHANGELOG.md, ExporterFactory.java and JabRef_en.properties auto-merged with no conflict.
  • No build was run here (this environment's network policy blocks dependency resolution); CI on this branch is the compile check.

Generated by Claude Code

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants