Screens & Widgets
Screen structure

Ensemble Screen Structure

Ensemble apps are built using a collection of screens, along with reusable components like widgets, scripts, assets, etc. This guide explores the core structure of an Ensemble screen and the elements that make it up.

Key Components of Screen: This section serves as a reference point for the key elements you'll encounter while creating a screen on Ensemble:

  • View: The fundamental building block for screen content and layout.
  • ViewGroup: A container for managing and arranging multiple views.
  • Header: Optional element for displaying titles, navigation, or controls at the top of the screen.
  • Menu: Optional element for user navigation within the app.
  • Body: Main content area of a screen, typically containing widgets.
  • API: The collection of functions and tools provided by Ensemble for building your app.
  • Global: Elements or functionalities accessible across all screens in your app.

Below is the overview of the basic components being arranged on the screen.

Page Skeleton

View Group

The ViewGroup widget allows you to group multiple Views together and organize them behind a menu, such as a Drawer, EndDrawer, BottomNavBar, SideBar, or EndSidebar. This provides a convenient way to create structured layouts and navigation within your application.

Example

Let's look at an example with a Bottom Navigation Bar menu type.

ViewGroup:
  BottomNavBar:
    styles:
      backgroundColor: white
    items:
      - icon: search
        label: Search
        page: Home
      - icon: assignment
        label: Appointments
        page: MyAppointments
      - icon: list
        label: My Doctors
        page: MyDoctors
      - icon: account_circle
        label: Profile
        page: Profile
Output

BottomNavBar

To get hands-on experience with View Group, check the live example on Ensemble Studio (opens in a new tab)

View

The View widget defines the overall structure of a page, including properties like header, body and more, to create a cohesive layout and presentation within your application. View requires only body while other components like header and menu are optional.

Properties

PropertyTypeDescription
headerobjectdetails
bodyobjectdetails
onLoadactionExecute an Action from a set of pre-defined set of actions when the screen loads
onPauseactionExecute an Action when this screen is no longer active. This happens when another screen navigates on top of this screen, or when the App (Native only) is no longer in the foreground.
onResumeactionExecute an Action when this screen becomes active again from the inactive state. This happens when navigating back from another screen, or when the App (Native only) is brought back to the foreground.
optionsstringSpecify if this is a regular (default) or modal screen.
stylesobjectsee properties

View.styles

PropertyTypeDescription
backgroundColorColorBackground color for the screen starting with '0xFF' for full opacity e.g 0xFFCCCCCC. It can be specified as a number, a predefined color name, or a hexadecimal value starting with '0x'. transparent black blue white red grey teal amber pink purple yellow green brown cyan indigo lime orange
backgroundImageBackgroundImageBackground image of the View.
useSafeAreabooleanApplicable only when we don't have a header. If true, insert paddings around the body content to account for the devices' Safe Area (e.g. iPhone notch). Default is false.
scrollableViewbooleanSpecify if the content of this screen is scrollable with a global scrollbar. Using this also allows you to customize the scrolling experience of the header.
showNavigationIconbooleanFor a screen with header, the App will automatically show the Menu, Back, or Close icon (for the modal screen) before the title. On the modal screen without the header, the Close icon will be shown. Set this flag to false if you wish to hide the icons and handle the navigation yourself.
navigationIconPositionstringOn modal screen without a header, you can position the close button at the start or end of the screen. For left-to-right languages like English, start is on the left and end is on the right. This property has no effect on a screen with header.

Header

The header contains the Safe Area (e.g. iPhone notch) and by default has the background color of your theme's primaryColor. It includes:

  1. navigation icon. If a drawer menu is used the system will automatically show an icon to open/close the drawer, otherwise if this page can navigate back to the previous page, the back arrow will be shown. If neither condition is true, the icon will not be visible, in which case the title will stretch to fill the entire horizontal space.
  2. title. Its simplest form is a string which is the title text. You may override it with a custom widget.
  3. flexible background. Specifies a widget that will fill the entire header (including the notch). This is typically used as a background for the header. This widget will be laid out first, with the navigation icon and the title overlay on top.

Properties

PropertyTypeDescription
titleTextstringThe title for the screen
titleWidgetWidgetRender this widget as the screen title
stylesobjectsee properties
flexibleBackgroundWidgetThis widget (typically used as an background image) acts as the header's background, with the title bar and the bottom widget overlaid on top. On non-scrollable screen, its dimensions is dictated by the header's width and height.

