Views

What It Is

A view is Jetstack's configured data workspace for a type. It combines:

• a target object type
• a default query
• a default viewer
• runtime display options
• add-time context rules
• query switching options
• optional folder context
• view-level actions
• per-viewer layout settings

In practical terms, a view is the place where a type and a query become a usable interface.

Why It Matters

Types define what data exists. Queries define which records and columns are relevant. Views decide how that result becomes a working screen.

Use views to shape different jobs around the same data model. For example, the same Task type can support:

• a table view for back-office review
• a kanban view for operational triage
• a calendar view for planning
• a card view for mobile-friendly inspection

A strong view reduces friction by making the right data, controls, and creation defaults appear in the right context.

How To Read This Chapter

This chapter follows the structure of the actual View builder in the platform:

1. general configuration
2. display and behavior settings
3. add-time context injection
4. view actions and layout configuration
5. system fields

For each option, the goal is to explain:

• what it controls
• how it can be configured
• when to use it
• what effect it has at runtime

Use this chapter together with:

• Queries
• Query Parameters
• Expressions
• Canvases
• Folders And Roots

Mental Model

Keep these distinctions clear:

• object_type defines which type the view works with
• query defines the default data selection
• viewer defines the default presentation mode
• relevant_queries defines which other queries users may switch to from this view
• adding_* fields define how object creation behaves specifically from this view
• view_actions define extra operations available from the view
• settings stores layout-builder configuration and viewer-specific layout state

The view is not the place to encode all business filtering logic. Put durable data-selection logic into Queries, then use the view to decide how that query becomes an interface.

Configuration Areas

The platform organizes view configuration into these groups:

• General
• Settings
• Adding
• System

There are also two important builder actions outside the standard field groups:

• Layout builder
• Actions editor

Those two are part of real view configuration even though they are not edited as plain scalar fields.

General Configuration

view_name

What it is:

• the main administrative name of the view

How to configure it:

• enter a stable, recognizable name such as All Tasks, Open Opportunities, My Calendar, or Files By Project

Why it matters:

• this is the title-role field for the view resource
• it is used as the primary name in builder screens
• it also becomes the fallback heading when view_title is empty

Use it when:

• you need a clean implementation-facing name that clearly describes the purpose of the view

Good practice:

• name views after the job they support, not only the type they display
• prefer Invoices Awaiting Approval over just Invoices

view_title

What it is:

• the display-facing heading title of the view

How to configure it:

• enter the exact title users should see when the view renders
• leave it empty if the same wording as view_name is appropriate

Why it matters:

• at runtime, Jetstack falls back to view_name when view_title is empty
• this lets you keep a technical or administrative builder name while still presenting a cleaner end-user heading

Use it when:

• the displayed heading should differ from the internal builder name
• the user-facing wording should be shorter or more task-oriented

icon

What it is:

• the icon associated with the view

How to configure it:

• choose an icon that reflects the work surface, such as list, board, calendar, files, or reporting

Why it matters:

• the icon strengthens navigation and recognition
• it also helps differentiate several views that target the same type

Use it when:

• the tenant uses multiple views of the same type and needs clear visual distinction

object_type

What it is:

• the type whose objects the view displays

How to configure it:

• select one type from the list of types
• the selected type should match the query and the intended viewer behavior

Why it matters:

• this is one of the foundational view settings
• it determines which properties, queries, actions, folder roots, and add-time values make sense

Runtime implications:

• the view loads objects of this type
• property references in custom_col_names, adding_*, calendar mappings, and many layout settings are interpreted against this type

Design guidance:

• configure the type first or at least decide it early
• changing object_type later can invalidate column mappings, add-value maps, or related query assumptions

viewer

What it is:

• the default viewer mode for the view

How to configure it:

• choose one of the supported viewer types, typically:
  • table
  • table_sortable
  • list
  • cards
  • calendar
  • kanban

Why it matters:

• it determines how results are presented when the view first opens
• it influences which layout zones and layout components are meaningful

Important runtime rule:

• if the selected query is a custom query, the effective runtime viewer is always table
• this means the configured viewer is ignored for custom-query execution

Use each viewer when:

• table: general-purpose tabular inspection
• table_sortable: table view with sortable behavior when that interaction matters
• list: compact operational browsing
• cards: visual item scanning
• calendar: date-oriented planning
• kanban: stage or workflow progression

