PageRoot

Page‑level configuration stored in puckData.root.props. It controls page metadata, data sources, form settings, and overall page behavior. These properties apply to the entire page and are separate from component‑level props.

Use Cases

• Configure page metadata (title, description, SEO)
• Define page data sources for data binding
• Mark pages as forms with decorative backgrounds
• Enable autoresponder for form submissions
• Configure after‑submit actions (thank‑you page, redirect)
• Set up duplicate prevention for form submissions
• Apply page‑level custom CSS
• Run JavaScript on page load (e.g., read URL query parameters and pre‑fill form fields)

Properties

pageDataSources

Array of data source configurations for this page. Each data source connects to a data table and can be referenced by components (Grid, Input, etc.) for data binding. Type: array.

Tip: Use descriptive IDs (e.g., ‘customersList’, ‘productDetails’, ‘orderEditor’). Use ‘list’ for tables/grids, ‘detail’ for view/edit forms. Each data source ID must be unique within the page.

pageTitle

Page title for SEO and browser tab. Displayed in search results and browser tabs. Type: string.

Tip: Keep length 50‑60 characters for optimal SEO, include brand name and page purpose, and ensure each page has a unique title.

pageDescription

Page description for SEO meta tags. Displayed in search results as page snippet. Type: string.

Tip: Keep length 150‑160 characters for optimal SEO, include a call‑to‑action or value proposition, and incorporate relevant keywords naturally.

customCss

Page‑level custom CSS applied to the entire page. Use for global styles, overrides, or page‑specific theming. Type: string.

Tip: CSS is scoped to the tenant’s page – multi‑tenant isolation enforced.

isFormPage

Indicates if this page is marked as a form page. Set to true when using markAsFormPage() method. Form pages can have decorative backgrounds (gradient, image) and different layout constraints. Type: boolean. Default: false.

formBackground

Form background configuration set via markAsFormPage() method. Controls decorative background for form‑only pages. Type: object.

Tip: Use gradient backgrounds for modern, professional standalone forms; use image backgrounds for event registrations or landing pages with visual theme; use solid backgrounds when the form is embedded in a normal page with Navbar/Footer.

backgroundType

Type of background: ‘solid’ allows normal layout, ‘gradient’ or ‘image’ creates form‑only layout with floating card. Type: string. Options: solid, gradient, image.

gradientStart

Gradient start color (hex) – only used when backgroundType='gradient'. Type: string.

gradientEnd

Gradient end color (hex) – only used when backgroundType='gradient'. Type: string.

backgroundImage

Background image URL – only used when backgroundType='image'. Type: string.

backgroundBlur

Apply blur effect to background image – only used when backgroundType='image'. Type: boolean. Default: false.

backgroundOverlay

Overlay darkness percentage (0‑100) – only used when backgroundType='image'. Type: number. Default: 30.

autoresponder

Autoresponder configuration set via setAutoresponder() method. Sends automated email to user after form submission. Type: object.

Tip: Ensure emailField matches the name of an Input component with type='email'. Keep subject and message professional and concise, and set clear expectations about response time.

enabled

Enable/disable autoresponder. Type: boolean.

emailField

Name of form field containing user’s email address. Type: string.

subject

Email subject line. Type: string.

message

Email body content. Type: string.

afterSubmitAction

After‑submit action configuration set via setAfterSubmitAction() method. Controls what happens after form submission. Type: object.

Tip: Use ‘thank-you’ action type for most forms – provides immediate feedback. Use ‘redirect’ for multi‑step forms or when integrating with external systems. Make thank‑you messages specific and reassuring.

actionType

Action type: ‘thank-you’ shows message overlay, ‘redirect’ navigates to URL. Type: string. Options: thank-you, redirect.

thankYouTitle

Thank‑you overlay title – only used when actionType='thank-you'. Type: string.

thankYouMessage

Thank‑you overlay message – only used when actionType='thank-you'. Type: string.

redirectUrl

Redirect URL – only used when actionType='redirect'. Type: string.

duplicatePrevention

Duplicate prevention configuration set via preventDuplicates() method. Prevents duplicate form submissions. Type: object.

Tip: Use ‘email’ for forms collecting user information (contacts, registrations), ‘ip’ for surveys or polls where email may not be collected, and ‘session’ for one‑time forms like giveaways or contests.

enabled

Enable/disable duplicate prevention. Type: boolean.

method

Detection method: ‘email’ checks for duplicate email addresses, ‘ip’ checks IP address, ‘session’ allows one submission per browser session. Type: string. Options: email, ip, session.

onPageLoad

JavaScript code that runs once when the page loads and all data sources are ready. Has full access to data sources (context.queryName.setField/getField), navigation (context.navigate), browser APIs (window, document, localStorage), and URL query parameters. Common use case: reading URL query parameters to pre‑fill form fields. Type: string.

Tip: Script runs AFTER all data source queries have loaded, so setField() calls work reliably. Use URLSearchParams to read query parameters passed from other pages. Access data sources via context.queryName (same API as button scripts).

Best Practices

• Always set pageTitle and pageDescription for SEO
• Define pageDataSources array for any page that displays or edits data
• Use markAsFormPage() with gradient or image backgrounds for standalone forms
• Enable autoresponder only on forms that collect email addresses
• Set afterSubmitAction to provide clear feedback after form submission
• Use preventDuplicates on forms where duplicate submissions should be blocked

Common Mistakes

Looking for autoresponder in component properties (Button, Input, etc.)

Why it's a problem: Autoresponder is a PAGE‑LEVEL setting configured via setAutoresponder() method, not a component property

Fix: Access autoresponder via root.props.autoresponder or use setAutoresponder() method on page object

Not setting emailField when enabling autoresponder

Why it's a problem: Autoresponder needs to know which form field contains the user’s email address

Fix: Always specify emailField parameter: page.setAutoresponder(true, 'email', 'Subject', 'Message')

Enabling autoresponder on pages without email field

Why it's a problem: Autoresponder requires an Input component with type='email' to send emails to users

Fix: Only enable autoresponder on forms that collect email addresses

Using markAsFormPage() on pages with complex layouts

Why it's a problem: Gradient/image backgrounds create form‑only layout – no Navbar, Hero, Footer allowed

Fix: Use backgroundType='solid' if page needs Navbar/Footer, or use ‘gradient’/‘image’ only for standalone forms

Not defining pageDataSources when components reference data sources

Why it's a problem: Components like Grid and Input need pageDataSources array to bind to data

Fix: Define pageDataSources array in root.props before adding data‑bound components