Header.styles

PropertyTypeDescription
backgroundColorColorBy default the background color uses the theme's 'primary' color. You can override the header's background color here. It can be specified as a number, a predefined color name, or a hexadecimal value starting with '0x'. transparent black blue white red grey teal amber pink purple yellow green brown cyan indigo lime orange
colorColorBy default the navigation icon, title, and action icons uses the theme's 'onPrimary' color. You can override their colors here. It can be specified as a number, a predefined color name, or a hexadecimal value starting with '0x'. transparent black blue white red grey teal amber pink purple yellow green brown cyan indigo lime orange
elevationintegerRaise the header on its z-coordinates relative to the body. This effectively creates a drop shadow on the header's bottom edge. Minimum value: 0, Maximum value: 24
shadowColorColorIf elevation is non-zero, this will override the drop shadow color of the header's bottom edge, starting with '0xFF' for full opacity. transparent black blue white red grey teal amber pink purple yellow green brown cyan indigo lime orange
centerTitlebooleanWhether to align the title in the title bar's center horizontally (default: true)
titleBarHeightintegerFor consistency, the header's title bar has the default fixed height of 56 regardless of its content. You may adjust its height here. Minimum value is 0
flexibleMinHeightintegerApplicable only if scrollableView is enabled. This attribute effectively sets the header's min height on scrolling (header's height will varies between the flexibleMinHeight and flexibleMaxHeight). Note that this attribute will be ignored if smaller than the titleBarHeight
flexibleMaxHeightintegerApplicable only if scrollableView is enabled. This attribute effectively sets the header's max height on scrolling (header's height will varies between the flexibleMinHeight and flexibleMaxHeight). This attribute will be ignored if smaller than the flexibleMinHeight

Note: When the entire View is specified as scrollable, flexible background's height can vary in height (hence flexible) on scroll with a parallax effect.

Menu

Ensemble provides support for five menu types that offer extensive customization options, including the ability to add custom items which are indeed custom widgets. These menu types allow users to meet their unique design needs or client requirements. Below, you will find detailed information about each menu type, including the supported properties, styles, and illustrative examples for better understanding.

BottomNavBar

This is the navigation bar at the bottom of the screen, typical of most iOS and Android apps. Where each item has several properties as explained below.

BottomNavBar.Properties

PropertyTypeDescription
itemsarray of objectsList of menu items (minimum 2). see properties
stylesobjectsee properties

BottomNavBar.items

PropertyTypeDescription
iconstringIcon name from Material Icons``Font Awesome``Remix or custom font icons.
iconLibrarystringEnables the usage of various icon libraries like FontAwesome, Remix, Material Icons or custom icon fonts within ensemble.
labelstringDefines the text displayed below the icon, providing a descriptive title or name for the menu item
pagestringThe new page to navigate to on click
selectedbooleanMark this item as selected. There should only be one selected item per page.
visiblebooleanMark this item as visible. Default is true
floatingbooleanMark this item as a floating icon
floatingMargininteger or stringThe margin around the floating.
floatingAlignmentstringHow to align the floating in the BottomNavBar. The values are left``center``right and none
colorColorUnselected icon color, starting with '0xFF' for full opacity e.g 0xFFCCCCCC. It can be specified as a number, a predefined color name, or a hexadecimal value starting with '0x'. transparent black blue white red grey teal amber pink purple yellow green brown cyan indigo lime orange
selectedColorColorSelected icon color, starting with '0xFF' for full opacity e.g 0xFFCCCCCC. It can be specified as a number, a predefined color name, or a hexadecimal value starting with '0x'. transparent black blue white red grey teal amber pink purple yellow green brown cyan indigo lime orange
backgroundColorColorBackground color of the box. which can be represented in different formats. It can be specified as a number, a predefined color name, or a hexadecimal value starting with '0x'. transparent black blue white red grey teal amber pink purple yellow green brown cyan indigo lime orange
floatingBackgroundColorColorFloating item background color, starting with '0xFF' for full opacity e.g 0xFFCCCCCC. It can be specified as a number, a predefined color name, or a hexadecimal value starting with '0x'. transparent black blue white red grey teal amber pink purple yellow green brown cyan indigo lime orange
floatingIconColorColorFloating item icon color, starting with '0xFF' for full opacity e.g 0xFFCCCCCC. It can be specified as a number, a predefined color name, or a hexadecimal value starting with '0x'. transparent black blue white red grey teal amber pink purple yellow green brown cyan indigo lime orange
customItemobjectAllows user to use custom widgets for two states selected and UnSelected.
BottomNavBar.items.customItem
PropertyTypeDescription
widgetWidgetCustom bottom navigation item for the unselected state
selectedWidgetWidgetCustom bottom navigation item for the selected state

