Skip to main content
All CollectionsFormula language reference
Custom user interfaces
Custom user interfaces

Build custom UI panels and controls in Neara projects

Updated this week

Panel

ui_panel()

Renders a surface for custom UI components. Contains header text, with a scrollable content beneath.

ui_panel(header, content)

Examples:

ui_panel("Header", "Panel content")
ui_panel( 	
    "Header", 	
    ui_accordion( 		
        list( 			
            ui_accordion_item(
                "Item 1", 
                "some content"
            ), 			
            ui_accordion_item(
                "Item 2", 
                "some content"
            ) 		
        ), 	
    ) 
)

For no heading text, set header to an empty string: ""

Displaying a custom panel in a project

To create a custom panel that can be opened and displayed in a project, register it as a Custom Widget:

  1. In the Schema Editor add a new field (of type Formula) to the the Model section

  2. Add a formula using ui_panel to the field definition, e.g.
    ​ui_panel("Panel title", "Panel content")

  3. Click the (+) at the end of any group of tabs, and on the popup select Create Custom Report

  4. For the report Datasource select CustomWidgets

  5. Use any meaningful name for the report, e.g. Custom Panels and save it

  6. Click the (+) at the end of any group of tabs, and on the popup select your Custom Widgets report under the Reports section

  7. Click Add a new entry, and in the new row enter:

    1. Name: This will be the name of the tab in the project. It can be the same as or different to the header in the ui_panel.

    2. Is Tab Panel: checked

    3. Formula: enter the name of the formula added in step (2)

  8. Close the custom widgets report

  9. Click the (+) at the end of any group of tabs, and on the popup select the custom tab under the new User Panels section

  10. It will open, and display the contents of the ui_panel formula

Use the formulas in the following sections to create custom user interfaces inside a ui_panel.

Containers

Mixed

ui_mixed()

ui_mixed(ui_element_1, ui_element_2, ...)

Renders all the UI elements together, inlining where applicable.

Example:

ui_mixed(
  ui_panel(
    "Location manager", 
    list(
      ui_input_text(model(), "u_search_location_name"), 
      ui_input_real(model(), "u_search_radius")
    )
  ),
  
  ui_button("Find location", do( 
    ... 
  )),

  ui_button("Reset form", do( 
    ... 
  ))

)

Vertical layout

ui_layout_vertical()

Experimental; subject to change

Lays out the provided items vertically with sensible spacing. Arbitrarily nested lists will be unboxed such that they are equivalent to positional arguments.


Examples:

ui_layout_vertical(
    ui_properties_panel(...), 
    ui_button("Submit", ...)
)
ui_layout_vertical(
    list(
        ui_properties_panel(...), 
        ui_button("Submit", ...)
    )
)

Accordion

ui_accordion()

ui_accordion(list|tuple(accordion_item), [ sort: "asc" | "desc" ])

Collapsible sections of content and controls.

Renders a vertically stacked list of headers that reveal or hide associated sections of content.

  • Takes a list of accordion items built with ui_accordion_item()

  • Optionally takes a sort direction to sort accordion items by their sort_value

ui_accordion_item()

ui_accordion_item(header, content, [ sort_value: string ])

Renders a single item in an accordion represented by a header, followed by some content.

  • Takes an optional sort_value to be used with the ui_accordion sort direction

Examples:

ui_accordion(
    list(
        ui_accordion_item("Item 1", “some content”),
        ui_accordion_item("Item 2", "some content")
    ),
)
ui_accordion(
    list(
        ui_accordion_item("Item 1", "some content"), sort_value: "1") ,
        ui_accordion_item("Item 2", "some content", sort_value: "2")
        ),
    sort: "desc",
)
ui_accordion(
    list(
        ui_accordion_item(
            "Item 1",
            ui_properties_table(
                make_props(
                    "Label", label,
                    "Notes", notes,
                )
            ),
        )
    ),
)

Tabs

Experimental; subject to change

ui_tabs()

ui_tabs(tab1, tab2,....)

Renders a tab component, used to display different but related content. Each tab should be created using ui_tab().

ui_tab(tab_name, content)

A single tab, to be passed as an argument to ui_tabs.

  • The tab_name is the text displayed on the tab itself

  • The content is the content displayed when the tab is selected


Example:

ui_tabs(
  ui_tab("First", ui_mixed("First tab content")),
  ui_tab("Second", ui_mixed("Second tab content")),
)

iFrame

ui_iframe()

ui_iframe(src: SafeUrl, name: Text)

Creates an iframe that embeds a website into the panel.

  • src: URL of the website. Must be marked as a safe URL using the Neara SDK, or using make_url()

  • name (optional): identifies this iframe in the DOM

Buttons & links

Button

ui_button()
​

ui_button(content, action, {mode, enabled})

Renders a button which executes the given action when clicked. Most commonly used for triggering an action such as reading/writing data:

  • mode: either "primary", "secondary" or "violent" (destructive). Defaults to "primary".

  • By default the button is enabled, but it can be controlled passing a boolean expression to the enabled parameter.

Example: 