Practical guidance:

• choose the viewer that matches the job, not only the data shape
• if users should switch viewers at runtime, configure the alternate viewer layouts in the layout builder as well

explicit_start_property

What it is:

• a manual property mapping for the calendar start date field

How to configure it:

• this field only appears when viewer = calendar
• enter the target property reference using the type's property identifier, typically a system name or property ID

Why it matters:

• by default, Jetstack tries to infer the calendar start field from property roles such as start date or special date roles
• this field overrides that inference

Use it when:

• the type has several date-like properties
• the automatic role-based choice would be ambiguous
• the calendar should use a date field that is not the default role-based candidate

Example:

• a task type has created_on, due_date, and planned_start
• the calendar should place items by planned_start
• configure explicit_start_property instead of relying on automatic inference

explicit_end_property

What it is:

• a manual property mapping for the calendar end date field

How to configure it:

• this field only appears when viewer = calendar
• enter the property reference that should act as the calendar end field

Why it matters:

• it overrides the normal date-end role lookup
• it is especially useful for range-based items such as events, bookings, or planned work blocks

Use it when:

• the calendar should show duration rather than a single point in time
• the end field is not the obvious default

query

What it is:

• the default query for the view

How to configure it:

• select the query that should load when the view opens
• make sure the query targets the same object_type

Why it matters:

• this is the view's baseline data definition
• the query controls filters, visible columns, groupings, calculations, merging, and result shape

Runtime behavior:

• the view stores the chosen query as its default
• users may still switch to other queries listed in relevant_queries
• user-specific query preference may later override the active default in day-to-day use

Best practice:

• choose a query that represents the most common or safest starting point for the view

persist_default_groups

What it is:

• a grouping persistence flag for query switching

How to configure it:

• enable it when the view should preserve default fixed groupings from its main query even after switching to another query in the same view

Why it matters:

• a view can expose several relevant queries
• when a user switches away from the default query, Jetstack normally changes to the new query's grouping model
• with this option enabled, fixed default groupings from the main query remain active when the runtime merges query parameters

Use it when:

• the view's main structure depends on one stable grouping concept
• the query selector should change filters or scope without collapsing the grouping layout

Typical example:

• a kanban-like work view groups by status
• you want users to switch between All, Mine, and Overdue
• the grouping by status should remain stable across those switches

relevant_queries

What it is:

• additional queries users may switch to from this view

How to configure it:

• select one or more queries that belong to the same object type and make sense in the same working context

Why it matters:

• this turns one view into a reusable work surface with several query perspectives
• the runtime presents the default query together with these relevant alternatives

Runtime behavior:

• the default query is always the baseline
• relevant_queries are added as switchable options
• availability is still filtered by query publicity and ownership rules

Use it when:

• users need several filters of the same operational screen
• you want one view to host All, Mine, Team, Archived, or similar perspectives

Avoid it when:

• each query really deserves its own separate workflow and presentation

is_active

What it is:

• the activation switch for the view

How to configure it:

• keep it enabled for live views
• disable it when the view should remain stored but not actively used

Why it matters:

• this is the basic operational lifecycle flag

Use it when:

• staging a future view
• temporarily retiring a view without deleting it
• keeping draft or backup views out of normal use

Display And Runtime Settings

show_title

What it is:

• whether the view heading should be rendered

How to configure it:

• enable it for normal standalone views
• disable it when the heading would be redundant, especially in embedded or canvas-driven contexts

Why it matters:

• views can be rendered directly or inside other surfaces
• a repeated title can make embedded compositions feel cluttered

Use it when:

• the view is the main surface on the page

Disable it when:

• the surrounding canvas or module already provides the section heading

show_filters

What it is:

• whether the filters area should be shown by default

How to configure it:

• enable it when users should actively explore, narrow, or shape the result set
• disable it for intentionally fixed or simplified views

Why it matters:

• the filters area is where users access query switching, ad hoc filters, grouping, calculations, and related tools

Practical note:

• even when disabled, some runtime states may still surface filter-related information when active parameters exist
• the option controls the primary visibility intent of the view

Use it when:

• the view is exploratory or analytical

Disable it when:

• the view is meant to behave like a fixed dashboard or tightly scoped task surface

show_add_button

What it is:

• whether the standard object creation button should be shown

How to configure it:

• enable it if this view should be a creation entry point
• disable it if objects should not be created from this context

