Folders And Roots

What It Is

Roots define top-level folder spaces, and folders define hierarchy inside those spaces. A view can bind to a root so users can organize records inside a navigable folder tree without changing the underlying data model.

This gives Jetstack a user-managed navigation layer that sits next to the normal query and property model.

Why It Matters

Folders are useful when users need to organize or browse records by location-like structure rather than by formal data properties.

Use them when:

  • users think in terms of cabinets, categories, areas, or workspaces
  • records need to be moved between organizational buckets over time
  • the structure is operational and navigational, not part of the core business schema

Do not use folders as a substitute for core meaning that should live in a property, relation, or type design.

Conceptual Model

The folder system has three layers:

  1. A root defines one folder space.
  2. Folders create the hierarchy inside that root.
  3. A view binds to a root and can expose folder navigation for records of its view type.

That last step is important. Folders do not become visible in a view automatically just because folders exist in the tenant.

Roots

Roots are intentionally simple. Their main job is to define the named top-level space in which a folder tree exists.

Use multiple roots when:

  • the tenant has distinct content domains
  • different business areas should not share one folder tree
  • separate views should expose separate folder spaces

In practice, the root acts as the container that a view points to.

Folders

Folders define the hierarchy inside a root. The main concepts are:

  • folder name
  • description
  • root
  • parent folder

This supports nested trees inside the selected root.

Folders are best when the structure is:

  • user-managed
  • likely to evolve over time
  • independent from the formal type schema

How Views Use Folders

A view uses folders only when both of the following are true:

  1. The view is bound to a root.
  2. The active viewer layout includes the Folders component.

This is the key rule for implementers.

A root by itself does not make folder navigation appear. The runtime folder UI is a view-layout component, so folder access is effectively off by default until the layout turns it on.

Folder Access Is Default Off In Views

Folder access is default off in ordinary views.

That happens for two reasons:

  • even if the viewer type supports folders, the default viewer layouts do not automatically place the Folders component into the layout for the normal list-style viewers
  • folder runtime behavior only becomes active when the layout actually uses the Folders component

So if a user says "this view has a root, but I still do not see folders," the first thing to check is the View Layout Builder.

How To Turn Folder Access On For A View

Folder access is enabled per view and per viewer layout.

To turn it on:

  1. Open the target View.
  2. Make sure the view has a root configured.
  3. Open the View Layout Builder.
  4. Select the runtime viewer you want to support, such as Table, Table sortable, List, or Cards.
  5. Move the Folders component from the unused view components area into an active view zone.
  6. Save the layout.

Once you do this, the view starts rendering the folder control for that viewer layout.

Why This Is Per Viewer

View layout is stored separately for each runtime viewer. That means folder access is not a single global toggle for the whole view.

For example:

  • you can enable folders in the Table layout
  • but still leave them absent in Cards

This is useful when the folder tree is valuable in one presentation mode but would be too heavy or distracting in another.

Supported Viewers

Folder access only works in viewer types that support the folders component.

In the current layout registry, folders are supported for list-style viewers such as:

  • table
  • table sortable
  • list
  • cards

As a practical rule, use folders in viewers where users browse and rearrange object-backed records rather than in purely timeline-style or specialized views.

What The Folders Component Actually Does

When the Folders component is present in the layout, the view renders the folders control and starts treating folder state as part of the runtime experience.

This includes:

  • showing the folder tree for the configured root
  • tracking the current folder selection as view state
  • limiting the visible records by the selected folder context
  • enabling folder-based movement workflows where supported

This is why folder access belongs in the view-layout layer rather than in the query-definition layer. It is not just a filter value. It is a navigational mode of the view.

What Happens If A View Has A Root But No Folders Component

If the view has a root but the layout does not include the Folders component:

  • the dedicated folder UI is not rendered
  • drag-and-drop folder interaction is not enabled
  • users do not get the normal folder browsing experience in that viewer

So the root defines the available folder space, but the layout decides whether the view actually exposes it.

Drag And Drop Behavior

Folder drag and drop is also tied to the Folders component.

The runtime only enables folder drag-and-drop object movement when:

  • the current viewer supports folders
  • the view has a root
  • the active viewer layout uses the Folders component

This is important because drag-and-drop is not just a generic list feature. It is explicitly treated as part of the folder-enabled view mode.

How Folder State Fits Into The View

Once folders are enabled, the current folder becomes part of the view’s working state in a similar way to active filters, tag state, or selected query.

This means folder selection influences:

  • what records are shown
  • where drag-and-drop moves records
  • how users navigate the current object space

That is why folder-enabled views should be documented for users. Folder context changes the meaning of the current dataset.

Example

Suppose a document-oriented view should let users browse contracts by department folders.

Use this pattern:

  1. Create a root for the contract space.
  2. Build the folder hierarchy inside that root.
  3. Configure the View to use that root.
  4. In the View Layout Builder for the Table viewer, add the Folders component.
  5. Save the layout and let users browse and move records within the folder tree.

If you skip step 4, the view still knows which root it belongs to, but the user will not get the intended folder navigation UI.

Best Practices

  • Always think of folders as a view capability, not just as stored hierarchy.
  • Configure the view root first, then enable the Folders layout component.
  • Enable folders only in viewer layouts where users genuinely need navigational hierarchy.
  • Keep folder structure operational and user-friendly rather than deeply technical.
  • Use properties for business meaning and folders for navigation and organization.
Previous← Filter Lists And TagsNextGroups →