Skip to main content
A screen resource defines one portal route. It can contain no root widget or one root widget node.

Author a screen

Create or edit a JSON file under portal/screens/. Keep its $schema URL and use the file name as the screen slug. Use the current schema for:
  • route metadata;
  • access and visibility settings;
  • the root widget node;
  • every nested widget property.
Do not copy a widget shape from an old portal. Built-in nodes and their properties can change with the Portal Definition schema.

Compose a widget tree

When a screen needs child placement, choose a registered container widget from the current schema or builder catalog. The container’s node definition tells you which property owns its children.

Start with a container at the root

Make the screen’s root node a container: ContainerWidget, LayoutWidget or CardWidget. Put the screen’s widgets in its props.children. Screens created in the Portal Builder start with a ContainerWidget root. With any other widget at the root, the screen renders, but the Portal Builder shows no drop zones on it, so admins can’t drag widgets onto it. Push only warns:

Choose a built-in widget

Use a built-in widget before you write a Widget Package. Built-in widgets work in the Portal Builder, follow the portal theme, and need no publishing. Use the widget schema for each widget’s properties. Don’t invent a type. The schema accepts only the built-in types and published Widget Package types. A node whose type the portal doesn’t know renders nothing.

Use EmbedWidget carefully

EmbedWidget shows a URL in a frame, exactly as you give it. It doesn’t add anything to the URL. When the Fluid admin opens a Droplet, it adds the company’s installation reference and a session to the URL. An EmbedWidget adds neither, so don’t point it at a Droplet’s admin page: a page that needs those values can’t tell which company is viewing it. If a Droplet or app publishes Widget Package widgets, place those instead. They work in the Portal Builder and fit the screen around them. Each node must use a built-in widget type or a published third-party widget type available to the portal. See PortalScreen, PortalWidgetNode, and PortalBuiltinWidgetNode for the exact properties.

Preview changes

Check each changed route at its screen slug. Verify empty content, narrow and wide layouts, interactive states, and the active theme modes.
On the deployed portal, a viewer receives only the screens that their profile’s navigations point to. Add a navigation item for every screen people should reach. Local preview loads every screen file, so a screen without a navigation item can open locally and still be missing once deployed.

Validate references

Preview can preserve an unresolved navigation entry without attaching a screen ID. Push rejects invalid references. Run fluid portal doctor, inspect every changed navigation target, and fix missing screen slugs before push.