App Builder

Overview

We’ve introduced the App Builder in the Quick Start section as your go-to tool for building new apps. Here, we’ll dive a bit deeper into each feature of the App Builder to help you manage your App Collections.

Note

If this is your first time opening the App Builder, please be sure to follow the Quick Start guide to complete the initial setup of your collection.

Tip

After you set up the App Builder for the first time, your configuration will be cached in your browser—meaning you won’t have to repeat the process every time you open the page! The same goes for any changes you make later on.

To open the App Builder, click here. Depending on which app you’ve loaded, you should see a page like this:

The page is very similar to the one you’ll see for an app from the App Library; however, it includes an extra Settings button:

You’ll use this menu to manage the content of your collections and, if you’re an admin for that collection, to perform admin operations (like deploying the collection to the Compute server, so it can be shared with others).

To open the App Builder Settings, click the Settings button mentioned earlier:

Setting up the App Collection

First, let’s talk about setting up an App Collection by taking a look at the Choose your App Collection Setup field:

Loading an existing collection

If you already have a collection stored on your computer, click the Load Existing Collection button to load it. A dialog will pop up where you can choose the App Collection directory to load:

Tip

If this dialog doesn’t appear automatically, click on the Compute Engine and it should pop up.

Creating a new collection

If you’d prefer to start a new App Collection, click the Start New Collection button. A dialog will prompt you to choose a name for your new collection:

After choosing a name for your App Collection, press the Ok button, and a new dialog will appear asking you where to save the collection directory. If the dialog doesn’t show up automatically, click on the Compute Engine and it should appear.

Once the App Collection is created successfully, you can inspect its contents by navigating to the directory you chose. You should see the same structure described here, with an empty apps/ directory.

Selecting an App to load

Next, let’s take a look at how you can select an existing app—or add a new one—to the selected App Collection using the Select Entry App field:

Adding a new app to the collection

To add a new app to the App Collection, click the + button on the right side of the field. This launches a dialog with a form where you can perform some initial configuration for the app. The information you provide will be used to create your app’s app_meta.yaml file.

Note

You can always modify this configuration directly in the app_meta.yaml file later. This step is just here to help you get started.

Some fields—like Authors, Discipline, and App Status—come with default values that you can change to suit your needs. The only required field is the App Title, which defines the title of the app that will be displayed to users in the App Library when deployed.

The Module Name field is automatically generated from your App Title. However, if you’d prefer a custom name for your app’s Python module, simply check the Custom Name checkbox and enter your desired name. Just make sure it follows PEP8’s package and module naming conventions!

Finally, check the Open new App in the default text editor checkbox to automatically open your default text editor when you create the app.

Change the entry app

If your loaded App Collection contains at least one app, you can select which app to load from the following drop-down menu:

Pressing the Ok button will reload the page with the selected entry app.

Collection Actions

This section provides features you can use at the collection level:

• Running checks on the loaded App Collection.
• Refreshing the App Collection.

Running Checks on the Collection

As you continue to add and modify your application code, it's important to ensure that your changes do not inadvertently break any of your apps. To help with this, click the Run Checks button to perform preliminary checks that verify your apps open without errors.

Info

These checks run the register_parameters and build_parameters methods on all your apps. They also ensure that there are no errors in the collection meta files (collection_requirements.yaml and app_meta.yaml).

If there are any errors, a new window will appear displaying the check results:

Each item represents a test suite – a group of tests that share a common name. It displays the test suite's name, its status (validated or failed), and the number of failed tests relative to the total tests.

You can also expand these test suites to view the results of each individual test:

For each test, you will see its name, status (validated or failed), an error message (if the test failed), and a description explaining what the test did.

To view the full error message for any failed test, click the Show Error Message button. This action opens a new window with the complete error details:

If the description is too long, click the ⓘ button to view the full test description:

After closing the check results window, if you want to view the previous results without running the tests again, click the button next to the Collection Validation Status in Collection Additional Info.

Refreshing the collection

When you make changes to the definitions of your App Collection
(for example, updating the collection_requirements.yaml file), you might notice that those changes aren’t immediately reflected—or you might even encounter errors. To fix this, simply refresh the App Collection by clicking the Refresh Collection button:

This action will rebuild the loaded App Collection using the current version of the collection_requirements.yaml file.

Note

You only need to do this when you change the collection_requirements.yaml file—not when you modify the app content itself!

Admin Operations

If you have the admin role for an App Collection, you’ll see an additional section in the App Builder Settings that lets you manage the App Collection's content hosted on the Compute server:

To start managing your App Collection's content, first choose an App Collection from the drop-down menu:

Downloading Collection

You can download the currently hosted version of the selected App Collection from the Compute server as a zip file by clicking the Download button:

The button will display a spinning animation while it’s downloading and will be grayed out.

If the download is successful, a green message will appear in the bottom right corner of the page:

Depending on your browser settings, the downloaded zip file will either be saved in your browser’s default download directory or you’ll be prompted to choose a location.

Deploying Collection

To share your App Collection with users subscribed to it, you first need to deploy it. Simply click the Deploy button to start the deployment process:

Before proceeding, a dialog will ask you to enter the name of the selected App Collection. This security feature helps ensure that you don’t accidentally deploy the collection:

If the deployment is successful, you’ll see a green message in the bottom right corner of the page.

You can now go to the App Library to view your updated App Collection. Users subscribed to the collection will also see these apps.

Danger

Please note that every time you Deploy an App Collection, the contents hosted on the Compute server are first purged before being updated.

Warning

Before the collection is deployed, some preliminary Checks will be executed to ensure that the collection builds without errors. If an error is found, a new window will open with the test results, as shown in the Running Checks Section. Please make sure you have a backup of your App Collection before proceeding.

Purging Collection

To remove the contents of the selected App Collection from the Compute server, click the Purge button:

Before proceeding, a dialog will ask you to confirm the purge action:

Danger

Similarly to deploying a collection, please ensure that you have backups of the App Collection before proceeding.

A green message will appear in the bottom left corner of the page if the purge is successful.

Collection Additional Info

At the bottom of the App Builder Settings, you can find additional information about the loaded App Collection — including the path to the selected collection, the number of apps currently loaded and the validation status of the collection.

Applying Changes

To apply the changes you’ve made in the App Builder Settings, press the Ok button:

This action will do two things:

• Load the selected Entry App on the App Builder page.
• Save your current configuration in your browser’s memory.

By caching your configuration, the next time you open the App Builder page, it will automatically load your previously defined settings.

If you’d like to discard any changes made in the App Builder Settings, simply press the Cancel button.