Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 38 ยท Concepts and Canvas Apps

Anatomy of a Canvas App

Learn how a canvas app is organized: the App object with OnStart and Formulas, screens, controls, properties, the name rules, and how formulas are evaluated.

A canvas app looks like a drawing, but under the surface it is a small, well-defined structure. Understanding that structure helps you read any app, debug it, and organize your own work so it stays maintainable.

The hierarchy

flowchart TD
  App["App object"] --> S1["Screen: Home"]
  App --> S2["Screen: Details"]
  S1 --> C1["Label: lblTitle"]
  S1 --> C2["Gallery: galItems"]
  C2 --> C3["Label inside gallery template"]
  S2 --> C4["Button: btnBack"]

Everything hangs from one App object. Screens hold controls; some controls contain other controls.

At the top is the App object. Below it are screens. Each screen contains controls, and some controls (galleries, forms, containers) contain more controls.

The App object

The App object is shown first in the Tree view. It has useful properties:

  • OnStart: runs once when the app starts. Historically used to set global variables and load collections. Heavy work here slows startup, so modern guidance prefers other options.
  • StartScreen: names the screen shown first, without running code in OnStart.
  • Formulas (named formulas): a property where you define values that are always up to date, such as CurrentUserEmail = User().Email;. They are recalculated on demand and keep startup fast.
  • OnError, OnMessage and others for advanced cases.
  • Theme and MinScreenWidth/MinScreenHeight for display behavior.

Named formulas are a great way to avoid repeated expressions:

TEXT
TodayText = Text(Today(), "yyyy-mm-dd");
IsManager = User().Email in ManagerEmails.Email;

You then use TodayText or IsManager anywhere. Unlike variables, they cannot be assigned; they always reflect their definition.

Screens

A screen is a page with its own controls and a few properties: Fill, BackgroundImage, OnVisible and OnHidden. Use OnVisible to refresh or reset state each time the screen appears, for example Reset(txtSearch). Screens are covered in Screens and navigation.

Controls and properties

Every control is a collection of properties. A property is either:

  • Input: a value you set, such as Text, Items, Fill or Visible.
  • Output: a value the control produces, such as TextInput1.Text or Dropdown1.Selected.
  • Behavior: a formula run in response to events, such as OnSelect and OnChange.

Behavior properties may contain several steps separated by semicolons (a semicolon in the English-US locale; some regional settings use a double semicolon). Input properties must be pure expressions with no side effects. This separation is why formulas stay predictable.

Naming rules and conventions

Control names must be unique across the whole app. Good conventions use a short prefix:

Prefix Control
lbl Label
txt Text input
btn Button
gal Gallery
drp Dropdown
frm Form
con Container
scr Screen

A formula refers to another control as Name.Property, for example txtSearch.Text. Because names are part of formulas, renaming a control updates references automatically.

How the app is evaluated

The core idea again: everything is a formula, and formulas are recalculated automatically when their dependencies change. The runtime builds a dependency graph. The stand-in below does the same thing in miniature: each named value is a formula; reading it recomputes from current inputs.

JS Stand-in: a tiny dependency graph of named formulas

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Reading someone else's app

A quick routine for an unfamiliar app:

  1. Open Tree view and collapse all screens. Note the screen names and the order.
  2. Select the App object and read StartScreen, OnStart and Formulas.
  3. Open View, Data sources to see what it connects to.
  4. Run App checker and read its warnings.
  5. Use Monitor while you click through; watch which calls fire.

The stand-in below prints a Tree view as indented text, to practice reading structure.

JS Stand-in: print a control tree

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Good structure habits

  • One concern per screen; reuse parts through components (see the Components and ALM chapter).
  • Keep OnStart short; use named formulas for derived values.
  • Group controls into containers so layout moves together.
  • Keep formulas readable: break long ones into named formulas, With blocks or helper variables.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the top of every canvas app's hierarchy?

    The App object owns the screens and app-wide properties like OnStart and Formulas.
  2. 2. Which is true of a named formula defined in App.Formulas?

    Named formulas are recalculated on demand and are read-only.
  3. 3. Which kind of property may contain several steps separated by semicolons?

    Behavior properties run actions in sequence; input properties are pure expressions.
  4. 4. Why use name prefixes like btn and txt?

    Prefixes improve readability for you and your team.

Summary

  • An app is an App object, screens, and controls with properties.
  • App properties include StartScreen, OnStart and Formulas.
  • Input properties are pure formulas; behavior properties run steps.
  • Names must be unique; prefixes keep them readable.
  • Formulas are recalculated through a dependency graph.

Next: Screens and navigation