Skip to content

Declarations

Declarations are the state and logic layer of a Bellini page, component, or service. They hold data, define functions, and provide access to API and app services — everything the UI needs to read and respond to. Think of them as the controller behind your page or component.

Declarations behave consistently across pages, components, and services, with a few context-specific differences covered at the end of this page.

What You Will Learn

  • What the different declaration types are and when to use each
  • How to navigate and use the Declarations panel
  • How to access declarations in code
  • How to add, configure, and inject declarations using the toolbar and context menu
  • How to set default values and define function behaviour

Declaration Types

There are five types of declarations:

Type Description
Property A single value of any type (string, number, boolean, object literal, etc.). Cannot contain nested properties — use an Object for that
Object A named container that holds child Property, Array, and Function declarations
Array A JavaScript array. Array items can be of type Property, Array, or Object
Function A named, callable function with parameters and a body. Can be async, invoked on load, and configured with watches. See Functions for full details
Service An injected API service, built-in service, or app service. Services are read-only — they expose functions and properties but cannot be modified. Injected services always appear at the top of the declarations tree

All non-service declarations require a name that is unique within their scope and follows standard JavaScript identifier rules. An optional description (written in Markdown) can be added and is visible directly in the declarations tree.

Declarations Panel

The Declarations panel is displayed as a collapsible accordion section in the Page Editor and Component Editor right panel, and as the main editing surface in the Service Editor. It shows all declarations as a tree, mirroring the nesting structure of objects and arrays.

The panel has a toolbar at the top:

Button Description
+ Opens a dropdown menu to declare a new property, object, array, or function, or to inject a service. Same options as right-clicking on empty space
Delete Deletes the selected declaration(s)
Collapse All Collapses all nodes in the tree
Expand All Expands all nodes in the tree
Search Opens the search field. Declarations that do not match are filtered out

Reordering Declarations

Drag and drop nodes in the tree to reorder them. Injected services are always pinned to the top of the tree and cannot be repositioned.

Accessing Declarations in Code

How you reference a declaration in expressions and function bodies depends on the context:

In pages and components, use $ctrl:

1
2
3
$ctrl.myProperty
$ctrl.myObject.myArray[0]
$ctrl.myFunction("param")

In services, use this:

1
2
3
this.myProperty
this.myObject.myArray[0]
this.myFunction("param")

Context Menu

Right-clicking in the Declarations panel opens a context menu. Available items vary depending on what was right-clicked.

Empty Space

Right-clicking on an empty area (no node selected) offers root-level actions:

Declare

Action Description
Declare Property Opens the Configure Declaration dialog to add a new property at the root
Declare Object Adds a new object at the root
Declare Array Adds a new array at the root
Declare Function Adds a new function at the root

Copy

Action Description
Paste Pastes copied declarations at the root
Paste JSON Parses JSON from the clipboard and creates declarations from it at the root

Inject

Action Description
Inject API Opens the Inject Service dialog to inject an OpenAPI or GraphQL API service
Inject Built-in Service Opens the dialog to inject a built-in Bellini service
Inject App Service Opens the dialog to inject a custom app service

Property, Object, Array, or Function Node

Edit

Action Availability Description
Add › Property / Object / Array / Function object nodes only Adds a child declaration inside the object
Add › Item / Array / Object array nodes only Adds an item inside the array
Configure Declaration All except children of service nodes Opens the Configure Declaration dialog
Edit Value property nodes only Opens the Edit Value dialog to set a default value
Edit Function function nodes only Opens the Function Editor
Rename All except array-indexed items and service children Triggers inline rename
Delete All except service children Deletes the selected declaration(s)

Copy

Action Availability Description
Copy All except service children Copies the declaration to the clipboard
Paste All except service children Pastes clipboard declarations at this node
Paste JSON object and array nodes only Parses JSON from clipboard and inserts it inside the node

Service Node

Action Availability Description
Delete All service nodes Removes the injected service
Edit API API service nodes only Opens the API editor
Edit Service App service nodes only Navigates to the app service editor
Copy All service nodes Copies the declaration to the clipboard
Paste All service nodes Pastes clipboard declarations at this node

API Method Node

Action Availability Description
Generate Form Operations with parameters or a request body Generates a form object declaration from the API operation's schema

Always Available

Action Description
Find References Searches the codebase for all references to the selected declaration

Configure Declaration Dialog

The Configure Declaration dialog is used to create or update a declaration's core settings.

Field Description
Name The declaration's identifier. Must be unique within its scope and follow JavaScript naming rules
Type The declaration type: Property, Object, Array, or Function
Description Optional. A Markdown editor for documenting the declaration. The description is visible in the declarations tree

Click Update to apply the changes.

Edit Value Dialog

The Edit Value dialog sets the default value of a property declaration. The value is a JavaScript expression that is evaluated when the page, component, or service loads, and its result is assigned to the declaration.

The dialog contains a JavaScript code editor. The available declarations are listed in a panel on the right and can be referenced in the expression.

Inject Service Dialog

The Inject Service dialog is used for Inject API, Inject Built-in Service, and Inject App Service — all three share the same layout.

The dialog displays a searchable list of available services. Clicking a service shows its description in a detail panel on the right. Each service has a checkbox; select one or more and click Inject to add them as declarations.

Context-Specific Differences

Declarations work the same way in pages, components, and services, with the following differences:

Context Difference
Pages When a page has parameters configured, a pageParameters object is automatically injected, giving access to parameter values via pageParameters.paramName
Components Declarations can be marked as exported, making them accessible to the parent page or component that uses this component. See Component Properties
Services Declarations can be marked as visible (public), controlling whether they are accessible when the service is injected elsewhere