Button

An interactive button component that supports link navigation, page data source operations (record navigation, new record, mode switching), form submission, and custom JavaScript execution. Save/Delete actions must use a custom script with navigation. The component offers two visual variants and can enable or disable dynamically based on data context.

Use Cases

• Navigation buttons linking to pages or anchor sections
• 🚨 SAVE/DELETE buttons (MUST use custom-script with navigation – page-data-source removed!)
• Record navigation buttons (Next, Previous, First, Last)
• Form submission buttons
• Custom script execution buttons for complex workflows
• Call-to-action buttons (Sign Up, Get Started, Contact Us)

Properties

label

Button text displayed to user. Type: string. Required. Recommendations:

• action-verbs: Use action verbs: Save, Delete, Create, Submit, Navigate, Send
• clarity: Be specific: ‘Save Record’ not ‘Save’, ‘Delete Customer’ not ‘Delete’
• length: 2-3 words (20 characters max) for clear, scannable buttons

variant

Visual style variant indicating button importance/hierarchy. Type: string. Options: primary, secondary. Default: primary. Visual Impact:

• primary: Solid dark background (#1e293b), white text, prominent shadow. Visually dominant for main actions.
• secondary: Light gray background (#f1f5f9), dark text, subtle shadow. Less prominent for alternative actions.

• primary-actions: Use ‘primary’ for main actions: Save, Submit, Get Started, Sign Up, Create
• secondary-actions: Use ‘secondary’ for alternative actions: Cancel, Go Back, Learn More, View Details
• visual-hierarchy: One primary button per section, multiple secondary buttons allowed

actionType

Type of action button performs when clicked. Determines which additional properties are required. Type: string. Options: link, page-data-source, submit-form, custom-script. Default: link. Visual Impact: Controls button behavior on click. Link navigates, page-data-source performs data operations, submit-form submits forms, custom-script runs JavaScript.

actionTypeFields

Container object for action-specific configuration. Type: object. The available sub‑properties depend on the selected actionType:

• href (string) – Link destination used only when actionType='link'. Can be an anchor, relative path, or external URL.
• targetDataSource (string) – Page data source ID to operate on, required only when actionType='page-data-source'. Must reference a configured page data source.
• pageDataSourceAction (string) – Data operation to perform when actionType='page-data-source'. Options: navigate-next, navigate-previous, navigate-first, navigate-last, new-record, enter-edit-mode, enter-view-mode. Visual Impact details each action’s behavior. Recommendations:
  • navigation-buttons: Use navigate-next/previous for ‘Next’/‘Previous’ buttons in record browsing interfaces
  • save-delete-operations: 🚨 MUST use actionType='custom-script' for save/delete – page-data-source no longer supports these!
  • mode-switching: Use enter-edit-mode/enter-view-mode for ‘Edit’/‘Cancel’ buttons
• confirmMessage (string) – Confirmation dialog message used only when actionType='page-data-source' AND pageDataSourceAction='delete-record'. Default: “Are you sure you want to delete this record?” Recommendations: be specific, mention irreversibility, default message applies if omitted.
• customScript (string) – JavaScript code executed only when actionType='custom-script'. Runs in a restricted sandbox with access to page data sources via context.[dataSourceId]. Use context.[dataSourceId].getField() and .setField(). Security Note: No access to window, document, fetch, eval, or Function constructor.

customCss

Custom CSS styles for advanced styling. Parsed as CSS property‑value pairs. Type: string. Security Note: Parsed by cssParser utility; tenants only affect their own pages (multi‑tenant isolation enforced).

Best Practices

• 🚨 CRITICAL: For SAVE/DELETE operations, use actionType='custom-script' with navigation – page-data-source 'save-record' and 'delete-record' have been REMOVED!
• ALWAYS specify actionType based on button purpose (link, page-data-source, submit-form, or custom-script)
• All buttons should have smooth hover effects – use customCss for enhanced interactivity
• Primary CTAs can use subtle pulse animations for emphasis (celebrations only – NOT for business apps)
• Use customCss for hover states: ‘transition: transform 0.3s ease, box-shadow 0.3s ease; &:hover { transform: translateY(-2px); box-shadow: 0 8px 16px rgba(0,0,0,0.2); }’
• Use actionType='link' for simple navigation (pages, anchors, external URLs)
• Use actionType='page-data-source' ONLY for: navigate-next, navigate-previous, navigate-first, navigate-last, new-record, enter-edit-mode, enter-view-mode
• Use actionType='submit-form' for form submission buttons
• Use actionType='custom-script' for save/delete operations (MANDATORY!) and complex workflows
• Use variant='primary' for main actions (Save, Submit, Get Started)
• Use variant='secondary' for alternative actions (Cancel, Go Back, Learn More)
• Set confirmMessage for destructive actions (delete-record) to prevent accidental data loss
• Keep button labels action‑oriented (2-3 words: ‘Save Record’, ‘Next’, ‘Sign Up’)
• When using page-data-source actions, ALWAYS specify targetDataSource ID

Common Mistakes

🚨 CRITICAL: Using actionType='page-data-source' with pageDataSourceAction='save-record' or 'delete-record'

Why it's a problem: These actions have been PERMANENTLY REMOVED from the system! If you try to use them, the button will NOT work. Save/delete operations MUST use actionType='custom-script' with navigation back to list page for good UX.

Fix: ALWAYS use actionType='custom-script' for save/delete operations

CRITICAL: Using context.pageData or context.setPageData() - these APIs DO NOT EXIST

Why it's a problem: The correct API is context.[dataSourceId].getField() and context.[dataSourceId].setField(). Using pageData/setPageData causes runtime error: 'context.setPageData is not a function'

Fix: ALWAYS use context.[dataSourceId] API (NOT context.pageData or context.setPageData)

CRITICAL: Using actionTypeFields.script instead of actionTypeFields.customScript for custom-script buttons

Why it's a problem: The field name is 'customScript', not 'script'. Using 'script' breaks the button – code won’t display in editor and won’t execute at runtime.

Fix: ALWAYS use actionTypeFields.customScript (NOT actionTypeFields.script) for custom script code

Using actionType='page-data-source' without setting targetDataSource

Why it's a problem: Button doesn’t know which data source to operate on. Click does nothing.

Fix: Set actionTypeFields.targetDataSource to page data source ID (e.g., 'customerDetails')

Not setting confirmMessage for delete-record actions

Why it's a problem: Users can accidentally delete records with one click. No confirmation, permanent data loss.

Fix: Always set actionTypeFields.confirmMessage for delete-record actions (e.g., 'Are you sure you want to delete this customer?')

Using async operations in custom scripts without await

Why it's a problem: Operations like save(), delete(), navigateNext() are asynchronous. Without await, script continues before operation completes, causing race conditions.

Fix: Always use await for async operations: await context.customerDetails.save()

Trying to use window, document, or fetch in custom scripts

Why it's a problem: Custom scripts run in restricted sandbox for security. These APIs are blocked to prevent XSS attacks.

Fix: Use provided context API only. Access data sources via context.[dataSourceId], show alerts via context.alert()

Generic button labels like 'Click Here', 'Submit', 'Go'

Why it's a problem: Non‑descriptive labels don’t communicate what button does. Users hesitate to click unclear buttons.

Fix: Use specific, action‑oriented labels: 'Save Customer', 'Delete Order', 'Next Record', 'Create New'

Using variant='primary' for all buttons

Why it's a problem: When all buttons look important, none stand out. Users don’t know which action is primary.

Fix: Use variant='primary' for ONE main action per section, variant='secondary' for alternative actions

Not considering auto‑disable states for page-data-source buttons

Why it's a problem: Buttons like 'Next' should auto‑disable when no next record exists. Manual disable logic not needed.

Fix: Trust automatic disable logic: navigate-next disables when canNavigateNext=false, save-record disables when dirty=false or mode='view'