Why create an App Panel?
Building an app panel will let other users interact with the code in a more accessible and friendly fashion, by entering or choosing the values for the set of parameters you make available to them.
In this article, we will help you create a simple app panel with the example R script that you can use and adapt to your own code.
Prepare a New Capsule with Sample Files
App Panel works with code files that take input parameters in a capsule.
Create a new capsule using the R starter environment.
Click on Start with Sample Files to generate code and data that are ready for the App 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 Builder tab on the left (highlighted in red) to enter the Parameters and Result Files panels. The Parameters panel should be unlocked by default.
The App Builder contains four separate sections. In this guide, we will continue use the sample file to fill in each of the sections.
General - covers basic information about the App
Data - enables the attaching of data assets that can be swapped out
Parameters - set configurable parameters that are sent as arguments to run the script
Display Result After Run - choose output files to display in the main window
General Information
This section allows you to set the title for the application along with a short description of the App usage. It is recommended to create aREADME.mdfile along with the application to help users understand the functionality of the tool, the inputs and outputs of the application, and any additional necessary information.
The example below shows the completion of the General section. This capsule plots a sine function.
Types of Parameters
App Panel supports three types of input parameters. The icons at the top of the Parameters panel represent each type:
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
/datafolder 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.
plot_title: the title of the figure in the result file.number_of_cycles: # of cycles for the sine function.input_data: a txt file that indicates the sampling rate.
The arguments args[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 session shows you how to set the input parameters up respectively.
plot_title
The first parameter value you set up goes to args[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 the text icon in the Parameters section to add a new Text Parameter. Fill in the fields and Save to create the parameter.
Label (required) should inform the viewer of the meaning of this parameter, for example, Title.
Default Value (optional) is the value for the parameter for example, “Hello Code Ocean”.
Description (optional) is a brief description of the parameter, this will appear as a hover-over explanation for the information icon, for example, This sets the title for the output plots.
The result of the saved text parameter.
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.
Same as previous, click on the list icon in the Parameters section to add a new List Parameter. Fill in the fields and Save to create the parameter.
Label (required) represents the number of cycles, for example, # of cycles.
List Values (required) 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.
Default Value (optional) allows you to choose a default. In this example select 3 from the drop-down menu.
Description (optional) is a brief description of the parameter, Sets the number of cycles to generate the sine plot.
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.
Note: Files uploaded to the /data folder will appear in the drop-down menu.
Click on the file icon in the Parameters section to add a new File Parameter. Fill in the fields and Save to create the parameter.
Label (required) should indicate the function of this parameter, for example, Input Points File".
Default Value (optional) is the parameter value for example, /data/Sample_Input/sample-data.txt
Description (optional) is a brief description of the parameter and will appear as a hover-over explanation for the information icon, for example, Path to the input file containing the points that will determine the length of the sine plot.
After you add the Input data parameter, your Parameters panel should look like this
Swapping the Order of App Panel Parameters
To swap the order that the App Panel Parameters are displayed. In Build Mode
select the six ellipses
. Drag and drop the Parameters into the required order.
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).
Display Result after Run
This allows you to set results to display to the user after running the capsule. These are static paths, so the outputs will need to have the same name for every run. In this example, fig1.png and fig2.png are always output, they can be set as the results display.
Note: a reproducible run must be done in order to see available results files to display after the run.
After adding both results:
The final looks of the App Panel:
Example capsules