ui_button("View poles report", launch_report(“Poles"))

Action link

ui_action()

ui_action(content, action, {enabled})

Renders an action link which launches the given action when clicked. Commonly used for navigation/hiding/showing information:

  • By default the link is enabled, but it can be controlled passing a boolean expression as the optional enabled parameter.

Example:

ui_action(
    "View poles report", 
    launch_report(“Poles")
)

Launch report action

launch_report()

launch_report(report_name, {filter_matches:properties})

An action which locates or opens the report with the given [report_name] in the current workspace.

Can be used as an argument to ui elements like ui_link.

Optionally takes a key-value properties object of [filter_matches] to apply to the report.

Returns a UI action that can be used as an argument in ui_action.

Example:

launch_report(
    "Report Name", 
    filter_matches: make_props(
        "property_name", 
        property_name
    ),
)

Hyperlink

hyperlink()

hyperlink(safe_url, [title])
hyperlink(href, [title])

Creates a clickable link with the given title. Commonly used for opening another website.

Example:

hyperlink("https://www.neara.com", "Neara homepage")

Google Street View link

ui_street_view_link()

ui_street_view_link(target)

Renders a link to Google Street View for the given location.

Example: 

ui_street_view_link(vec3(location.x, location.y, origin().z)

Inputs

Text

ui_input_text()

ui_input_text(object, text_field_name, {multiline:false})

Renders a text field input using, optionally multi-line.

  • The field_name must exist on the object and be writable

Numbers

Integer

ui_input_int()

ui_input_int(object, num_field_name, {min, max, step})

Renders a integral field with optional min/max/step. The field name must exist on the object and be writable.

Real

ui_input_real()

ui_input_real(object, num_field_name, [unit], {min, max, step, digits:2})

Renders a real-numeric field with optional unit, min/max/step. T

  • The dimension of min/max/step must be compatible with the field.

  • The num_field_name must exist on the object and be writable.

Suggest

ui_input_suggest()

ui_input_suggest(object, field_name, options, {labels: labels})

Renders a picker field, of any type.

  • labels: list of text that optionally overrides the labels to display (must be same length as options or will be dropped)

  • The field_name must exist on the object and be writable.

Form controls

Checkbox

ui_input_check()

ui_input_check(object, bool_field_name, {label:""})

Renders a check input for a field with an optional label. The field name must exist on the object and be writable.

Switch

ui_input_switch()

ui_input_switch(object, bool_field_name, {label:""})

Renders a switch input for a field with an optional label. The field name must exist on the object and be writable.

Segmented control

ui_input_segmented_control()

ui_input_segmented_control(object, field_name, options: list(), {labels: labels})

Renders a segmented control input field, of any type with optional labels.

  • labels should be the same length as options. If not, they will not be used.

  • The field_name must exist on the object and be writable.

Example:

ui_input_segmented_control(
  self, // pole object
  "status",
  list("QA Required", "QA In-Progress", "QA Complete")
)

Slider

ui_input_slider()

ui_input_slider(object, num_field_name, {min, max, step, digits: 2, unit})

Renders a numeric input slider for the specified field, which must be a writeable number (integer, dimensionless real, or a unit type). The slider allows the user to select a value within a defined range min to max with a specified increment step. The dimension of min/max/step must be compatible with the field.

  • min and max must be provided.

  • step is optional, allowing the increment size to be changed.

  • digits is optional for non-integer values, allowing the number of decimal places to be changed.

  • unit is optional for non-integer values, allowing the magnitude to be changed, e.g. from m to km.

Examples:

ui_input_slider(u_assembly, "dist_from_top", min: 0m, max: 20m)
ui_input_slider(u_assembly, "dist_from_top", min: 0m, max: 20m, unit: "cm", digits: 3)
ui_input_slider(self, "u_int", min: 0, max: 10, step: 2)

Properties

Properties panel

ui_properties_panel()

ui_properties_panel(row1, row2, ...)

Builds a properties panel suitable for field-value inputs.

Each row should be created using ui_properties_row() to get the field-value view, any other item will render in a full row.

Properties panel row

ui_properties_row()

ui_properties_row(key, value)

Builds a row suitable for inclusion in a ui_properties_panel()

Properties editor

ui_properties_editor()

ui_properties_editor(object, field_names: list(text))

Renders a form for editing the fields on the given object.

Properties table

ui_properties_table()

ui_properties_table(properties, [ filter_empty: true | false ])

Renders a key-value properties object (built using make_props) in a table.

Takes an optional [filter_empty] argument to omit properties with empty values, defaults to false.

Examples:

ui_properties_table( 	
    make_props( 		
        "Label", 
        label, 		
        "Notes", 
        notes, 	
    ), 
)
ui_properties_table(
    make_props(
        "Label", 
        label, 
        "Notes", 
        notes,
    ), 
    filter_empty: true
)

Popups

show_popup()

show_popup(content)

Creates an action that will render a modal popup with the given content when executed.

Example:

show_popup(ui_mixed("Hello, World!")

Imagery

Image

ui_image()

Experimental; Subject to change

ui_image(image, {width, height})

Renders an image. Provide optional width and height parameters as integer pixels.

Related Articles
Assemblies library
Working with tables in Reports
Create an area/line chart
Did this answer your question?