# Frontend Commands {% hint style="info" %} Frontend Commands are available on all [Beefree SDK paid plans](https://developers.beefree.io/pricing-plans). {% endhint %} ## Overview Frontend Commands let you control the builder’s user interface programmatically. You can focus on specific elements, scroll to parts of the UI, highlight areas temporarily, or select content on the stage. These commands help you build guided experiences, automate QA checks (when couple with the [Content Services API Check endpoints](https://docs.beefree.io/beefree-sdk/~/changes/480/apis/content-services-api/check)), or create onboarding flows by directing attention exactly where it’s needed—whether on the stage or in the sidebar. **Available actions:** * [**Focus**](#focus-1) – Move focus to a specific element. * [**Scroll**](#scroll) – Navigate to a precise part of the editor. * [**Highlight**](#highlight) – Briefly emphasize a target element. * [**Select**](#select) – Choose a row or module within the template. * [Tab](#tab) - Navigate to a specific tab within the builder. Options include: **Settings**, **Content**, and **Rows**. {% hint style="info" %} **Important:** You can use Frontend Commands to navigate to elements with the entire builder. This includes the stage and the sidebar. For example, if you want to navigate to an image on the stage missing alt text, and then indicate on the sidebar where the end user can add the alt text, both are possible with Frontend Commands. {% endhint %} ## Method The `execCommand` method is the central function used to trigger any Frontend Command within Beefree SDK. It allows you to execute one of the following supported actions: * `focus` * `scroll` * `highlight` * `select` * `tab` ## Target Object The target object is an important concept within Frontend Commands. It defines where in the UI the Frontend Command should act. It specifies the exact element—on the stage or in the sidebar—that the action should interact with. Depending on the action being performed, certain target fields are required. The following table provides a comprehensive reference of the target options, examples values, and a description including which actions correspond with the target option. | Target Options | Example Values | Descriptions | | ------------------------- | ------------------------------ | ------------------------------------------------------------------------------- | | `key` | `'font-weight'` | For sidebar controls (used in `focus`, `scroll`, `highlight`) | | `selector` | `'.my-element-class'` | For DOM elements (used in `focus`, `scroll`) | | `uuid` | `'abc123-uuid-value'` | For modules or rows (used in `scroll`, `highlight`, `select`) | | `row`, `column`, `module` | `row: 2, column: 1, module: 3` | For a specific module via coordinates (used in `scroll`, `highlight`, `select`) | | `target` | `settings`, `rows`, `content` | Navigate to a specific tab within the sidebar of the builder. | ## How Actions Work Each Frontend Command is executed using a consistent structure. Here's how to construct and use them: 1. **Define the SDK instance**: Use the Beefree SDK instance you’ve initialized (e.g., `beeInstance`). 2. **Use the `execCommand` method**: This method is used to trigger all Frontend Commands. 3. **Specify the action**: Pass one of the four supported action strings: `"focus"`, `"scroll"`, `"highlight"`, or `"select"`. 4. **Define the `target` object**: This object determines where in the editor the action applies. Depending on the action, you may use `key`, `selector`, `uuid`, or coordinates in the form of `row`, `column`, and `module`. The following code snippet provides an example of scrolling to a button in the DOM: ```javascript beeInstance.execCommand('scroll', { target: { selector: 'button' } }); ``` The following sections include comprehensive steps and examples on how to use each action and target with the `execCommand` method. ## Focus The focus command will set the focus on the first focusable DOM element based on the passed target. The target can be defined with a `key` or a `selector`; either one or the other is mandatory. If both are provided, the `selector` will be used. ### Details The following table provides additional details on the options you can use to define a target for the focus action using the `execCommand` method. | Field | Type | Mandatory | Description | | ---------- | ------ | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `selector` | string | `true` (mutually exclusive with `key`) | An actual valid CSS selector. If it matches, it will set the focus on the first focusable element (itself or a child element). | | `key` | string | `true` (mutually exclusive with `selector`) | A reference to a sidebar property, usually matching the label shown in the UI but converted to kebab-case (e.g., **Line height** → `line-height`). The exact value can be found in the DOM within the `data-qa` attribute. | ### How to Use Focus Take the following steps to focus on a specific element in the builder: 1. Identify the element you want to focus on, using either a CSS selector or a sidebar control key. 2. Call the `execCommand` method on the Beefree SDK instance. 3. Set the action to `"focus"` and define the `target` using either the `selector` or `key`. #### Examples To focus on the selected row toolbar: ```javascript beeInstance.execCommand('focus', { target: { selector: '.row-actions-toolbar--cs' } }); ``` Which results in the visual cue displayed in the following image:
To focus on the “line height” property in the sidebar: ```javascript beeInstance.execCommand('focus', { target: { key: 'line-height' } }); ``` Which results in the visual cue displayed in the following image:
### Handle Focus Errors If no element matches the provided `selector` or `key`, Beefree SDK throws the following error: ```json { "code": 7040, "detail": { "selector": "[data-qa=\"line-height\"]" }, "message": "Element not found with selector [data-qa=\"line-height\"]", "name": "elementNotFound" } ``` * **What it means:** The target element isn’t present in the DOM at execution time. * **How to fix:** Make sure the element exists and is visible before calling the command. ## Scroll The scroll command will scroll to the passed target position. The target can be defined with a `key`, a `selector,` coordinates (`row`, `column`, `module`), or `uuid`. Either the `key`, the `selector`, the `uuid`, or the coordinates need to be defined. ### Details The following table provides additional details on the options you can use to define a target for the scroll action using the `execCommand` method. | Field | Type | Mandatory | Description | | ---------- | ------ | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `key` | string | `true` (mutually exclusive with `row` and `selector`) | A reference to a sidebar property, usually matching the label shown in the UI but converted to kebab-case (e.g., **Line height** → `line-height`). The exact value can be found in the DOM within the `data-qa` attribute. | | `selector` | string | `true` (mutually exclusive with `key` and `row`) | An actual valid CSS selector. If it matches, it will scroll to the found element. | | `row` | number | `true` (mutually exclusive with `key` and `selector`) | The positional number of the row to scroll to or the row the final target is in. | | `column` | number | `true` if `module` is defined | The positional number of the column the module is in. | | `module` | number | `true` if `column` is defined | The positional number of the module to scroll to. | | `uuid` | string | `true` if none of the coordinates are defined | The unique identifier of the target (row or module). | ### How to Use Scroll Take the following steps to scroll to a specific part of the editor: 1. Determine what you want to scroll to—this can be a sidebar property, a DOM element, a row/module via coordinates, or an element via UUID. 2. Call the `execCommand` method on the Beefree SDK instance. 3. Set the action to `"scroll"` and define the `target` appropriately. #### Examples To scroll to the 3rd module of the 1st column in the 2nd row: ```javascript beeInstance.execCommand('scroll', { target: { row: 2, column: 1, module: 3 } }); ``` To scroll to an element using a UUID: ```javascript beeInstance.execCommand('scroll', { target: { uuid: 'a123abcd-0a01-12a1-12a0-a12b3456789c' } }); ``` To scroll to the “Font weight” property in the sidebar: ```javascript beeInstance.execCommand('scroll', { target: { key: 'font-weight' } }); ``` To scroll to a button: ```javascript beeInstance.execCommand('scroll', { target: { selector: 'button'} }); ``` ### Handle Scroll Errors If the target isn’t found, the following error is returned: ```json { "code": 7030, "name": "entityNotFound", "message": "Entity at target {\"row\":4} not found", "detail": { "target": { "row": 4 } } } ``` * **What it means:** The specified row, UUID, key, or selector does not match any element. * **How to fix:** Double-check that the coordinates or identifiers are correct and that the content is rendered. ## Highlight The highlight command will highlight the passed target for three seconds. The target can be defined with a `key`, coordinates (`row`, `column`, `module`), or `uuid`. Either the `key`, the `uuid`, or the coordinates need to be defined. ### Details The following table provides additional details on the options you can use to define a target for the highlight action using the `execCommand` method. | Field | Type | Mandatory | Description | | -------- | ------ | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `key` | string | `true` (mutually exclusive with `row`) | A reference to a sidebar property, usually matching the label shown in the UI but converted to kebab-case (e.g., **Line height** → `line-height`). The exact value can be found in the DOM within the `data-qa` attribute. | | `row` | number | `true` (mutually exclusive with `key`) | The positional number of the row to highlight or the row the final target is in. | | `column` | number | `true` if `module` is defined | The positional number of the column the module is in. | | `module` | number | `true` if `column` is defined | The positional number of the module to highlight. | | `uuid` | string | `true` if none of the coordinates are defined | The unique identifier of the target (row or module). | ### How to Use Highlight Take the following steps to temporarily highlight a specific element: 1. Identify the element using a `key`, `uuid`, or `coordinates`. 2. Call the `execCommand` method on the Beefree SDK instance. 3. Set the action to `"highlight"` and define the `target`. #### Examples To highlight the 3rd module of the 1st column in the 2nd row: ```javascript beeInstance.execCommand('highlight', { target: { row: 2, column: 1, module: 3 } }); ``` Which results in the visual cue displayed in the following GIF:
To highlight an element by UUID: ```javascript beeInstance.execCommand('highlight', { target: { uuid: 'a123abcd-0a01-12a1-12a0-a12b3456789c' } }); ``` Which results in the visual cue displayed in the following GIF:
To highlight the “Font weight” sidebar control: ```javascript beeInstance.execCommand('highlight', { target: { key: 'font-weight' } }); ``` Which results in the visual cue displayed in the following GIF:
### Handle Highlight Errors If no element matches the target, the following error is returned: ```json { "code": 7030, "name": "entityNotFound", "message": "Entity at target {\"row\":4} not found", "detail": { "target": { "row": 4 } } } ``` * **What it means:** The target (via coordinates, key, or UUID) doesn’t point to a valid element. * **How to fix:** Verify that the target refers to an existing and rendered element. ## Select The select command will select the passed target position module or row. The target can be defined with coordinates (`row`, `column`, `module`). ### Details The following table provides additional details on the options you can use to define a target for the select action using the `execCommand` method. | Field | Type | Mandatory | Description | | -------- | ------ | ----------------------------------------------------- | ----------------------------------------------------------------------------- | | `row` | number | `true` (mutually exclusive with `key` and `selector`) | The positional number of the row to select or the row the final target is in. | | `column` | number | `true` if `module` is defined | The positional number of the column the module is in. | | `module` | number | `true` if `column` is defined | The positional number of the module to select. | | `uuid` | string | `true` if none of the coordinates are defined | The unique identifier of the target (row or module). | ### How to Use Take the following steps to select a specific module or row on the stage: 1. Choose the target element using coordinates (`row`, `column`, `module`) or a `uuid`. 2. Call the `execCommand` method on the Beefree SDK instance. 3. Set the action to `"select"` and define the `target`. #### Examples To select the 3rd module of the 1st column in the 2nd row: ```javascript beeInstance.execCommand('select', { target: { row: 2, column: 1, module: 3 } }); ``` To select an element using a UUID: ```javascript beeInstance.execCommand('select', { target: { uuid: 'a123abcd-0a01-12a1-12a0-a12b3456789c' } }); ``` ### Handle Select Errors When the element can’t be located, the following error is thrown: ```json { "code": 7030, "name": "entityNotFound", "message": "Entity at target {\"row\":4} not found", "detail": { "target": { "row": 4 } } } ``` * **What it means:** The given coordinates or UUID don’t resolve to any element in the template. * **How to fix:** Ensure the target exists in the current template and the row/module indexes are accurate. ## Tab The tab command will open the specified tab in the Beefree SDK editor. The target must be defined as one of the supported tabs: **settings**, **rows**, or **content**. ### Details The following table provides additional details on the options you can use to define a target for the tab action using the `execCommand` method. | Option | Type | Description | | -------- | ------ | ------------------------------------------------------------------------------------ | | `target` | String | The tab you want to open. Supported values are: `"settings"`, `"rows"`, `"content"`. | ### How to Use Take the following steps to switch to a specific tab in the Beefree SDK editor: 1. Choose the target tab by specifying one of the valid values: `"settings"`, `"rows"`, or `"content"`. 2. Call the `execCommand` method on the Beefree SDK instance. 3. Set the action to `"tab"` and define the target. #### Examples To open the **Settings** tab: ```javascript beeInstance.execCommand('tab', { target: 'settings' }); ``` To open the **Rows** tab: ```javascript beeInstance.execCommand('tab', { target: 'rows' }); ``` To open the **Content** tab: ```javascript beeInstance.execCommand('tab', { target: 'content' }); ``` ### Handle Tab Errors When working with the **tab** action, two types of errors may occur: * **Invalid Target:** An error is thrown for any value that is not one of the supported options (`settings`, `rows`, `content`). * **What this means:** You passed a target that does not exist. * **How to fix:** Double-check that the target is exactly `"settings"`, `"rows"`, or `"content"`. * **Locked or Unavailable Tab:** An error is thrown if the requested sidebar tab is currently locked or unavailable. * **What this means:** The editor is preventing access to that tab due to configuration, user permissions, or current editing state. * **How to fix:** Verify that the tab is enabled in the editor configuration and that you have permission to open it. Try again once it becomes available.