## Overview

This widget displays a button that runs a Low-Code script when clicked.

The Low-Code Button widget is an interactive widget that allows administrators and low-code developers to embed custom automation logic into cplace pages through a button interface. When clicked, the button executes a configurable JavaScript script that has access to contextual data from the page, connected widgets, and data sources.

The widget bridges the gap between no-code page building and full custom development by providing a scriptable button interface with rich access to page data, search results, and user selections.

## Use Cases

### Data Processing and Transformation
Execute custom business logic to process or transform data on the current page or related entities:
- Calculate and update aggregate values across multiple pages
- Transform data formats or structures
- Apply custom validation rules
- Generate derived data based on complex business rules

### Bulk Operations on Selected Items
Perform actions on multiple items selected in a connected table widget:
- Bulk update attributes across selected pages
- Mass approve/reject workflow items
- Batch delete or archive records
- Apply consistent changes to a selection of entities

### External System Integration
Trigger integrations with external systems or services:
- Call external APIs to synchronize data
- Send notifications to external systems
- Export data to external formats
- Import data from external sources

### Workflow and Process Automation
Automate workflow steps and business processes:
- Trigger state transitions
- Start background jobs for long-running processes
- Execute multi-step approval processes
- Orchestrate complex business workflows

### Report Generation and Data Export
Generate custom reports or export data:
- Create formatted reports based on search results
- Export data in custom formats
- Generate summary statistics
- Create audit logs or change histories

### User Interaction with Confirmation
Present users with action buttons that require confirmation:
- Delete operations requiring user confirmation
- Critical actions that need explicit approval
- Operations that collect additional input before execution

## Operating Modes

### Synchronous Execution
Script runs in the current request context:
- Limited to default script timeout (typically 60 seconds)
- Suitable for quick operations that need immediate feedback
- Log output is not displayed to the user
- Script completes before page control returns to user

### Asynchronous Execution (Default)
Script runs as a background job:
- A background job is created and tracked
- Users receive a link to monitor job progress
- Script output via `log.logText()` and `log.logHtml()` is captured in the job log
- Suitable for long-running operations
- User can continue working while script executes

## Design Considerations

### When to Use This Widget

Use the Low-Code Button widget when you need to:
- Execute custom business logic that cannot be achieved with standard cplace features
- Automate repetitive tasks directly from the page interface
- Integrate with external systems through custom code
- Process multiple items based on user selection
- Provide users with action buttons that execute context-specific logic

### Data Source Options

The widget supports multiple ways to provide data to the script:

**Search-based**: Define a search query whose results are available as the `pages` binding. Use when you need to process a dynamic set of pages matching specific criteria.

**Connected Table**: Connect to a table widget on the same page to process selected rows. Use when users need to explicitly select which items to process. Supports nested connected tables for complex scenarios.

**Manual Selection**: Manually select specific pages to provide as the `pages` binding. Use when the set of pages is fixed and known at configuration time.

**All Search Results**: Provides raw search results (not just pages) in the `searchResults` binding. Use when you need access to search metadata beyond just the page objects.

### Script Structure Requirements

Every Low-Code Button script must return an object with two methods:

**`checkAccess()`**: Controls button availability based on context. Evaluated when the page loads. Returns `true` to enable the button, `false` to disable it. Does not have access to the `log` binding.

**`call()`**: Contains the actual business logic executed when the button is clicked. Has access to all script bindings including the `log` binding for user output. Can optionally return a success message or job ID.

### Integration with Other Widgets

The Low-Code Button widget can be:
- **Embedded in**: Attribute Group widgets or Connected Attribute Group widgets
- **Connected to**: Embedded Search as Table widgets (to access selected rows)
- **Nested**: Can work with connected tables that are themselves connected to other tables

### User Interaction Enhancements

**Confirmation Dialogs**: Prompt users before script execution for critical operations. Customizable message and button labels.

**Additional Data Collection**: Display a dialog to collect additional input before script execution. Configure any cplace type to define the input fields needed.

## Common Pitfalls

- **Synchronous timeout**: Synchronous execution is limited to 60 seconds by default. Use asynchronous mode for long-running operations.
- **Access control oversight**: The `checkAccess()` method is only evaluated on page load, not on every click. Dynamic conditions should be rechecked in the `call()` method if needed.
- **Missing data source**: Scripts expecting the `pages` binding will fail if no data source is configured.
- **Log output ignored**: In synchronous mode, `log.logText()` and `log.logHtml()` output is not displayed to users.

## Testing Before Embedding

Before embedding a Low-Code Button widget into a rich string attribute, test your cplaceJS script independently to verify it works correctly.

**Recommended workflow:**
1. Write your cplaceJS script (with `checkAccess()` and `call()` methods)
2. Test the `call()` logic using `cplace_execute_script` with a representative page as the context page
3. Verify the script executes without errors and produces the expected result
4. Only then embed the widget via `cplace_richstring_insert_widget` with the tested script in the properties

**Why this matters:** A script with errors will produce a broken button once embedded. Debugging scripts inside embedded widgets is significantly harder than debugging them standalone, because the embedded widget rendering does not surface script errors clearly.

## Permissions and Access Control

- **Embedding Permission**: Only users with "Low-Code permission" (`GlobalPermissions.mayEditLowCode()`) can embed this widget
- **Script Editing**: The script attribute is only visible/editable to users with Low-Code permission
- **Runtime Access Control**: The `checkAccess()` method provides dynamic access control based on context

## Related Widgets

### Low-Code Text Widget
Displays computed text/HTML instead of executing actions. Both widgets share similar data source configurations and script bindings but serve different purposes:
- **Low-Code Button**: Imperative, user-triggered actions
- **Low-Code Text Widget**: Declarative, auto-updated display

### Embedded Search as Table
Often used as a connected data source for the Low-Code Button. The table widget provides the selection of pages that the button script processes.

### Attribute Group Widgets
Common embedding containers for Low-Code Button widgets, allowing the button to be positioned alongside other page content.

### Low-Code Widget Builder (Embedded Widget)
Consider the **Low-Code Widget Builder** instead when you need more than a single button — a full custom widget with its own HTML/CSS/JS, client-side interactivity, and write-back. Those widgets are authored in the Widget Builder (as `cf.cplace.lowCodeWidget.widgetDefinition` pages) and placed via the Embedded Widget (`cf.cplace.lowCodeWidgetBuilder.embeddedWidget`). The Low-Code Button remains the right choice for a single user-triggered action.