Writer Framework Builder’s interface is an overlay on top of the running app, which allows you to edit your app while it’s running. This approach gives you an accurate representation of how the app will look and behave without the need to constantly preview it.

​
Writer Framework Builder’s modes

Writer Framework Builder has two modes:

  1. UI mode: This is the default mode, which provides an overlay of tools for building and editing the user interface. The app still runs in UI mode, allowing to you test its functionality while you’re building it. You can also edit the app’s code and view its log.

  1. Preview mode: This mode lets you preview the application, experiencing it almost as your end users would. The tool overlay is hidden, but you can still edit the app’s code and view its log in this mode.

You can switch between UI mode and Preview mode by using the UI/Preview selector near the upper left corner of the page.

​
Building your app in UI mode

​
The different areas of UI mode

In UI mode, Writer Framework Builder’s page is divided into these areas:

  1. Canvas: This is where you lay out components to build your app’s user interface. It displays the UI as your users will see it.
  2. Core toolkit: A “palette” of UI components that can be added to your app’s user interface. To add a component to your app’s UI, drag it onto the Canvas or into the Component tree.
  3. Component tree: This provides an alternative way to view your app’s user interface: as a hierarchical tree structure. It’s useful for ensuring that UI components are located in the right place or in the correct container object, and is handy for selecting UI components in complex layouts.
  4. Component settings: This panel lets you view and edit the settings for the currently selected UI component. You can hide the Component settings panel if you need more screen space to work on the Canvas.
  5. Top bar: Contains the “high level” editing controls: switching between UI and Preview mode, undoing and redoing the most recent change to the UI, and viewing the application’s state.
  6. Bottom bar: Contains the “low level” editing controls, which toggle the Code and Log panels.

​
Defining your app’s user interface

Writer Framework Builder provides a selection of over 50 UI components that you can use to build your app’s user interface:

You define your app’s user interface by dragging components from the Core toolkit and dropping them either onto the Canvas or into the Component tree (remember, the Canvas and Component tree provide different ways to look at your app’s user interface). If you simply drag and drop a UI component onto an empty spot on the Canvas, it will be placed at the “end,” below all other UI components in the user interface. To place a UI component at a specific location, drag them over the desired location or parent component until you see the insertion lines.

It can sometimes be difficult to find the component you’re looking for, so the Core toolkit has a search field. You can use it to find the narrow down the list of components or find a specific one.

Some UI components, such as Section, can act as “parents,” which are UI components that can contain other UI components. Others, such as Text, cannot. Additionally, certain components have placement restrictions — for instance, a Column must be added to a Column Container, and a Sidebar can only be added to a Page.

The Component tree provides a hierarchical view of your app’s user interface. It shows the top-down layout of UI components in your app, as well as the parent-child relationships between components, making it easier to understand your app’s structure and ensure that components are correctly nested.

You will find the Component tree useful when trying to reorganize the order of components in the UI, especially those located inside a parent UI component. For more flexibility and finer control, you can use the Component tree as a source or a destination for your drag and drop actions.

​
Discovering components

The Builder is designed to allow easy discoverability of components. Rather than scouring specifications every time you need to use a component, you can rely on the visual editor to guide you.

  1. Short description: You can hover on the component type to get a tooltip with a short description.
  2. Available properties and events: Looking at Settings will allow you to see which of its properties are configurable.
  3. Built-in docs: Components have short docs built into them. You can expand it by clicking the help icon in Settings.
  4. Event handler stub code: Different events need to be handled differently. The built-in stub handlers, which can be found next to each event, can help you get started when writing event handlers.

​
Selecting and editing components

To move or edit a component in your UI, you need to select it first. You can do this by clicking on the component either in the Canvas or in the Component tree. The selected component will be highlighted in both the Canvas and Component tree.

Selecting a UI component will allow you to view and edit its settings in the Component settings panel on the right side of the page.

To hide the Component settings panel to get a better view of the Canvas, click on » in the button bar. To show the panel, click on ⚙ in the button bar.

The settings in the Component settings panel are divided into the following sections:

​
Component shortcuts

The Component shortcuts bar contains a set of options to perform various operations that are often performed on components.

Options will be grayed out when they’re not applicable to the relevant component. Most shortcuts can also be activated using the keyboard; hover the cursor over a shortcut to see its keyboard shortcut.

The shortcuts are:

  • Add: Adds a child of a specified type to the selected component.
  • Move up: Decrements the position index of the selected component, used to sort children within the parent container.
  • Move down: Increments the position index of the selected component.
  • Cut: Cuts the selected component and places it in the clipboard.
  • Copy: Copies the selected component to the clipboard.
  • Paste: Pastes the content of the internal clipboard using the selected component as a parent.
  • Go to parent: Selects the parent of the selected component.
  • Delete: Deletes the selected component.

​
The Code editor and the Log

Writer Framework Builder provides a built-in Code editor for the main.py file, which defines the behavior of the app. You can toggle the Code panel by clicking the Code control near the lower left corner of the page:

Any changes made to the code do not take effect until you click the Save and run button, located at the upper right corner of the code editor.

The log is a useful debugging tool that displays any messages sent to standard output via the print() function, as well as any error messages. You can toggle the Log panel by clicking the Log control near the lower right corner of the page:

Note that both the Code editor and Log panes can be displayed at the same time:

​
Testing your app in Preview mode

In Preview mode, the overlays that let you build the user interface — the Core toolkit, Component tree, and Component settings — are invisible and unavailable. You see the app almost as your users would see it; the Top bar and Bottom bar, which your users would not see, are still available to you in Preview mode.

You can still use the Code editor and Log in Preview mode:

Backend-initiated actionsDataframe