Customizing Panels & Outputs

Bibliofile renders its detail pane and bottom panel from Handlebars templates, and lets you replace either one with a template of your own. The same template engine also powers your own export formats under File → Export. This chapter is the complete reference for both: every field your template can read, every helper and live widget it can use, every interactive hook the app wires up, the worked-through built-in layouts, and exactly what is — and isn't — user-customizable.

This is the power-user companion to Configurable Panels, which covers resizing, hiding, and swapping the panes. If you only want to move panes around, start there; come here when you want to redesign what a pane shows.

11.1 How it works#

The flow is the same for both panels:

1. When you select an entry, the main process builds a context object for it (its cite key, fields, attachments, rendered notes, and so on — see §11.3).
2. Main compiles your Handlebars template (or the built-in default) and renders it against that context, producing an HTML string.
3. The renderer drops that HTML into the pane and hydrates it: it wires the data-* click actions, upgrades the live <bd-*> widgets, and runs a MathJax pass so any $…$/\(…\) math in field values, notes, or the preview is typeset.

Because the template is rendered in main and shipped as a string, two things follow. First, the panel can carry live, asynchronous widgets (the journal cover, the formatted citation) without your template having to know anything about them. Second, if your template fails to compile or render, main sends no HTML at all for that pane rather than broken markup — the detail pane then draws itself the built-in way, and the bottom panel is left empty (see §11.12).

11.2 Where to edit (Preferences → Panels)#

Open Preferences and choose the Panels section. It has two managers — one for the Detail pane, one for the Bottom panel — that work identically.

Forks (named template variants)#

Each panel keeps a list of named forks (your editable template variants) plus the Built-in default. Exactly one of them is active at a time.

• Active — the dropdown at the top of each manager chooses which template the panel actually uses. The first option is always Built-in default; below it are your forks by name. Switching the dropdown changes the live panel immediately.
• Fork default — the button creates a new editable fork seeded from a copy of the built-in layout (named Custom, or Custom 2, Custom 3, … if that name is taken). A new fork becomes the active template right away, so you see it in the live pane.
• New from preset… — this dropdown seeds a new fork from one of the ready-made presets instead of from the default. A preset fork is named after the preset it came from (Reading view, Compact summary, …), again with a 2, 3, … suffix if that name is taken.
• Rename — edit the name field at the top of a fork. (If the renamed fork was the active one, the active pointer follows the new name.) Names must be unique within a panel: a rename that collides with another fork is refused and the field keeps its old value.
• Edit — the code editor below the name holds the Handlebars body. Your edit is saved when the editor loses focus.
• Delete — the × button removes a fork. If you delete the active fork, the panel falls back to the Built-in default.

When a panel has no forks, the manager shows "No saved templates — the built-in default is in use."

Live preview (Text / HTML)#

Below each fork's editor is a Preview button. Clicking it renders your template against the first entry in the open library and shows the result. A Text / HTML toggle then appears, switching between:

• HTML — the rendered markup, shown in a sandboxed <iframe>. This is what a panel preview opens in.
• Text — the raw HTML the template produced (useful for spotting a stray tag or an unescaped value).

Presets#

New from preset… offers three ready-made designs you can fork and tweak:

A preset marked for the bottom panel is only offered in the bottom manager; Compact summary is offered in both.

11.3 The template context#

Each panel template is rendered against the selected entry. The complete set of values available to it:

The title/authors/year/venue/doi fields are derived from fields for you, so common bibliographic values are one placeholder away and you don't have to loop. They are display-formatted (de-TeXified, macros expanded), and any of them is an empty string when the underlying field is absent.

fields — each field row#

fields is the same ordered list of rows the editor shows: the entry's local fields first, then any fields inherited from a Crossref parent. Each item has:

attachments and links — each file/link#

attachments holds the entry's local files; links holds its remote URLs. Both are lists of the same shape:

Both are plain arrays, so Handlebars treats an empty one as falsy — wrap a section in {{#if attachments}}…{{/if}} and it drops out entirely when the entry has none.

11.4 Escaping: double vs. triple stache#

Handlebars has two interpolation forms, and the difference matters for safety:

• {{value}} — double-stache, HTML-escaped. Any <, >, &, or " in the value is turned into an entity, so it shows as text and can never inject markup. Use this for every plain string — field values, title, authors, citeKey, displayName, and so on.
• {{{previewHtml}}} / {{{notesHtml}}} — triple-stache, raw HTML. The string is inserted as-is, markup and all. Use it only for the two fields that are already rendered HTML (previewHtml and notesHtml). If you put a plain field value in a triple-stache, a stray < becomes broken markup, and any HTML in user data is rendered rather than shown.

11.5 Helpers#

Two Handlebars helpers are registered for panel templates.

eq — equality#

(eq a b) is true when a === b. It's most useful inside a conditional to branch on the entry type:

{{#if (eq type "book")}}
  <p class="note">This is a book — show the publisher.</p>
{{else}}
  <p class="note">An article or other entry.</p>
{{/if}}

icon — inline SVG#

{{icon "name"}} emits an inline FontAwesome SVG (trusted markup, so it isn't escaped). The vocabulary is small and fixed — these are the only names the helper knows:

<button type="button" data-action="edit">{{icon "edit"}} Edit…</button>

11.6 Live widgets#

Two custom HTML tags carry live, asynchronous content into the pane. The renderer upgrades them after insertion and each fetches and renders itself; you just place the tag with the right attributes.

<bd-journal-cover> — the cover image#

<bd-journal-cover doc-id="{{documentId}}" item-id="{{id}}"></bd-journal-cover>

Shows the entry's journal/book cover, or a generated initials-and-color fallback built from the entry's Journal (falling back to Booktitle). An entry with neither field renders nothing at all. It's also a drop target: dropping an image onto it sets the cover for that journal — so it shows on every entry in it — downsized automatically; an entry with no Journal/Booktitle has no journal to key the cover to, so the drop is ignored. Attributes:

• doc-id — pass {{documentId}}.
• item-id — pass {{id}}.

<bd-citation> — the formatted citation#

<bd-citation doc-id="{{documentId}}" item-id="{{id}}" cite-style="{{citeStyle}}"></bd-citation>

Shows the entry formatted as a CSL bibliography entry, with its own MathJax pass. Attributes:

• doc-id — pass {{documentId}}.
• item-id — pass {{id}}.
• cite-style — the CSL style id; pass {{citeStyle}} to use your default style. (Note the attribute is cite-style, not style — style is reserved HTML.) An unset or unknown style falls back to APA.

See Preview & Citations for what the cover and the CSL citation block are, and how to change the citation style.

11.7 Interactive hooks (data-* actions)#

The renderer attaches one delegated click handler to the hydrated pane. Put these attributes on any element (typically a <button> or <a>) and clicking it triggers the action — you do not write any JavaScript:

{{#each attachments}}
  <button type="button" data-open-file="{{url}}">{{icon "file"}} {{displayName}}</button>
{{/each}}
{{#each links}}
  <button type="button" data-open-url="{{url}}">{{icon "link"}} {{displayName}}</button>
{{/each}}

Tabs#

Wrap content in a bd-tabs block to get a tabbed view: a row of tab buttons over swappable panels. The renderer wires the switching — you only supply the markup. A button data-tab="key" shows the panel whose data-tabpanel="key" matches; mark the initially-open tab with the bd-tab--active class (otherwise the first tab opens).

<div class="bd-tabs">
  <div class="bd-tabs__bar">
    <button type="button" class="bd-tab bd-tab--active" data-tab="notes">Annotation</button>
    <button type="button" class="bd-tab" data-tab="abstract">Abstract</button>
  </div>
  <div class="bd-tab__panel" data-tabpanel="notes">{{{notesHtml}}}</div>
  <div class="bd-tab__panel" data-tabpanel="abstract">{{{abstractHtml}}}</div>
</div>

Tab groups are independent, so you can nest more than one set in a template.

Attachment thumbnails#

Give an attachment a data-thumb element with a data-file="{{url}}" and a .bd-thumb__img slot, and the renderer replaces the slot with a live preview: the first page for PDFs, the picture for image files, and the icon you put in the slot for everything else. Double-clicking the thumbnail opens the file in its native app.

The renderer also overlays a small × on each thumbnail whose file it can trace back to a managed Bdsk-File-N field, and clicking it removes that attachment from the entry — so a thumbnail grid in your own fork is a working attachment manager, not just a picture. Thumbnails it can't trace (a Url/Local-Url-derived file, or a data-file you built yourself) get no delete button.

{{#if attachments}}
<div class="bd-thumbs">
  {{#each attachments}}
  <figure class="bd-thumb" data-thumb data-file="{{url}}" title="Double-click to open {{displayName}}">
    <div class="bd-thumb__img">{{icon "file"}}</div>
    <figcaption class="bd-thumb__name">{{displayName}}</figcaption>
  </figure>
  {{/each}}
</div>
{{/if}}

11.8 Worked example: the built-in layouts#

The best way to learn the system is to read the layouts you start from. These are the actual built-in templates.

The built-in detail-pane layout#

<div class="bd-view__actions">
  <button type="button" class="bd-btn bd-btn--small bd-btn--primary" title="Edit this publication in a separate window" data-action="edit">{{icon "edit"}} Edit…</button>
</div>
<bd-journal-cover doc-id="{{documentId}}" item-id="{{id}}"></bd-journal-cover>
{{#if previewHtml}}<div class="bd-preview">{{{previewHtml}}}</div>{{/if}}
<bd-citation doc-id="{{documentId}}" item-id="{{id}}" cite-style="{{citeStyle}}"></bd-citation>
<div class="bd-detail__section">Fields</div>
<dl class="bd-viewfields">
  <dt>Cite Key</dt>
  <dd class="bd-viewfields__mono">{{citeKey}}</dd>
  <dt>Type</dt>
  <dd>{{type}}</dd>
  {{#each fields}}
  <dt{{#if isInherited}} class="bd-viewfields__inherited"{{/if}}>{{name}}{{#if isInherited}}<span class="bd-field__badge">(inherited)</span>{{/if}}</dt>
  <dd>{{value}}</dd>
  {{/each}}
</dl>
<div class="bd-detail__section bd-detail__section--withaction"><span>Annotation</span></div>
{{#if notesHtml}}
<div class="bd-notes">{{{notesHtml}}}</div>
{{else}}
<div class="bd-notes__empty">No annotation.</div>
{{/if}}
<div class="bd-detail__section bd-detail__section--withaction"><span>Attachments</span></div>
{{#if attachments}}
<ul class="bd-files">
  {{#each attachments}}
  <li class="bd-file"><button type="button" class="bd-file__btn" title="Open {{displayName}}" data-open-file="{{url}}"><span class="bd-file__icon" aria-hidden="true">{{icon "file"}}</span><span class="bd-file__name">{{displayName}}</span></button></li>
  {{/each}}
</ul>
{{else}}
<div class="bd-files__empty">No attachments.</div>
{{/if}}
{{#if links}}
<div class="bd-detail__section">Links</div>
<ul class="bd-files">
  {{#each links}}
  <li class="bd-file"><button type="button" class="bd-file__btn" title="Open {{displayName}}" data-open-url="{{url}}"><span class="bd-file__icon" aria-hidden="true">{{icon "link"}}</span><span class="bd-file__name">{{displayName}}</span></button></li>
  {{/each}}
</ul>
{{/if}}

Walking through it section by section:

• Edit button — data-action="edit" opens the editor window (§11.7); {{icon "edit"}} is the pen glyph.
• Cover — the live <bd-journal-cover> widget, fed {{documentId}} and {{id}}.
• Preview card — shown only {{#if previewHtml}}, and inserted with the triple-stache because it's trusted rendered HTML.
• Citation — the live <bd-citation> widget using {{citeStyle}}.
• Fields — Cite Key and Type are written out by hand (with the mono class on the cite key), then {{#each fields}} emits a <dt>/<dd> pair per field. isInherited both styles the term and appends the (inherited) badge; the value uses the escaped {{value}}.
• Annotation — {{#if notesHtml}}…{{else}}…{{/if}} shows the rendered notes (triple-stache) or an empty-state line.
• Attachments and Links — each is an {{#each}} of file buttons, carrying data-open-file / data-open-url so a click opens the target; the links block is dropped entirely when there are none.

The built-in bottom-panel layout#

The default bottom panel is a wide, comfortable annotation reader:

<div class="bd-detail__section">Annotation — <span class="bd-viewfields__mono">{{citeKey}}</span></div>
{{#if notesHtml}}<div class="bd-notes bd-notes--wide">{{{notesHtml}}}</div>{{else}}<div class="bd-notes__empty">No annotation for this entry.</div>{{/if}}

A heading with the cite key, then the rendered notes (or an empty-state line) in the wide notes style. It shares the exact same context as the detail template — the two panels differ only in their markup.

11.9 A custom example#

Here's a small, complete detail-pane template that shows a header, a type-specific line via eq, the citation, and the attachments — using the hooks and widgets above:

<div class="bd-view__actions">
  <button type="button" class="bd-btn bd-btn--small bd-btn--primary" data-action="edit">{{icon "edit"}} Edit…</button>
</div>

{{#if title}}<h2>{{title}}</h2>{{/if}}
{{#if authors}}<p><em>{{authors}}</em>{{#if year}} ({{year}}){{/if}}</p>{{/if}}

{{#if (eq type "book")}}
  <p>📕 Book{{#if venue}} — {{venue}}{{/if}}</p>
{{else}}
  <p>{{type}}{{#if venue}} · {{venue}}{{/if}}</p>
{{/if}}

<bd-citation doc-id="{{documentId}}" item-id="{{id}}" cite-style="{{citeStyle}}"></bd-citation>

{{#if notesHtml}}<div class="bd-notes">{{{notesHtml}}}</div>{{/if}}

{{#if attachments}}
  <p>{{#each attachments}}<button type="button" class="bd-chip" data-open-file="{{url}}">{{icon "file"}} {{displayName}}</button>{{/each}}</p>
{{/if}}
{{#if links}}
  <p>{{#each links}}<button type="button" class="bd-chip" data-open-url="{{url}}">{{icon "link"}} {{displayName}}</button>{{/each}}</p>
{{/if}}

Reusing the bd-… classes (like bd-chip, bd-notes, bd-btn) gives your template the app's native styling for free; you're equally free to add your own classes and inline styles.

11.10 The multi-select panels#

When you select two or more entries, both panes switch to a multi-select view instead of the single-entry layout.

• The detail pane shows a sticky "Multiple entries selected" header above a scrollable list of each selected entry's pretty-printed citation preview.
• The bottom panel shows the same sticky header above a list of each entry's annotation.

Neither multi-select template contains editing controls: batch editing (set field, add/remove keyword) is done from the floating batch-edit bar at the bottom of the window — see Configurable Panels → Batch tools.

Their context is:

For reference, this is the built-in multi-select detail template:

<div class="bd-multi">
  <div class="bd-multi__sticky">
    <div class="bd-multi__head">Multiple entries selected <span class="bd-multi__count">{{count}}</span></div>
  </div>
  <ul class="bd-multi__list">
    {{#each items}}
    <li class="bd-multi__item">
      <div class="bd-multi__key">{{citeKey}}</div>
      {{#if previewHtml}}<div class="bd-preview bd-preview--multi">{{{previewHtml}}}</div>{{else}}<div class="bd-multi__bare">No preview.</div>{{/if}}
    </li>
    {{/each}}
    {{#if moreCount}}<li class="bd-multi__more">+{{moreCount}} more not shown</li>{{/if}}
  </ul>
</div>

11.11 Customizing outputs#

"Outputs" — the formats you get out of the app — come in two distinct flavors. One is Handlebars-driven and fully user-customizable; the other is CSL-driven and chosen rather than authored. It's important to know which is which.

Export templates (Handlebars — fully customizable)#

You can author your own export formats under Preferences → Templates, in the Export templates section. Each is a named Handlebars body plus an output file extension (html for a new one; a leading dot is stripped, and clearing it falls back to txt). Once defined, the template appears as a submenu under File → Export, with three scope choices — Whole Library…, Shown Entries… (the current group plus whatever the search box is filtering to), or Selected Entries…. Choosing one renders the entries through your template and writes the result to a file you pick.

These export templates are a different context from the panel templates. Each template renders against { title, count, entries }, where title is your library's name and entries is the list to output. Each entry exposes:

Two helpers are available in export templates:

• {{field "name"}} — looks up a field case-insensitively on the current entry, e.g. {{field "journal"}}.
• {{join array ", "}} — joins an array with a separator (default , ), e.g. {{join authors "; "}}.

A minimal export template loops the entries — this is exactly the body the + button seeds a new template with:

{{#each entries}}
{{authorsText}} ({{year}}). {{title}}. {{venue}}. [{{citeKey}}]
{{/each}}

The editor has the same Preview + Text / HTML toggle as the panel editors (it previews against the first eight entries of the open library, and opens in Text unless the template's extension is html), and values are HTML-escaped, so titles with <, >, or & export safely.

Citations and printing (CSL — chosen, not authored)#

The other outputs — the formatted citation in the detail pane, Edit → Copy Citation, and File → Print… — are not Handlebars. They are formatted by a CSL (Citation Style Language) engine, so you don't write their layout; you choose a style.

• Pick a style — Preferences → Citations → Default style sets the citation style used in the pane, in copy-citation, and in the printout. Three styles ship bundled (APA, Vancouver, Harvard).
• Install more — under Citation styles, click Install CSL file… and choose any Citation Style Language .csl file (e.g. from the Zotero / CSL style repository). It's validated, copied into the app's data folder, and added to the style list with a ★ marking it as a user-installed style; then pick it in the dropdown.
• Remove — the Citation styles list shows every style you installed, each with a × (Remove) button. Bundled styles aren't listed and can't be removed.

So: if you want a different reference style for citations or a printed bibliography, install or pick a CSL style — there is no Handlebars customization for the CSL citation, by design. If you want a bespoke output layout of your own design, use a Handlebars export template. See Preview & Citations for the citation block and Importing & Exporting for the full export and print story.

11.12 Errors & the safe fallback#

Two safeguards keep a bad template from breaking the app:

• In the editor — when you click Preview and your template fails to compile or render, the error message is shown in place of the preview (in red), so you can fix it before relying on the template.

• In the live pane — if the active template throws while rendering an entry, main sends the pane nothing at all, so you never see broken markup. What you see instead differs by pane, and it's worth knowing which:

  • the detail pane falls back to drawing itself the built-in way (the same Edit button, cover, preview card, citation, fields, annotation, attachments and links the default layout produces), so a bad fork there looks like the default pane;
  • the bottom panel has no such fallback — it simply shows nothing for that entry. A permanently empty bottom panel is the symptom of a fork that throws, not of a missing annotation.

  (An export template that throws is reported instead: the export stops with a readable "Template error: …" and no file is written.)

This means it's safe to experiment: a typo in a fork can't lock you out of your data — switch the Active dropdown back to Built-in default, or fix the template, and you're back.

See also#

• Configurable Panels — resizing, hiding, and swapping the panes (the layout side of the same feature).
• Preview & Citations — what the preview card and the CSL citation block are, and choosing a citation style.
• Importing & Exporting — the built-in export formats, the styled HTML bibliography, and printing.
• Shortcuts & Reference — the full menu and keyboard reference.