BottomNavBar.styles

PropertyTypeDescription
backgroundColorColorBackground color of the box. which can be represented in different formats. It can be specified as a number, a predefined color name, or a hexadecimal value starting with '0x'. transparent black blue white red grey teal amber pink purple yellow green brown cyan indigo lime orange

Example

BottomNavBar:
  styles:
    backgroundColor: white
    color: grey
    selectedColor: orange
    floatingBackgroundColor: orange
    floatingIconColor: white
  items:
    - label: Home
      activeIcon: home
      icon: home
      page: Home
 
    - customItem:
        widget: CustomNavBarItem
        selectedWidget: ActiveCustomNavBarItem
      page: Icon
 
    - icon: note_add
      floating: true
      floatingAlignment: center
      floatingMargin: 5
      onTap: |
        //@code
        ensemble.navigateScreen('Lottie');
 
    - icon: search
      label: Search
      page: Image
      visible: true
 
    - customItem:
        widget: CustomNavBarItemWithImage
        selectedWidget: ActiveCustomNavBarItemWithImage
      page: WeeklyScheduler

This sippet has example for how user can utilize

  1. Custom widgets as items for the menu
  2. Floating icons

To get hands-on experience with BottomNavBar, check the live example on Ensemble Studio (opens in a new tab).

Drawer

This menu type puts the menu behind a drawer icon on the header. The drawer icon will be positioned to the 'start' of the header (left for most languages, right for RTL languages).

Drawer.Properties

PropertyTypeDescription
headerwidgetThe header widget for the menu
footerwidgetThe footer widget for the menu
itemsarray of objectsList of menu items (minimum 2). see properties
stylesobjectsee properties

Drawer.items

PropertyTypeDescription
iconstringIcon name from Material Icons``Font Awesome``Remix or custom font icons.
iconLibrarystringEnables the usage of various icon libraries like FontAwesome, Remix, Material Icons or custom icon fonts within ensemble.
labelstringDefines the text displayed below the icon, providing a descriptive title or name for the menu item
pagestringThe new page to navigate to on click
selectedbooleanMark this item as selected. There should only be one selected item per page.
visiblebooleanMark this item as visible. Default is true

Drawer.styles

PropertyTypeDescription
backgroundColorinteger or stringBackground color of the box. which can be represented in different formats. It can be specified as a number, a predefined color name, or a hexadecimal value starting with '0x'. transparent black blue white red grey teal amber pink purple yellow green brown cyan indigo lime orange

Example

It is a basic usage example for the Drawer menu.

View:
  title: Drawer menu
  menu:
    Drawer:
      items:
        - label: Home
          icon: home
          page: Home
        - label: Button
          icon: input
          page: Button
 
  Column:
    styles: { gap: 16, padding: 24, scrollable: true }
    children:
      - Markdown:
          text: |
            This page includes menu displayed as drawer
Output

Page Skeleton Page Skeleton

To get hands-on experience with Drawer, check the live example on Ensemble Studio (opens in a new tab)

End Drawer

Similar to Drawer but the drawer icon will be positioned to the 'end' of the header (right for most languages, left for RTL languages). You can check its properties here.

To get hands-on experience with End Drawer, check the live example on Ensemble Studio (opens in a new tab)

SideBar

A fixed navigation menu to the 'start' of the screen (left for most languages, right for RTL languages). The menu may become a drawer menu on lower resolution or screen sizes.

Sidebar.Properties

PropertyTypeDescription
headerwidgetThe header widget for the menu
footerwidgetThe footer widget for the menu
itemsarray of objectsList of menu items (minimum 2). see properties
stylesobjectsee properties

Sidebar.items

