> For the complete documentation index, see [llms.txt](https://www.opal-rt.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.opal-rt.com/docs/hypersim/model-and-simulation/edit-a-model-schematic/create-manage-subcircuits/block-form-editor.md).

# Block Form Editor

When a User-Coded Model (UCM) or Subcircuit is created, HYPERSIM displays a default parameter form when the component is double-clicked in the schematic. The Form Editor allows you to create a custom view that improves the organization, presentation, and usability of the component's configuration interface. By default, the custom view file for a component is named CustomView\_{BlockName}.xml.

Although the Subcircuit configuration allows the custom view file name to be modified, it is recommended to keep the default name to maintain consistency and improve file organization. {% endhint}

## Create a form custom view

Before a component view can be edited, its **XML file** must be generated. For supported components, this can be done by right-clicking the component in the default parameter form.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-c7b853dc6e53433a20cfcb25334e63b0bc04bc0b%2Fform-editor-save-layout.png?alt=media" alt=""><figcaption></figcaption></figure>

Once saved, the custom view is stored in the **\_hyp/view folder** of the project and is therefore available only within that model. When opening a component form, HYPERSIM searches for custom view definitions according to a predefined hierarchy and automatically loads the most specific one available.

<table><thead><tr><th width="150">Location</th><th width="150">Scope</th><th>Notes</th></tr></thead><tbody><tr><td>${HYP_FOLDER}\view</td><td>Project only</td><td>Will be exported with the model</td></tr><tr><td>${USER_HOME}\HYPERSIM\view</td><td>User only, all projects</td><td>Will not be exported with the model by default</td></tr><tr><td>${HYPERSIM_DIR}\Windows\Hyperworks\data\view</td><td>All users, all projects</td><td>Should not be edited manually, but can be overridden if required.</td></tr><tr><td>Installation binaries</td><td>All users, all projects</td><td>Cannot be edited</td></tr></tbody></table>

## Editing the form

This documentation uses the [Distribution Connected Battery Energy Storage System with Average Converter](https://www.opal-rt.com/docs/hypersim/examples/renewable-energy/distribution-bess-average-converter.md) model as example.

After saving the layout, the layout can be edited showing the following view:

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-449a6178097c827f4822fba6b78c9420c9489d61%2Fform-editor-custom-view.png?alt=media" alt=""><figcaption></figcaption></figure>

**1** : The form editor tabs enable to switch between the **widget view**, which displays the final layout of the component, and the **parameter view**, which lists all available parameters in the component.

**2**: The **tree view** shows the Custom View structure. Each tab is made of a grid, in which Widgets are inserted and linked to the parameters of the block.

**3**: The form preview shows the current result of the Custom View. The grid can be shown or hidden from the View menu at the top of the window. When a widget is being edited, it will be blinking in the preview.

**4**: The property menu shows the configuration of the currently selected structure element.

### Form editor tabs

The **Widgets tab** is used to design and edit custom views, while the **Parameters tab** lists all parameters available for the component.

* Parameters not yet included in the custom view are displayed in red. Right-click a parameter to add a widget.
* For parameters already included in the custom view, use Locate from the context menu to quickly find the corresponding widget.

### Tree view structure

The tree view consists of four hierarchical levels, each offering its own right-click context menu options.

* **Component level**: shows the component category as title, it allows to control the default dimensions of the windows.
* **Tab level**: For each tab, the name and number of columns can be edited.

  Note: If the custom view has only 1 tab, it may be displayed as \_*UNKNOWN*\_, as this title will not be visible when opening the component form
* **Column level**: From this level, cosmetic widgets may be inserted.
* **Widget level**: From this level, rows can be added in the grid, and the widget may be located, deleted or moved to another location.

### Form preview

This scene displays the current result of the custom view.

{% hint} This view allows you to edit text field values and change units as in a standard component form; however, any changes are for preview purposes only and cannot be applied to the component. {% endhint}

### Property menu

The Properties panel displays all properties associated with the selected item. For components, tabs, and columns, the available options are limited and generally self-explanatory.

When a widget is selected, the properties are organized into three categories:

* **Common properties**: These properties are shared by all widget types and control general aspects such as the widget type, tab assignment, position, and size.
* **Widget-specific properties**: Each widget type provides a set of properties that define its behavior and appearance. For example, a text field can be configured as read-only, while a web component can specify the path to an image or external resource.
* **Widget positioning controls**: The Up, Down, Left, and Right buttons allow you to reposition the widget within the custom view.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://www.opal-rt.com/docs/hypersim/model-and-simulation/edit-a-model-schematic/create-manage-subcircuits/block-form-editor.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
