Configure Field Layouts and Global Code

Field Layouts change how field values look when users view them. Global Code applies CSS across pages that match your rules. Neither feature changes field editors, permissions, validation, actions, or history.

Who this is for

Workspace administrators and team members with the Manage Advanced Settings permission who configure field displays or workspace styles.

Before you begin

• Choose an existing field and page where you can check the finished layout.
• Prepare sample JSON without real customer information.
• Decide whether the design should apply broadly or only to specific pages, fields, roles, people, or themes.
• Plan to check the result in both light and dark themes.

Create a field layout

1. Open Settings, then System, then Field Layouts (/settings/app/layouts (opens in new tab)).
2. Select New layout.
3. Enter a Name and optional Description, then select Create.
4. Open Settings in the editor. Choose the Render scope and Priority, then select Save settings.
5. Add shortcode markup on Template and optional CSS on Styles.
6. Add safe test data on Sample, check the result on Preview, and narrow its reach on Rules.
7. Resolve any validation messages, then select Save draft or Publish.

AgencyTitan creates a stable key with the layout. Field definitions and marketplace packages can use that key to refer to the layout without relying on its display name.

Expected result

The layout shows a Published status and changes matching field displays. Draft changes do not affect the published version until you publish again.

Value only and full field scopes

Value only is the default. It replaces the value area while AgencyTitan continues to show the field label, prefix, suffix, and help text.

Full field controls the visible label, value, prefix, suffix, and help text. AgencyTitan still controls Edit, Copy, History, validation, permission checks, and the field editor. In a table, the layout supplies the complete cell display without adding a separate label.

Fields that support click to edit use the custom layout while idle, switch to the standard editor during editing, and return to the layout after you save or cancel. Fields that are always editable keep the standard editor.

Precedence

When more than one source specifies a layout, AgencyTitan uses the first explicit choice in this order:

1. Layout instance override
2. Field definition override
3. Custom object type default, for composite custom fields only
4. First matching workspace rule by priority
5. Built-in field display

Inherit continues to the next source. Use built-in stops the search and uses the standard AgencyTitan display. AgencyTitan does not combine the template or style code from two layouts. A closer list setting replaces an inherited list.

Template syntax

Field Layouts use AgencyTitan shortcode syntax, not Liquid, Handlebars, JavaScript, or Vue.

<article class="account-card">
  <strong>{{field.field_label}}</strong>
  <span>{{formattedValue}}</span>
  {{#if record.account_owner}}
    <small>Owner: {{record.account_owner}}</small>
  {{else}}
    <small>Owner not assigned</small>
  {{/if}}
</article>

Use {{path}} for an escaped value, {{#if expression}}...{{else}}...{{/if}} for conditions, and {{#each items}}...{{/each}} for lists. A value inserted by a shortcode is treated as data, not as more template instructions.

Available data

• value and raw contain the stored field value.
• formattedValue contains the standard AgencyTitan display value.
• field contains field details and options.
• record, client, and process contain values already available on the current page.
• route and display describe the current page and display mode.
• currentUser and tenant contain approved display details such as role, formatting preferences, theme, and timezone.
• items is the normalized list form.
• components contains normalized custom object components when available.

Templates do not load more data. If the current page has not loaded a value, referring to its path does not load it.

Each item in items provides value, formattedValue, label, index, first, last, and raw:

<ul>
  {{#each items}}
    <li>{{index}}. {{label}}: {{formattedValue}}</li>
  {{/each}}
</ul>

Nested custom objects include component details with raw and formatted values. Use nested loops and conditions to handle one value, several records, or nested records without depending on how they are stored.

Formatting helpers

Open Helpers in the editor to copy a supported data path or helper. These helpers use workspace formatting preferences where applicable.

Purpose	Examples
Date and time	{{date value}}, {{datetime value}}
Numbers and money	{{number value 2}}, {{currency value}}
Common field formats	{{phone value}}, {{duration value}}, {{file_size value}}
Files	{{file_url record.field_key}}, {{file_name value}}, {{#each file_list(record.field_key)}}...{{/each}}
Choice and reference labels	{{choice_label value field.options.options}}, {{reference_label value}}
Text and defaults	{{fallback value "Not set"}}, {{truncate value 60}}, {{uppercase value}}, {{lowercase value}}, {{titlecase value}}
Lists and inspection	{{join value ", "}}, {{json value}}
Rich content	{{rich_content value}}

Normal interpolation is HTML escaped. Use rich_content only for content that should be displayed as rich content after safety checks. Triple brace raw output is not supported.

Matching rules

Rules can target the route, app surface, user, role, department, permission, theme, record scope, field type, field key, field ID, and display context.

• Rules are checked in priority order. The first matching field layout wins.
• Values in one Include list use OR behavior.
• A group can require all conditions with AND or any condition with OR.
• A matching Exclude always wins over Include.
• all_pages matches every route after AgencyTitan identifies the workspace.

Use a surface condition to distinguish the signed-in app, portal, and public forms. When no field, layout, or custom object override is selected, matching workspace rules take their place in the precedence order.

Global Code

1. Open Settings, then System, then Global Code (/settings/app/global-code (opens in new tab)).
2. Select New style.
3. Enter a Name and optional Description, then select Create.
4. Add CSS on Styles. Use Insert common selector when you want one of the selectors listed by AgencyTitan.
5. Add narrow conditions on Rules and set its Priority in Settings.
6. Resolve any validation messages, then select Save draft or Publish.

Global Code accepts CSS only. Every published, enabled style with matching rules is applied in priority order. Published CSS can affect every matching workspace user and page, so begin with narrow rules and check both light and dark themes.

Global Code stays in your workspace and is not included with marketplace apps or templates.

Design with AI

Describe the change you want in the AI panel beside the editor. For a Field Layout, AI can use the current draft, the documented data paths and helper names, and your sample JSON. It does not receive live record values or customer information by default.

An AI result changes only the open, unsaved draft. Review the changed template, styles, sample data, and rules. Check the preview and validation messages before you select Save draft or Publish.

Publish, disable, and roll back

Publish makes the current draft active and adds a read-only revision to Revision history. Disable stops a published layout or style from displaying without removing its history.

To roll back, open Revision history, choose the version you need, and select Restore as current. Review the restored draft, then select Publish to make it active.

Layouts imported by name arrive as disabled drafts. A user with Manage Advanced Settings must review and publish them before they can change field displays.

Troubleshooting

What you see	What to check
The built-in field display appears	Confirm the layout is Published and enabled. Check precedence, Rules, and any validation messages. A Use built-in choice takes priority over lower sources.
A named layout is unavailable	Publish the layout and confirm the field or package refers to the correct stable key.
A rule does not match	Check the current route and surface, each condition group, and the rule priority. A matching Exclude wins over Include.
Layout styles do not apply	Resolve unsupported CSS or blocked content. Field Layout CSS is limited to that layout. Use Global Code only for intentional workspace-wide effects.
A list or custom object is empty in the preview	Check the structure of your sample JSON. Use items or components instead of assuming how the value is stored.
Publish is unavailable	Resolve the validation messages or wait for the AI change to finish. If authoring controls are missing, ask an administrator for Manage Advanced Settings.

Security boundary

Custom JavaScript is not supported. Script tags, inline event handlers, executable URLs, CSS imports, and other unsafe content are removed or rejected. Links, forms, images, and embeds are checked before AgencyTitan displays them.