Panels

A Panel is a screen built for the people who use a space rather than the people who program it. It opens at its own web address, needs no Lightpath login, and shows only what you put on it.

A wall tablet by the door that dims the lights. A phone page a bartender opens to change the scene. A always-on display in the office showing what is playing and whether anything is wrong. All Panels.

Two kinds of Panel

When you create a Panel you choose how it is built, and the choice is permanent.

Widget Panels are assembled from ready-made blocks — a content grid, a palette picker, now-playing, schedule, health. You arrange them, style them, and Lightpath draws them. No code.

Custom Panels are your own HTML, CSS and JavaScript. You get a blank page and the full Panel API. Choose this when the layout you want is not a grid of cards — a floor plan you tap, a room diagram, a branded splash screen.

Opening a Panel

Every Panel has an address of the form /p/name. From the Panels page you can:

• Browser — open it in your normal web browser, exactly as a guest will see it
• New window — open it in its own Lightpath window, sized like a tablet
• Copy URL — copy the address to send to a device

Point a tablet's browser at that address and add it to the home screen. It launches straight back into the Panel, with the Panel's own name and icon.

Who can open it

Set this on the Access tab. Three modes:

In the app, Operators can open and use Panels. Creators can also build and edit them. Admins can do both.

A Sign-in Panel can also be limited to certain roles: tick them under Who can open it. Anyone whose role isn't ticked won't see the Panel on the Panels page, and its address won't open for them. Admins always see every Panel, so unticking every role leaves a Panel only admins can open. Open and PIN Panels ignore this list, because anyone at the device gets in.

Leaving a Panel

The Panel's header has a way out that depends on how the device got in:

• Lock on a device that entered a PIN. The device forgets it was let in and shows the number pad again.
• Sign out for someone who signed in. This signs them out of Lightpath in that browser.

Both ask before doing anything, so a stray tap on a wall tablet won't lock it. On a phone, these sit with Contact support in the header's ⋯ menu. An Open Panel has nothing to leave, so it shows neither. A Panel with its header turned off has no Lock or Sign out either.

What a Panel can do

There is nothing to configure here, on purpose. A device that gets into a Panel can use everything on it — activate content, run controls, and drive playback and the schedule.

It can never author or delete content. A PIN is a shared secret written on a wall, not a personal password, so no Panel hands out the ability to change or remove your looks and scenes.

The reason there is no setting: a Panel that granted less than it displayed would draw a control and then refuse it when pressed, which looks like a broken installation rather than a locked one. What a Panel can do is exactly what you put on it, so put on it only what its audience should have.

Macros

A macro is a slider that changes how everything playing looks, without editing any look. There are three:

To add one, open a Controls widget, click Add control, choose Macro, and pick it from the list. Each macro can appear once per Controls widget. The same three sliders are always in the Controls section of the Controller's right column, and moving one in either place moves it in both.

A macro applies to every output and to every look that plays while it is set: when a playlist moves to the next look, or a scene or the schedule changes what is on, the new content plays at the same Speed, Scale and Shape. Speed and Scale multiply each look's own setting, so 2× on a look that was already fast is twice as fast again. Shape moves each look's setting up or down from where it was saved.

Macros are never saved. Restarting Lightpath or switching projects puts all three back where they rest. Double-click a macro to return it there yourself; the slider also snaps there as you drag past the middle.

A macro is grayed out when nothing playing has that control. A look takes part when its source has the matching parameter; effects are never changed. Most built-in sources have Speed and a handful have Scale; none has Shape yet, so Shape only does something with sources built to use it. Sources that pass an outside picture straight through, such as NDI and Spout, have none of them.

A look being edited ignores the macros until you close the editor, so what you see while editing is the look as it is saved.

Writing a Custom Panel

Creating a Custom Panel scaffolds three files in your project:

projects/your-project/panels/your-panel/
  index.html
  style.css
  script.js

Edit them with any editor. They live in the project folder, so they are backed up and synced with everything else. The Custom tab in the Panel editor has an Open folder button, and a Reload preview button to pick up your changes.

The Panel API

Lightpath injects window.lightpath into your page automatically — there is no script tag to add and no key to configure.

