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.

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

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

View.styles

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

Header.styles

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

BottomNavBar.items

BottomNavBar.items.customItem

BottomNavBar.styles

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
 
    - 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

Drawer.items

Drawer.styles

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

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

Sidebar.items

Sidebar.styles

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

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

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

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

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