Creator Guide

Learn to create an App Panel with sample files step-by-step. It takes ~10min to complete

The goal of this tutorial is to help you create a simple App Panel that you can use and adapt to your own code. Follow the five steps below to create an App Panel with sample files from a capsule in R.

1. Prepare a new capsule with sample files.

2. Set up the Parameters panel.

3. Lock the Parameters panel.

4. Run with parameters.

5. Set up the Result Files panel.

Prepare a New Capsule with Sample Files

App Panel works with code files that take input parameters in a capsule.

1. Create a new capsule using the R starter environment.

2. Click on Start with Sample Files to generate code and data that are ready for the App Panel.

You will see code and data files in /code and /data folders.

Click on main.R and run from /code. Drag the run file tab to the right so both files appear side-by-side in the viewer (see animated GIF below).

Set up the Parameters Panel

Set up the Parameters panel to map the input arguments in the code (e.g. main.R) to user inputs in the App Panel.

Click on the App Panel tab on the left (highlighted in red) to enter the Parameters and Result Files panels. The Parameters panel should be unlocked () by default.

You can set up the parameters in the unlock mode () only. Click on the lock icon () to lock/unlock.

Types of Parameters

App Panel supports three types of input parameters. The icons at the top of the Parameters panel represent each type:

Icon	Type	Functionality
	Text Parameter	Allows users to enter any string or number
	List Parameter	Allows users to select one value from a list
	File Parameter	Allows users to select an existing file under /data folder or upload a file from their local machine

main.R plots a sine function. You will set up the following three arguments in this example from main.R.

1. plot_title: the title of the figure in the result file.

2. number_of_cycles: # of cycles for the sine function.

3. input_data: a txt file that indicates the sampling rate.

The argumentsargs[x]in line 9-11 need to match with the three input parameters in the panel in sequential order from top to bottom. The following three tabs show you how to set the input parameters up respectively.

The following three tabs show you how to set up three parameters in the Parameters panel. Click on each tab for more details.

plot_title

The first parameter value you set up goes toargs[1]in the code. It is stored in plot_titleas the first argument. This parameter lets the viewer type the plot title by entering any text. A Text Parameter is the most appropriate parameter type here.

Click on in the Parameters panel to add a new Text Parameter section. Fill in the fields: Display Name (required) should inform the viewer of the meaning of this parameter (e.g., “Title”). Default Value (optional) is the value for the parameter (e.g. “Hello Code Ocean”). Click Add to create this parameter.
After you add the Title parameter, your Parameters panel should look like this.

number_of_cycles

The second parameter value you set up goes to args[2], which is stored in number_of_cycles as the second argument. This parameter lets the viewer choose the number of cycles for the plot. Both Text and List Parameters are suitable here, although using a List Parameter limits users to a list of predefined values.

Click on in the Parameters panel to add a new List Parameter section. Fill in the fields: Display Name represents the number of cycles (e.g. “# of cycles”). List Options allows you to add a list of inputs, each in a separate line as the options of cycles. In this example, you can enter 3, 5, and 7. Choose a Default Value from the drop-down menu (e.g., 3). Click Add to create this parameter.
After you add the # of Cycles parameter, your Parameters panel should look like this

input_data

The third parameter value you set up goes to args[3], which is stored in the variable input_dataas the third argument. This parameter lets the viewer choose the input file under the /data folder.

Files uploaded to the /data folder will appear in the drop-down menu.

Click on in the Parameter panel to create a new File Parameter section. Fill in the fields: Display Name represents the name of the parameter. (e.g. "Input data") Choose sample-data.txtas the Default Value from the drop-down menu that lists all the files under the /data folder. Click Add to create this parameter.
After you add the Input data parameter, your Parameters panel should look like this

Lock the Parameters Panel

Now that you set up the parameters, lock the panel so that other users can change the parameters without modifying the settings. Click on the unlock icon ( ) to switch the panel to lock mode ( ). In lock mode, the Parameters panel should look like this

Run with Parameters

After setting up the Parameters panel, click on Run with parameters on the upper right to execute the run script. Line 8 of the run file Rscript main.R "$@" runs the main.R file with the three parameters you just set up in the parameters panel (see what “$@” stands for).

Set up the Result Files Panel

After you've generated results, click on Add Result File +. Select the result file that you want to display after each run with parameters from the drop-down menu (e.g. fig1.png and fig2.png).

This is what the selected result files in this example look like

Set the Functionality Status

To lock the released capsule to App Panel only, set the Functionality Status to Run-only functionality available in the capsule metadata.

Share the Capsule

You just completed creating an App Panel. To share it with others, you can either share the capsule or release the capsule. To use and view an App Panel, go to the Viewer Guide.