README

Live preview for the Flarum composer. Textarea is always the source of truth (raw Markdown/BBCode); preview is either a split panel below the editor or a full toggle via the eye button.

How it works

Default (Preview on click OFF)
- Composer: top = textarea, bottom = split preview panel (server-rendered HTML, debounced). Panel is open by default; tap the header to collapse/expand.
- Drag header up to expand the preview more.
- Preview updates as you type (debounce + optional instant triggers).
Preview on click ON
- Split view is hidden. No bottom preview panel.
- Eye button appears in the composer.
- Reply composer: Flarum’s default preview button is replaced by this one.
- Click eye → full preview (textarea hidden, only rendered HTML). Click again → back to textarea.
Settings
- Preview debounce (ms): Delay before calling POST /api/preview (default 300).
- Instant triggers: If ON, preview is requested immediately on certain keystrokes (e.g. closing **, ```) as well as after debounce.
- Preview on click: See above; when ON, split view is off and eye toggles full preview.
Backend
- POST /api/preview: body { content } → JSON with rendered HTML (Flarum Formatter).
- Client uses tokenizer for template detection only; all rendering is server-side.

Developer Notes

Split view (default): The composer body is wrapped: textarea in the top portion, a preview panel below. The panel shows server-rendered HTML; you can expand/collapse it by tapping its header.
Server preview: Content is sent to POST /api/preview (same pipeline as Flarum’s TextFormatter: Markdown + BBCode + extensions). The extension registers this route and uses Flarum’s Formatter to parse and render.
Client tokenizer: A small client-side tokenizer recognizes common Markdown (headings, bold, italic, code, lists, links, images, blockquotes). It is used only to detect default toolbar templates (e.g. [link](https://), **bold**) and avoid rendering them until the user edits the placeholder.
BBCode / unknown tags: Not parsed on the client. Full content is sent to the server; the server returns HTML. The client does not assume any BBCode extension; it relies on the server preview for unknown tags.

Install

Copy the extension into your Flarum extensions folder (or install via Composer when published):
```
cd /path/to/flarum
composer require zerosonesfun/flarum-preview
```
Or clone/copy into extensions/zerosonesfun-preview.
Clear cache and enable in Admin:
```
php flarum cache:clear
```
Then Administration → Extensions → Preview → Enable.
Rebuild frontend assets if your setup requires it (e.g. php flarum build if you use Flarum’s build pipeline).

Build JS (for development)

From the extension directory:

npm install
npm run build

This produces js/dist/forum.js and js/dist/admin.js. Use npm run dev for watch mode.

Admin settings

Preview on click (eye icon)
When ON: live preview is off; users use an eye icon to toggle between raw composer and preview.
Preview debounce (ms)
Delay before sending content to the server (default 300).
Instant preview triggers
When ON: preview is requested immediately on certain keystrokes (e.g. closing ** or ```) instead of only after debounce.

Known edge cases

Very long content:
Debouncing and optional instant triggers limit server calls; for very large posts, consider increasing debounce or disabling instant triggers.
BBCode-only content:
Preview is correct (server handles it). The textarea is always the source of truth and can be edited normally.

License

MIT. See LICENSE.

Runbook (tests and build)

Build JS

cd /path/to/flarum-preview
npm install
npm run build

Produces js/dist/forum.js and js/dist/admin.js.

Repository

zerosonesfun/flarum-preview — GitHub

zerosonesfun / flarum-preview

Maintainers

Package info

Statistics

Security