There are a number of ways to customise and extend the user interface of a Neara project. Construct bespoke end-user experiences, and time-saving automations that are powered by a network model, related data, and the Neara platform.

This section is a reference of the available formulas that can be used to generate user interface features in a project.

Containers

UI Panel

ui_panel()

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

ui_panel(header, content)

Similar to ui_layout_vertical(), ui_panel() also accepts lists for content.

Example:

ui_panel( 	
    "Example accordion", 	
    ui_accordion( 		
        list( 			
            ui_accordion_item(
                "Section 1", 
                "Content in section 1"
            ), 			
            ui_accordion_item(
                "Section 2", 
                "Content in section 2"
            ) 		
        ), 	
    ) 
)

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

For heading text only, set content to an empty list: list()

UI 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( 
    ... 
  ))

)

This is useful when a formula expects UiElement type content, for example in show_popup():

show_popup(
  ui_mixed(
    "Pole 1 was clicked"
  )
)

Accordions

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("Pole features", "Pole features content"),
        ui_accordion_item("Span features", "Span features 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,
                )
            ),
        )
    ),
)

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.

Examples

Primary button, enabled:

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

Secondary button, enabled:

ui_button(
    "View poles report", 
    launch_report(“Poles"),
    mode: "secondary"
)

Destructive button, disabled:

ui_button(
    "Delete pole custom label", 
    do(make_field_mutation(model(), u_pole_custom_label: "")),
    mode: "violent",
    enabled: len(u_pole_custom_label) <> ""
)

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: Action links, enabled and disabled:

ui_mixed(
  ui_action(
    "Show Poles report",
    launch_report(
      "A Poles report"
    )
  ),
  ui_action(
    "Show Poles report",
    launch_report(
      "A Poles report"
    ),
    enabled: false
  )
)

Example: Action link that modifies a field's value:

ui_action(
    "Reset all", 
    do(
      make_field_mutation(
        model(), 
        u_latlong_string: ""
      )
    )
)

Example: Action link that shows a custom panel (generated in this example using a formula in a field called u_custom_panel_field) as a popup:

ui_action(
  "Show panel as a pop-up",
  show_popup( 
    not_null( 
      u_custom_panel_field 
    )
  )
)

Launch report

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: Consider this formula for field u_first_selected_pole, which obtains the first pole from the list of currently selected poles (refer to the earlier example above for the u_selected_poles formula):

index(
  model().u_selected_poles,
  0
)

To generate a Google Street View link for that pole's location, the formula is:

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

When clicked, the user will be shown Google Street View, if available, at that location in a new browser tab.

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

Integer

ui_input_int()

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

Renders a integer value field, with optional minimum, maximum, and step size.

num_field_name is a string e.g. "u_number_segments". It must exist on the object, and be writable.

Example: integer input, minimum value of 0, maximum value of 100, step size of 10:

ui_mixed(
  "0-100 in increments of 10:",

  ui_input_int(
    model(),
    "u_an_integer_value",
    min: 0,
    max: 100,
    step: 10
  )
)

Real

ui_input_real()

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

Renders a real-numeric field with optional minimum, maximum, and step size.

num_field_name is a string e.g. "u_latitude". It must exist on the object, and be writable.
unit is a string e.g. "m" or "MPa". If the value is dimensionless use an empty string: "".
The dimension of min/max/step must be compatible with the field
digits is the number of digits following the decimal point

Example: Dimensionless real value, displayed inside a ui_properties_panel:

ui_properties_row(
  "Longitude",

  ui_input_real(
    model(),
    "u_longitude",
    "",
    digits: 7
  ),
)

Example: Dimensioned real value

ui_input_real(
  model(), 
  "u_height",
  "m",
  digits: 2
)

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: segmented control with custom values:

ui_input_segmented_control(
  self,
  "u_selected_pole_status",
  list("QA Required", "QA In-Progress", "QA Complete")
)

Example: segmented control for boolean value, with custom display order:

ui_mixed(
  "Display point cloud",
  ui_input_segmented_control(
    model().view_config,
    "Display_point_cloud",
    list( 
      false, 
      true
    )
  )
)

Example: segmented control with custom display labels

ui_input_segmented_control(
  model(),
  "u_component_category",
     
  // Data values
  list(
    "pl",
    "cnd",
    "trns",
    "brc",
    "ins"
  ),
            
  // Custom display labels
  labels: list(
    "Pole",
    "Conductor",
    "Transformer",
    "Brace",
    "Insulator"
  )
)

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!"
  )
)

Images

ui_image()

Experimental; Subject to change

ui_image(
  image, 
  {width, height}
)

Renders an image.

image is an Image type

Provide optional width and height parameters as integer pixels

To create an Image, use make_image. For security, make_image requires a safe URL. Safe URLs can be created as follows.

An image can be loaded from an External Data Source (EDS) that is connected to the organisation account.

Create an safe URL to an image file's location on the EDS by using the get_data_source formula in a make_image formula, similar to this:

ui_image(
  make_image(
    get_data_source_url(
      data_source_id: "<data_source_id>", 
      path: replace(self.u_path_to_image_file, "\\", "/")
    ),
    "Neara logo", 
    id: "neara-logo"
  ),
  width: 500,
  height: 300
)

An image can also be loaded from an external service / site / API, where an External Service Configuration has been setup in an organisation account to provide secure access to resources on that service.

This is done by creating a safe URL to an image file's location by first using the authorize_service formula. If successful this returns a templated URL that can be used in a make_image formula similar to this:

ui_image(
  make_image(
    make_url(
      templated_url: authorize_service("neara-image-service"),
      substitution: map("FILE_PATH", "/logos/neara-logo-dark-bg.png")
    ),
    "Neara logo", 
    id: "neara-logo"
  ),
  width: 500,
  height: 300
)

For more information about configuring External Data Sources and External Service Configurations, contact us.

Setting a manual or calculated custom Pole Strength

Creating custom reports

Lists and Collections

Monte Carlo simulation

Plot a Cumulative Distribution Function (CDF)