Using the editor

This is your code editor. Using Python, you can customize your form's code extensively to produce the functionality you want. Based on the components you chose in the UI builder, their layout and their individual property values and settings, the builder will automatically generate a base code structure that outlines your form. You can use this and build on it as you like by manipulating the existing code or using any of your custom variables.

Above the code editor, you have two buttons that you can use: Regenerate and Run.

Run

To test your code after editing, you must click Run to update the form preview.

Regenerate

After your form's base code is generated, when you make changes to your form in the UI builder, the code editor will be modified accordingly. Clicking Regenerate will replace the code with an initial state based on the updated form UI. If there are any lines of custom code that you want to keep, make sure to have a copy of them with you before regenerating the code editor.

Component Path

Each component is accessed through its own unique path. In the case of a component that isn't placed in any group, the path is simply one element array containing the component’s ID:

['component_id']

If a component is placed within a group, the component's path is an array of the parent group's ID, the group's row index, and the component's ID:

['parent_group_id', <group_row_index>, 'component_id']

If a component is placed within a nested group (group_1 -> group_2 -> group_3), the component's path is an array of the parent group's IDs, the group's row indexes, and the component's ID:

['group_1', <group_1_row_index>, 'group_2', <group_2_row_index>, 'group_3', <group_3_row_index>, 'component_id']

-1 index points to the last row of the group:

['parent_group_id', -1, 'component_id']

Try in Playground

Event Handlers

Event handlers are special functions that allow users to add custom functionality on user-triggered and other events.
Event handler function name should have a strict format:

on_<component id>_<event type>

There are four types of events:

  • Component value change event - event type = change, in this case the function receives two arguments:
    • path - the path of the trigger component
    • value - updated value of the trigger component
  • Button click event - event = click, in this case the function receives one argument:
    • path - the path of the trigger button
  • Message event - event = message, in this case the function receives two arguments:
    • path - the path of the trigger component
    • value - received message from the trigger component
  • Group row deleted event - event type = deleted, this event is fired when a row in a group is being deleted by pressing X button. The handler function receives one argument:
    • path - the path of the trigger row
  • pre_hook() - Fired when an item is being opened in the editor.
  • post_hook() - Fired when an item is being closed in the editor.

Example:

### Value change event handler of the component with "prompt" id
def on_prompt_change(path, value):
   ### your custom code
   return

### Button click event handler of the button with "submit" id
def on_submit_click(path):
   ### your custom code
   return

### Message event handler of the component with "custom_web_component" id
def on_custom_web_component_message(path):
   ### your custom code
   return

### Group row deleted event handler of the component with "my_group" id
def on_my_group_deleted(path):
   ### your custom code
   return

Custom functions

In the code editor, you can use following custom functions:

  • getValue(path: List[Union[str, int]]) - Returns the current value of the component by the provided path. For more information about components and value types, please refer to the component descriptions.

  • setValue(path: List[Union[str, int]], value) - Sets the value of the component by the provided path. For more information about components and value types, please refer to the component descriptions.

  • repeatRow(path: List[Union[str, int]]) - Appends a row to the group by the provided path. This function returns the path of newly created row. For more information about the group component's structure, please refer to the component descriptions.

  • deleteRow(path: List[Union[str, int]]) - Deletes the row of the group specified by path. Here, the path should include the row index. For more information about the group component's structure, please refer to the component descriptions.

  • getGroupLength(path: List[Union[str, int]]) - Returns the number of rows in the group by its path. For more information about the group component's structure, please refer to the component descriptions.

  • postMessageToWebComponent(path: List[Union[str, int]], message) - Sends a message to a web component specified by the provided path. For more information about the web component's structure, please refer to the component descriptions.

  • setLoading(on_off: bool) - Enables/disables the loading icon. The icon replaces the page's layout when enabled.

  • getPayload() - Returns data attached to the item when the function is called in the editor. Returns no data when in build mode. For more information, refer to the Integration with the SuperAnnotate platform section.

HTTP Requests from The Code

To send HTTP requests, it is recomended to use the requests module, which was created by SuperAnnotate to replicate the Python requests module. The only difference is the browser limitation. In most cases, you won't see any difference.

Example:

import requests

def on_submit_click(path: List[Union[str, int]]):
    response = requests.request(
        url='https://your.domain.com/your/path',
        method ="GET",
        headers = None
    )

    ### Return response as a JSON object
    return response.json()

There is one important thing you need to remember while using this module - all the methods are asynchronous, meaning during the execution the UI will be blocked. Therefore, you should only use it with cases where the HTTP requests are fast enough. To use the asynchronous functionality, you can use asyncs sub module and add await to the function call to make it asynchronous.

Example:

import requests.asyncs as requests

async def on_submit_click(path: List[Union[str, int]]):
    response = await requests.request(
        url='https://your.domain.com/your/path',
        method ="GET",
        headers = None
    )

    ### Return response as a JSON object
    return response.json()