Why it matters:

• the view can double as both browsing surface and context-aware creation surface

Important runtime rule:

• the button is only shown if the user is allowed to create objects of the selected object_type
• this means enabling the flag does not bypass permissions

Use it when:

• the view naturally leads to creating more objects of the same type

Disable it when:

• records should be created only through a specialized flow
• the view is read-only or reporting-oriented

add_button_text

What it is:

• a custom label for the add button

How to configure it:

• enter a contextual action label such as Add Task, Create Booking, Log Expense, or New Contact
• leave it empty to use the generic platform default

Why it matters:

• action wording can make the intent of the view much clearer

Use it when:

• the view has a strong business context and the default generic label would be vague

custom_col_names

What it is:

• per-column label overrides for the view

How to configure it:

• provide a structured object where:
  • keys are property system names or property IDs
  • values are the column labels you want the view to display

Example:

{
  "due_date": "Deadline",
  "owner": "Responsible Person"
}

Why it matters:

• the same property can need different wording in different views
• this lets you adapt labels to the user's task without renaming the property globally

Runtime behavior:

• the view sanitizes and resolves these labels against the selected object type
• the custom names are also used in grouping and merging UI where relevant

Use it when:

• a property name is technically correct but not ideal in this specific work context

available_to_roles

What it is:

• a role-based availability list for the view

How to configure it:

• select the roles that should have this view available

Why it matters:

• views are often role-specific workspaces
• not every role should see every operational surface, even when the underlying data type exists

Important distinction:

• this controls availability of the view itself
• it does not replace object-level create, edit, show, or delete permissions on the underlying type

Use it when:

• the same type needs different working views for different roles
• a specialized operational view should stay hidden from unrelated users

no_data_message

What it is:

• the message shown when the current query returns no results

How to configure it:

• enter a helpful empty-state message, such as:
  • No open tasks match the current filters.
  • No files are stored in this folder yet.
  • No bookings are scheduled for this period.

Why it matters:

• empty states are part of the user experience
• a good message helps users understand whether the view is functioning normally or whether they should widen filters or add data

Use it when:

• the view should speak in business language rather than generic system wording

root

What it is:

• the folders root used by the view

How to configure it:

• select a folders root when the view should expose folder navigation and folder-based organization for its objects

Why it matters:

• this gives the view folder awareness
• it enables folder browsing, counts, breadcrumb context, and folder assignment workflows against the chosen root

Use it when:

• the type needs document-like or hierarchy-like organization
• users should navigate records through folders in addition to filters

Avoid it when:

• folder semantics are not part of the working model

settings

What it is:

• a structured settings object for advanced view configuration

How to configure it:

• in most cases, configure this through the Layout builder
• only edit it manually if you understand the stored structure and have a strong reason to do so

Why it matters:

• this field stores viewer-specific layout configuration
• it is where Jetstack persists layout-builder output

What it typically contains:

• layout
• viewerLayouts
• view-zone placement
• filter-zone placement
• custom buttons for layout zones
• zone settings
• advanced template configuration

Important practical rule:

• treat settings as a managed configuration object rather than a casual free-form notes field
• the layout builder sanitizes and normalizes its contents before storage

Use it when:

• you need advanced layout control beyond the basic scalar view options

Add-Time Context Injection

These options are what turn a view from a passive list into a contextual creation entry point.

adding_force_values

What it is:

• values that must be applied when creating an object from this view

How to configure it:

• provide a structured object where:
  • keys are property system names or property IDs
  • values are the forced values to apply

Example:

{
  "status": "Open",
  "department": 14
}

Why it matters:

• these values define hard context for creation from this view
• they are stronger than defaults because the creation flow should treat them as fixed

Use it when:

• a record created from this view must always belong to a certain status, parent, queue, department, or other fixed context

Difference from defaults:

• forced values are for non-negotiable context
• default values are for suggested starting values

adding_default_values

What it is:

• default values applied when a user starts creating an object from this view

How to configure it:

• provide an object where:
  • keys are property system names or IDs
  • values are the initial values to prefill

Example:

{
  "priority": "Normal",
  "country": "US"
}

Why it matters:

• defaults reduce repetitive input
• they still preserve user choice in cases where the field remains editable

Use it when:

• the view suggests a likely starting point but should not enforce it

adding_hidden_values

What it is:

• fields that should be hidden in the creation flow started from this view

