Skip to main content

Viewer Integration

The Typograph Viewer fills templates in. It is the read-only counterpart of the Editor — same rendering engine, same bundle family, a much smaller interface: no menu bar, no parameter bar, and a floating toolbar that follows whatever is selected.

The Viewer is not the Editor with things switched off. It is a separate script (viewer.js) built for one job: letting an end user complete a template an author already designed.

There is no npm package — include the script from the CDN.

Quick Start​

<!DOCTYPE html>
<html translate="no">
<head>
  <meta charset="utf-8">
  <title>Typograph Viewer</title>
  <script src="https://cdn.typograph.nl/editor/latest/scripts/jsColorEngineWeb.js"></script>
</head>
<body>
  <!-- The viewer builds itself inside this container. It must have a height. -->
  <div id="app" style="position:absolute; top:0; left:0; right:0; bottom:0;"></div>

  <script type="module">
    import { Viewer } from 'https://cdn.typograph.nl/editor/latest/viewer.js';
    const viewer = new Viewer({ container: '#app' });
  </script>
</body>
</html>

Two scripts, no markup to author. The colour engine (jsColorEngineWeb.js) is a bare-global script and stays your responsibility; everything else — the chrome, the stylesheet, the webfont — the bundle brings itself.

Viewer is also exposed as window.Typograph.Viewer if you would rather not use a module script.

note

viewer.js does nothing until you construct a Viewer. This differs from editor.js, which mounts itself on document.body when nothing constructs it. A page can therefore load the viewer bundle and decide at runtime whether to mount it.

Container Requirements​

container​

A CSS selector, a bare element id, or an HTMLElement — all three work:

new Viewer({ container: '#app' });                          // selector
new Viewer({ container: 'app' });                           // bare id
new Viewer({ container: document.getElementById('app') });  // element

If nothing matches, a warning is logged and the viewer mounts on document.body rather than failing silently. Omit container entirely and you get the full-page viewer.

The container must have a height​

This is the one requirement. The layout is absolutely positioned and resolves against the container's box, so a container with no height gives you a viewer with no height. A plain <div id="app"></div> collapses to zero.

#app { position: absolute; top: 44px; left: 24px; right: 24px; bottom: 24px; }
#app { height: 90vh; }
/* Inside a flex or grid parent that gives it a track. */
#app { min-height: 0; }

The viewer handles the rest: an unpositioned container is given position: relative, and a container with visible overflow is given overflow: hidden so nothing escapes the box you allotted. Both are restored on destroy().

Everything stays inside the container​

The floating toolbar, its palettes and the swatch picker are all confined to the box you gave the viewer — none of them can be drawn over the rest of your page.

Construct it early​

Construct the Viewer before the window load event. A module script in the page body is early enough.

Script URL​

ChannelURL
Latest stablehttps://cdn.typograph.nl/editor/latest/viewer.js
Minifiedhttps://cdn.typograph.nl/editor/latest/viewer.min.js
Colour enginehttps://cdn.typograph.nl/editor/latest/scripts/jsColorEngineWeb.js

The viewer ships from the editor bundle's CDN folder — it is a second entry point of the same build, not a separate product path. Load viewer.js as a module (<script type="module" src="...">).

Options​

new Viewer({
    container:   '#app',
    show_rulers: true,          // default true
    page_bar: {
        visible:          true, // the bar itself
        show_name:        true, // each page's name
        show_page_number: true, // the number badge
        show_add_page:    true, // the "new page" control
    },
});
OptionTypeDefaultWhat it does
containerselector | id | HTMLElementdocument.bodyWhere the viewer is built.
show_rulersbooleantrueShow the rulers.
page_bar.visiblebooleancanvas defaultShow the page bar at all.
page_bar.show_namebooleancanvas defaultShow each page's name.
page_bar.show_page_numberbooleancanvas defaultShow the page-number badge.
page_bar.show_add_pagebooleancanvas defaultOffer the "new page" control.

All options are optional; omit any and the canvas default applies.

page_bar matters more than it looks. The page bar is the viewer's only navigation, but a filled-in template is not an authoring surface — the page names it carries are the template author's, not your user's, and there may be nothing to number. Turn off what your product should not show.

What the User Can Edit​

Permissions are answered by the template, not by the viewer. An element with no authored edit_options falls back to the viewer default policy:

InteractionDefault in the viewer
Editing textAllowed
Moving, scaling, rotating an image inside its frameAllowed
Moving, resizing, rotating the frame itselfDenied

Grant frame edits in a template and the same code allows them, with no change to your host. This is why the viewer is described as a different profile rather than a restricted editor.

The toolbar floats and follows the selection, showing the controls for whatever is selected and undo/redo when nothing is. Drag it by its handle and it stays where you put it — following the selection is a convenience, your placement is an instruction.

What the Viewer Does Not Have​

Absent by construction — a template cannot turn these on:

  • No menu bar, content bar or parameter bar
  • No path tool, marquee, guides or multi-select
  • No numeric position/size entry — that is the parameter bar's job; direct manipulation is the whole interface
  • No image picker. React to the selection event and swap the image through the manifest API — what replaces it belongs to your application, not to Typograph
  • No Find and Replace dialog, because there is no menu bar to carry it. The API behind it is canvas-level and works here unchanged: window.typograph.find() and replace_all() are available in a viewer embed — see Find and Replace. If the filling in happens server-side before the document reaches the viewer, TextModel is the same job done there

Lifecycle​

const viewer = new Viewer({ container: '#app' });

viewer.get_document();   // the canvas document, once booted
viewer.destroy();        // remove the viewer's DOM and styles

Re-mounting after destroy() is not supported — reload the page instead.

The viewer emits the same canvas lifecycle events as the editor, including typograph_editor_ready once it has finished setting up and typograph_document_opened when a document loads.

Authentication​

The viewer renders a document JSON payload that your page or server already resolved — it does not call Typograph APIs on your behalf. If your template is protected behind the File Service, fetch the JSON server-side with a user token and hand the data to the viewer.

Client tokens cannot read templates from /v1/file/* — see Token Types.