SaleSys egna vyer (custom views)

A vy is a standalone HTML fragment that SaleSys renders as a panel inside app.salesys.se — reachable from the top navigation or from Inställningar. No framework, no build step: one HTML file with an inline <style> and <script>. It talks to the SaleSys REST API as the logged-in user.

Two layers:

• View preset (view-presets-v1, admin) = the reusable template (html + optional settingsHtml, icon, rights).
• Org view (views-v1) = a per-organisation instance pointing at a preset via presetId, deciding navigation placement + team/role visibility. URL: https://app.salesys.se/views/<viewId>.

⚠️ First decision: which paradigm?

There are two ways to author a view. Pick before writing a line — they don't mix well.

	Native (handlebars + components)	Raw JS
Best for	Forms, settings/config panels, master-detail CRUD, anything that looks like the rest of SaleSys	Dashboards, games, custom canvas/layout, heavy realtime, xlsx export, anything the components can't express
Uses {{ }}	Yes — this is the templating language. {{custom.x}}, {{#each}}, {{#if}}	Never — you build the DOM yourself; deploy-preset.py refuses any file containing {{
Components	<Field>, <SecondaryButton>, <SettingsList>, <Transition>, <CheckboxField>, <Tooltip>, Modal	plain HTML + your own CSS, matching native chrome via CSS variables
State	window.form.custom / setState, window.form.settings / setSettings, window.form.addHook	your own JS variables + a poll loop; persist in the user reference object
Data access	window.form.resources.* (preloaded) + fetch with window.getAccessToken()	fetch with token read from the s2_utoken cookie
Edited	in the browser (admin.salesys.se) or via API	authored in the vyer/ repo, deployed with deploy-preset.py
Reference example	examples/webhooks.view.html, examples/stangtider.view.html (both bundled here)	any dir under vyer/ (tavlingar2/, qa/, tidsrapportering/)

Rule of thumb: if it's a form or a settings screen, go native — you get validation, theming, and the SaleSys look for free. If it's an interactive app that fights the component model, go raw JS. The {{-refusal in deploy-preset.py exists because the repo standardised on raw JS — it is a repo choice, not a platform limit. The platform happily renders handlebars (Webhooks, Stängtider, Rapportverktyg all do).

Read next (progressive disclosure)

• reference/native-components.md — the full catalog: every component + attribute, the complete window.form.* API, the modal system, the handlebars helper set, resources, partials. Read this before building a native view. The bundled examples/webhooks.view.html is the masterclass — a full CRUD panel (list → modal editor → preview → nested actions) built entirely from native components; examples/stangtider.view.html is a second complete worked example (opening-hours rules + call routing).
• reference/apis-and-deploy.md — REST endpoints, presetState, custom rights, the reference-object-as-database pattern, in-app notifications, files, entity groups, and the build-harness → deploy-preset workflow with the raw-JS gotchas. Read this before deploying anything or for any data/API question.
• In the SaleSys repo: vyer/README.md, vyer/deploy-preset.py, vyer/presets.json, vyer/PROJECT-LOG.md, and any existing view dir are the live source of truth — always cross-check them.

Workflow (either paradigm)

1. Scaffold vyer/<name>/<name>.html — copy the closest existing view (native → an example here; raw JS → a vyer/ dir).
2. Test locally before prod. Raw-JS views: python3 vyer/build-harness.py → serve /tmp/ksv-<name>-test.html and retest after document.body.innerHTML = document.body.innerHTML (the app re-renders the view DOM after init). Native views: preview in admin.salesys.se ("Förhandsgranska"); window.form.preview is true there.
3. Deploy the preset (admin token in /tmp/ksv-token): python3 vyer/deploy-preset.py <name> (first run POSTs + records the id in presets.json; later runs PUT). Register the view in deploy-preset.py's VIEWS dict (and build-harness.py if raw JS). Preset HTML changes propagate to every org view instantly.
4. The first org view must be created via API — a preset's settings only surface in the UI once one org view exists: POST /users/views-v1 { presetId, name, iconName, iconColor, locations, teamIds: null } (null = everyone, [] = admin-only). Thereafter edit HTML in the browser.

Rules that apply to BOTH paradigms

• No in-view title/heading — the app already renders the view's name as a large title top-left (part of the nav chrome). Do NOT repeat it with your own <h1>/header inside the view — it shows the name twice. Start straight with content. Native views can add a subtitle via window.form.setSubtitle("…") and a title-bar action via window.form.setButton(...); a detail/sub heading inside a card is fine, just not a top-level view title. (For a full-bleed compact layout you may instead hide the app title with CSS, e.g. .ribbon_title__3ukce{display:none} — the QA view does this.)
• Never set page width — the SaleSys app container controls the view's width and outer padding. A view fills the container fluidly; it must NOT impose its own page width, max-width, fixed pixel width, margin: 0 auto centering, or outer horizontal margins on its root. Lay out within the given width with fluid/responsive CSS (%, fr, flex/grid, minmax); constrain only inner elements when needed, never the whole view. Don't assume a viewport width either — the container narrows on smaller screens and when side widgets are open.
• No emojis — FontAwesome 5.10.2 (global) or inline SVG. ✓/× typographic marks are fine. (User rule.)
• Theme via CSS variables with fallbacks — var(--color-background-2, #fff), --color-text-2/3, --color-primary, --color-background-1/3, --color-element-hover, --border-radius-button (8).
• No native <select> in raw-JS forms — use icon-card grids / chip rows / preview cards + a side info-panel. (Native views use <Field select-type="dropdown|switches"> instead, which is fine.)
• Icons: FontAwesome 5 free — https://fontawesome.com/v5/search?ic=free-collection

Raw-JS-only rules (event delegation on document, window.__<ns>Cleanup, the mandatory contrast probe in the poll loop, cookie-token auth) live in reference/apis-and-deploy.md.