How to configure it:

• provide an array of property system names or IDs

Example:

[
  "department",
  "status"
]

Why it matters:

• a view can quietly apply context and avoid showing fields that users do not need to adjust in that flow

Use it together with:

• adding_force_values when the hidden field should also be fixed
• adding_default_values when the hidden field should start with a value but remain context-driven

Design guidance:

• hide fields only when the context genuinely makes them unnecessary
• do not hide important business decisions that users still need to understand

Query Strategy In Views

The combination of query, relevant_queries, and persist_default_groups is one of the most important design areas of a view.

Use this pattern:

• query defines the main starting perspective
• relevant_queries define alternative perspectives in the same workspace
• persist_default_groups keeps structural grouping stable when that stability matters more than each query's own grouping defaults

This is a good fit for:

• work queues
• operational boards
• manager review screens

It is a poor fit for:

• unrelated report families that happen to target the same type

View Actions

view_actions

What it is:

• the configured list of actions available from the view

How to configure it:

• use the Actions editor action on the view
• the field itself is stored as structured data and is not intended to be hand-edited in normal use

Why it matters:

• view actions are often the main operational controls of the screen
• they can turn a passive list into an action-oriented workspace

Important runtime behavior:

• if no custom action configuration exists, the platform falls back to default system export actions
• for custom-query views, some export variants are intentionally omitted

Types of view actions:

• export actions
• automation actions
• canvas actions
• divider entries for visual grouping

Action Configuration Options

Each non-divider action can include the following practical settings.

Action title

What it controls:

• the user-facing label of the action

How to configure it:

• enter a clear verb-based label such as Assign, Open Dashboard, Run Check, or Export Current Result

Action type

What it controls:

• what kind of target the action invokes

How to configure it:

• choose automation when the action should run workflow logic
• choose canvas when the action should open or render a canvas-based surface

Action automation

What it controls:

• the automation target for automation-type actions

How to configure it:

• choose one automation in the actions editor

Use it when:

• the view should provide business operations such as assign, escalate, notify, enrich, or process

Action canvas

What it controls:

• the canvas target for canvas-type actions

How to configure it:

• choose one canvas in the actions editor

Use it when:

• the action should open a specialized interface, detail flow, or embedded experience

Action icon

What it controls:

• the icon displayed with the action

How to configure it:

• choose a meaningful icon that distinguishes the action visually

Action showCondition

What it controls:

• whether the action should be shown in the current runtime context

How to configure it:

• enter an expression that evaluates to a truthy or falsy result
• use the same expression approach described in Expressions

Why it matters:

• action visibility often depends on state, selection, permissions, or business conditions

Use it when:

• an action should only appear for certain object states or user situations

Action isAjax

What it controls:

• whether the action runs through AJAX behavior

How to configure it:

• enable it for in-place interactions
• disable it when the action should behave more like a full navigation or full page transition

Divider Actions

Divider entries do not execute anything. They exist only to visually separate action groups.

Use them when:

• a view has enough actions that grouping improves clarity

Layout Builder And Per-Viewer Layout

The view resource includes a dedicated Layout builder action. This is where the more advanced settings payload is normally managed.

What The Layout Builder Controls

The layout builder stores viewer-specific layout configuration such as:

• which view components are visible
• which filter components are visible
• where those components are placed
• which viewers have dedicated layouts
• advanced template configuration
• custom zone buttons

Why This Matters

The view's scalar fields tell Jetstack what the view is. The layout builder tells Jetstack how the chosen viewer should be composed.

That includes:

• title placement
• top button placement
• filter bar arrangement
• pagination visibility
• folders component placement
• tag component placement and tag editing availability
• calculations summary placement
• viewer selector availability

Working With Tags In The Layout Builder

When a view should expose tags, the layout builder works with two separate tag-related features.

Tag cloud

This is a view component that you place into one of the active view zones.

What it does:

• renders a tag-based search and filtering surface for the current view
• lets users narrow the current dataset by selected tags
• works as part of the view's filter and navigation layer

Use it when:

• users should filter the current view by tags
• tags should behave like a visible facet of the dataset

Inline tagging

This is not the same thing as the Tag cloud component. It is a separate layout option controlled by the Inline tagging switch in the layout builder.

What it does:

• shows the current tags directly on listed objects
• lets users click existing tags on objects
• enables the per-object tag management UI where the viewer and permissions allow it