<button id="warm">Warm evening</button>

<script>
  document.getElementById("warm").onclick = () => {
    lightpath.applyContent("Warm Evening");
  };
</script>

Every call is checked on the server, so a Panel can never do more than a Panel is allowed to do, whatever its code asks for. Calls that would author or delete content are refused.

Reading what's happening

These refresh on their own. To react to a change:

const stop = lightpath.on("state", (state) => {
  document.body.dataset.playing = state.outputs[0]?.activeLookName ?? "";
});
// stop() when you no longer care

on also takes "ready" and "error".

Making something happen

Images and video

img.src = lightpath.getThumbnailUrl("Warm Evening", "look");

getSourceThumbnailUrl(source) gives the raw pattern image before any palette. attachStream(el, target) puts live video — an output preview or a camera feed — into a <video> or a <canvas>, and returns a handle with .stop().

Styling with the Panel's brand

The accent and mode you pick in the editor arrive as CSS variables, so your stylesheet can follow the Panel's branding instead of hard-coding colors:

button {
  background: var(--lp-accent);
  color: var(--lp-mode-text);
}

What your code cannot do

A Custom Panel runs in an isolated frame. It has no access to the Lightpath app's page, no login token, and no cookies. It cannot make its own network requests — everything goes through window.lightpath, which applies the Panel's role to each request.

This is deliberate, and it is what makes it safe to put someone else's HTML on a wall tablet: the worst a mistake in your code can do is the same as what a person holding that tablet could already do.

Pages and groups

Two ways to fit more into a Panel than one screenful, and they work at different scales.

A page is a screen of its own. Add a second page and the Panel grows a nav bar along the bottom, one entry per page, and shows one page at a time. Use pages for things a person is doing separately — lights on one page, music on another.

A group is one tile that holds several widgets, switched by tabs across its top. Everything else on the page stays put. Use a group for a few things that belong in the same spot — a scene picker and a brightness pad in one corner.

Both are built on the Arrange tab, by dragging. Drag a widget onto a group to put it in; drag it back out to give it its own tile again. A group's tab order is the order its widgets appear underneath it, and dragging a group by its handle moves the whole thing, contents included. Deleting a group is not deleting its widgets — they fan back out where the group was. Nor is deleting a page: its contents move to the page above it.

Tablet and phone layouts

A widget Panel has two layouts: one for tablets and wall displays, one for phones. The screen picks between them by width alone. Below 640 pixels wide it gets the phone layout; anything wider gets the tablet layout. A phone turned sideways is wider than that, so it gets the tablet layout.

Phones and tablets want different things. A tablet usually has room for everything on one screen. On a phone it is better to give each widget the full height and spread them across a few pages. So each layout has its own:

• Pages — a tablet layout with one page and a phone layout with four is normal.
• Order — which page each widget is on, and where on it.
• Size — on a tablet, each widget is 1/2 or Full width. On a phone everything is full width, so height is the only size.
• Visibility — the eye on each row in the Arrange list hides that widget on the layout you are editing, and only that one.

Everything else is shared. The widgets themselves and their settings are the same on both, and so are groups: what is grouped with what, and the tab order. Remove a widget and it is gone from both. To take it off just one layout, use the eye instead.

Switch between the two with Tablet and Phone at the top of the Arrange tab. The preview, the Arrange list and the size controls all follow that switch, so what you drag is always what you see. A widget you add appears at the end of the other layout too. Move it where you want it there, or hide it with the eye.

Height

Height is a share of the screen: 1/3, 1/2, 2/3 or Full. Two widgets at 1/2 stacked in a column fill the screen exactly, and so do 1/3 and 2/3. The screen here is the part under the header bar and above the page nav bar.

Some widgets need a minimum height for what you have turned on — a two-row scene picker needs 1/2 — and some have nothing more to show past a certain height. Those sizes are not offered.

If a column adds up to more than one screen, the page scrolls. The preview shows a dashed line where the screen ends, so you can see what a viewer will have to scroll to.

In the editor, the toolbar over the preview lets you check the layout at real device sizes — iPad, iPhone, Pixel, a 1080p wall display — and rotate a tablet between portrait and landscape. Changing the preview size never changes the Panel.