PropertyTypeDescription
iconstringIcon name from Material Icons``Font Awesome``Remix or custom font icons.
iconLibrarystringEnables the usage of various icon libraries like FontAwesome, Remix, Material Icons or custom icon fonts within ensemble.
labelstringDefines the text displayed below the icon, providing a descriptive title or name for the menu item
pagestringThe new page to navigate to on click
selectedbooleanMark this item as selected. There should only be one selected item per page.
visiblebooleanMark this item as visible. Default is true

Sidebar.styles

PropertyTypeDescription
backgroundColorinteger or stringBackground color of the box. which can be represented in different formats. It can be specified as a number, a predefined color name, or a hexadecimal value starting with '0x'. transparent black blue white red grey teal amber pink purple yellow green brown cyan indigo lime orange
borderWidthintegerThe thickness of the border
borderColorinteger or stringColor of the border, which can be represented in different formats. It can be specified as a number, a predefined color name, or a hexadecimal value starting with '0x'. transparent black blue white red grey teal amber pink purple yellow green brown cyan indigo lime orange
itemDisplaystringHow to render each navigation item. stacked sideBySide
itemPaddinginteger or stringPadding for each navigation item with CSS-style value
minWidthintegerThe minimum width for the menu (default 200)

Example

An example on how to use Sidebar menu.

View:
  title: Sidebar menu
  menu:
    Sidebar:
      items:
        - label: Home
          icon: home
          page: Home
        - label: Button
          icon: input
          page: Button
 
  Column:
    styles: { gap: 16, padding: 24, scrollable: true }
    children:
      - Markdown:
          text: |
            This page includes menu displayed as Sidebar
Output

Page Skeleton

To get hands-on experience with Sidebar, check the live example on Ensemble Studio (opens in a new tab)

Body

The View requires a single widget defined as its child. This will act as the body content, and can only be a Column, Row, Flex, or Stack widget.

API

API provides a convenient way to interact with external services or data sources, allowing developers to make HTTP requests, access data, and integrate various functionalities into their applications.

Properties

PropertyTypeDescription
methodStringThe HTTP method of the request, such as GET, POST, DELETE, PUT, PATCH
uriStringThe URI for the request
bodyObjectThe request body
headersObjectThe headers for the request
onResponseActionThe action to handle the response
onErrorActionThe action to handle errors
inputsArrayThe input values

To learn about API's in detail, click here

Global

Global enables users to declare or define functions and variables which can be accessed globally inside the whole screen in every widget. In simple words its scope ig global just like a normal JavaScript Global Execution Context where users can access these functions anywhere in the screen.

Example

View:
  header:
    title: "Code: Global functions"
  styles:
    scrollableView: true
  Column:
    styles: { gap: 16, padding: 24 }
    children:
      - TextInput:
          id: secondsInput
          label: Seconds
          value: 28565
      - Button:
          label: Convert to hours and minutes
          onTap:
            executeCode:
              body: |-
                //@code
                results.text = convertSecondsToHours(secondsInput.value);
 
      - Text:
          id: results
 
Global: |-
 
  function convertSecondsToHours (s) {
 
    console.log(s);
  }

Output

The output can be checked in the logs for browser

Page Skeleton

Putting it together

This example illustrates almost all the widgets which are integral part of ensemble page structure. It also demonstrates a comprehensive usage of BottomNavBar, onLoad action, API calls and custom widgets.

View:
  onLoad:
      invokeAPI:
        name: getUser
        inputs:
          id: 32GelurbLbd6umj3ULOkAXYSYyq2
 
  # Set the view to be scrollable
  styles:
    scrollableView: true
menu:
    BottomNavBar:
      styles:
        shadowColor: 0xFFFD451C
      items:
        - icon: home
          label: Home
          page: Home
          selected: true
        - label: Favorite
          icon: favorite
          page: Favorite
        - label: Promos
          icon: loyalty
          page: Promos
        - label: Account
          icon: account_circle
          page: Profile
 
  # This is the parent widget for all screen content
  body:
    Column:
      styles:
        backgroundGradient:
          colors: [ 0xFFF4D66C, 0xFFFEFAF3, 0xFFFFFFFF ]
          start: topLeft
          end: bottomRight
 
      children:
        - UserInfo
        - SearchBar
        - Categories
        - NearbyFood

Output

Page Skeleton

To get hands-on experience with a complete Application, check Ensemble Studio (opens in a new tab)