Use it when:

• users should see tag assignments directly in rows or cards
• the view should support lightweight tagging as part of day-to-day work

Practical rule:

• use Tag cloud for filtering the dataset
• use Inline tagging for displaying and maintaining tags on individual objects

These two features are often used together, but they are configured separately and one does not automatically enable the other.

Runtime Viewer Switching

Views can support runtime viewer switching, but this is not purely a matter of setting viewer.

For runtime switching to work well:

• the target viewer should have a layout configuration
• the layout should include the viewer selector component where appropriate

This matters because the platform determines active runtime viewer options from the configured layout state, not only from the default viewer field.

Advanced Template Configuration

The layout builder also supports advanced template configuration.

Use it when:

• the standard slot-and-component layout is not expressive enough
• you need a more custom arrangement while still working inside the view system

In advanced template mode you write HTML directly and mark each view component with a [[token]] shortcode placeholder. The renderer replaces each known token with the rendered component and leaves unknown tokens intact as plain text.

Shortcode Tokens

Practical Rules

• duplicate tokens render only once — the second occurrence is dropped
• unknown tokens (typos, removed components) survive as plain text so the page never silently swallows content
• syntax is [[token]] with optional whitespace: [[ data ]] is equivalent to [[data]]
• the layout-builder editor offers autocomplete after typing [[
• the bracket form keeps these shortcodes visually distinct from {{...}} expression interpolation; tokens are layout placeholders, not expressions

Practical guidance:

• prefer the visual layout builder first
• use advanced template configuration only when the normal layout model is insufficient
• if you need a dynamic value inside the template, use {{...}} expression interpolation alongside the layout [[...]] tokens — they are processed by independent pipelines and do not interfere with each other; {{...}} expressions have the current View object as their context.

System Fields

These fields are mainly diagnostic or builder-supporting rather than day-to-day design controls.

id

What it is:

• the numeric internal identifier of the view

How to configure it:

• you do not configure it manually

Why it matters:

• it is useful for internal references, debugging, and synchronization diagnostics

view_code

What it is:

• a generated control snippet for rendering the view

How to configure it:

• you do not normally configure it manually

Why it matters:

• it represents the platform's render mask for the view control
• it is mainly useful as a system-level reference

created_on, updated_on, updated_by

What they are:

• system metadata about creation and last modification

How to configure them:

• they are managed by the platform

Why they matter:

• they help with auditability, troubleshooting, and implementation review

Common View Patterns

Stable Operational Queue

Configure:

• viewer = table or kanban
• one default query
• several relevant_queries
• persist_default_groups = true when grouping should stay stable
• clear showCondition rules on important actions

Use it for:

• support queues
• approval worklists
• order processing

Contextual Creation View

Configure:

• show_add_button = true
• contextual add_button_text
• adding_force_values for hard context
• adding_default_values for suggested context
• adding_hidden_values for fields users should not have to manage

Use it for:

• add task to project
• create issue in queue
• register expense in department

Calendar Planning View

Configure:

• viewer = calendar
• explicit_start_property and explicit_end_property when date roles are ambiguous
• a query suited to planning horizon and status scope

Use it for:

• bookings
• planned work
• deadlines and milestones

Folder-Aware File Or Document View

Configure:

• a suitable query
• root with the intended folders root
• useful custom column names
• creation defaults that respect folder context where needed

Use it for:

• document libraries
• structured case folders
• file-heavy operational surfaces

Design Questions To Ask Before Finalizing A View

• Is this view for monitoring, triage, editing, planning, or reporting?
• Should one query define the screen, or should several relevant queries share it?
• Should users create new records from this view?
• Which values should be forced, suggested, or hidden during creation?
• Does the view need folder navigation?
• Should actions appear all the time, or only when expressions say they are relevant?
• Does the view need simple layout composition or a more advanced layout-builder setup?

Best Practices

• Design each view around one primary job to be done.
• Put durable data logic in queries and presentation logic in views.
• Use relevant_queries for neighboring perspectives, not unrelated reports.
• Use adding_force_values only for context that truly must be fixed.
• Keep showCondition expressions readable and business-oriented.
• Treat settings as managed layout configuration, not as a casual manual object.
• When several roles use the same type differently, prefer separate views with role-specific availability.

Related Chapters

• Queries
• Query Parameters
• Expressions
• Canvases
• Types
• Folders And Roots