UI Builder Tutorial.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"well well-sm col-md-5 pull-right\" style=\"margin-left:30px;\">\n",
    "    <h2>Table of Contents</h2>\n",
    "    <ul>\n",
    "        <li><a href=\"#Building-the-UI\">Building the UI</a></li>\n",
    "        <li><a href=\"#Python-Variables-&-String-Literals\">Python Variables & String Literals</a></li>\n",
    "        <li><a href=\"#String-Serialization\">String Serialization</a></li>\n",
    "        <li><a href=\"#Rendering-Existing-Functions\">Rendering Existing Functions</a></li>\n",
    "        <li><a href=\"#Overriding-Properties\">Overriding Properties</a></li>\n",
    "        <li><a href=\"#Overriding-Parameters\">Overriding Parameters</a></li>\n",
    "        <li><a href=\"#Hiding-Parameters\">Hiding Parameters</a></li>\n",
    "        <li><a href=\"#Output-Variable\">Output Variable</a></li>\n",
    "        <li><a href=\"#Parameter-Types\">Parameter Types</a></li>\n",
    "        <li><a href=\"#Client-side-Interactivity\">Client-side Interactivity</a></li>\n",
    "        <li><a href=\"#Tool-Registry\">Tool Registry</a></li>\n",
    "        <li><a href=\"#Files-in-Markdown-Cells\">Files in Markdown Cells</a></li>\n",
    "        <li><a href=\"#Send-to-Text\">Send to Text</a></li>\n",
    "        <li><a href=\"#UI-Output\">UI Output</a></li>\n",
    "        <li><a href=\"#Conclusion\">Conclusion</a></li>\n",
    "    </ul>\n",
    "</div>\n",
    "\n",
    "# UI Builder Tutorial\n",
    "\n",
    "This is a tutorial that demonstrates how to use the UI Builder, a feature of the [GenePattern Notebook](http://genepattern-notebook.org) environment which allows a notebook author to easily turn any Python function into an interactive widget.\n",
    "\n",
    "This widget will render itself in a notebook as an interactive web form. By default, it uses the docstring of the function as a description, it will infer parameter types from default values and will display parameter\n",
    "annotations as helpful text near each input.\n",
    "\n",
    "This tutorial assumes that the reader has basic knowledge of Python programming. It also assumes that [nbtools](https://github.com/genepattern/nbtools) is installed and its Jupyter nbextension enabled (this is part of GenePattern Notebook). If not, install instructions are available at the webpage linked above."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-info\">\n",
    "<h3 style=\"margin-top: 0;\"> Instructions <i class=\"fa fa-info-circle\"></i></h3>\n",
    "Throughout the tutorial, instructions will be given in blue boxes that look like this.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Building the UI\n",
    "\n",
    "The simplest way to render a function using the UI Builder is to import the `nbtools` package and then attach the `@build_ui` decorator. An example of this is given below."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-info\">\n",
    "<h3 style=\"margin-top: 0;\"> Instructions <i class=\"fa fa-info-circle\"></i></h3>\n",
    "Run the code below. If everything is working properly, the code will disappear and be replaced with a UI Builder widget. To see the code again, go to the gear menu in the upper right and select \"Toggle Code View.\" \n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "import nbtools\n",
    "\n",
    "@nbtools.build_ui\n",
    "def example_function(first_parameter, second_parameter):\n",
    "    \"\"\"Do something\"\"\"\n",
    "    print('Do something...')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### The UIBuilder Class\n",
    "\n",
    "Alternatively, a UI Builder widget may defined and referenced directly. To render a function in this way, simply import the `UIBuilder` class from the `nbtools` package and pass the function to the `UIBuilder` constructor. To display the widget, just return the `UIBuilder` object in a Jupyter code cell or call `IPython.display.display()`, passing in the `UIBuilder` object as a parameter. An example of this is below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "from nbtools import UIBuilder\n",
    "\n",
    "def direct_example(first_parameter, second_parameter):\n",
    "    \"\"\"Do something\"\"\"\n",
    "    print('Do something...')\n",
    "\n",
    "# Create the UIBuilder object and immediately return it for display in Jupyter\n",
    "UIBuilder(direct_example)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Python Variables & String Literals\n",
    "\n",
    "Python variables may be used as input when filling out a UI Builder form. To do this, simply type the name of the variable into the input field. When the form is submitted, the widget will pass a reference to the variable in the resulting function call.\n",
    "\n",
    "Conversely, to ensure that an input value is evaluated as a string literal rather than a variable name, a user can wrap the input to a particular field in either single or double quotes (' or \"). This tells the UI Builder to skip checking for variable names and to treat the value in quotes as a literal string. For example, forcing the string foo to be treated as a string literal would be entered in the input field as: `\"foo\"`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-info\">\n",
    "<h3 style=\"margin-top: 0;\"> Instructions <i class=\"fa fa-info-circle\"></i></h3>\n",
    "Run the two code cells below. The first defines the variable `foo` and the second creates a simple UI Builder widget. Enter `foo` as input to the widget and click \"Run.\" Observe what happens. Then do the same with `\"foo\"` (including quotes).\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "foo = \"This is a Python variable\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "@nbtools.build_ui\n",
    "def variable_example(input_text):\n",
    "    \"\"\"Print what was input\"\"\"\n",
    "    print(input_text)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## String Serialization\n",
    "\n",
    "The input to a UI Builder form may include a string representation of a variable's value rather than a reference to the variable itself. This is useful for embedding the value inside a larger string, or when a variable reference would be unwanted.\n",
    "\n",
    "This functionality can be achieved by placing the variable name inside double curly brackets. For example, embedding the string serialization of the variable\n",
    "`foo` would be entered into an input field as: `{{ foo }}`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-info\">\n",
    "<h3 style=\"margin-top: 0;\"> Instructions <i class=\"fa fa-info-circle\"></i></h3>\n",
    "Try entering `{{ foo }}` into the UI Builder widget above and observe the results.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Rendering Existing Functions\n",
    "\n",
    "Existing Python functions, such as those included in third-party Python libraries, can also be used with the UI Builder. To display an existing function, first import it and then pass the function into the constructor of a `UIBuilder` object. Return this object in a cell to display the resulting widget. For example,\n",
    "the code for displaying the `os` module's `chdir` function is given below."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-info\">\n",
    "<h3 style=\"margin-top: 0;\"> Instructions <i class=\"fa fa-info-circle\"></i></h3>\n",
    "Run the cell below and enter a directory path, such as \"..\" Then click \"Run.\"\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "from os import chdir\n",
    "\n",
    "UIBuilder(chdir)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Overriding Properties\n",
    "\n",
    "By default, the widget name will be the function name, the description will be the docstring of the function and the parameter names will be the same as the parameters defined in the code. All of these, however, can be manually overridden. This is particularly useful when providing better names or descriptions that users would find helpful.\n",
    "\n",
    "To override the default values, optional parameters may be passed into the `build_ui` decorator or into the `UIBuilder` constructor. Examples of overriding the widget name and description are shown below."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-info\">\n",
    "<h3 style=\"margin-top: 0;\"> Instructions <i class=\"fa fa-info-circle\"></i></h3>\n",
    "Run the examples below and examine the overridden values.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "@nbtools.build_ui(name=\"Simple Example\", description=\"This is an example function.\")\n",
    "def override_example(param_1, param_2):\n",
    "    \"\"\"Override defaults\"\"\"\n",
    "    print('Override...')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The same effect can be also achieved when directly instantiating a `UIBuilder` object.\n",
    "\n",
    "This example also demonstrates overriding the canonical name of the function being rendered. This is sometimes helpful if the function has been imported into the code in a non-top level namespace."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "import os\n",
    "\n",
    "UIBuilder(os.chdir,\n",
    "          name=\"Change Directory\",\n",
    "          description=\"Change the working directory\",\n",
    "          function_import=\"os.chdir\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Overriding Parameters\n",
    "\n",
    "The names and descriptions of individual parameters may also be overridden. To do this, pass a dict to the `build_ui` decorator or the `UIBuilder` constructor with the parameter's name as the key and a dict of the properties to override as the value.\n",
    "\n",
    "An example is given below which overrides the name, description and the default value of a parameter, and sets it as optional."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "@nbtools.build_ui(parameters={\n",
    "    \"param_1\": {\n",
    "        \"name\": \"foo\",\n",
    "        \"description\": \"This parameter has been renamed.\",\n",
    "        \"default\": \"bar\",\n",
    "        \"optional\": True\n",
    "    }\n",
    "})\n",
    "def override_example2(param_1):\n",
    "    \"\"\"Override parameter defaults\"\"\"\n",
    "    print('Override...')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Hiding Parameters\n",
    "\n",
    "Sometimes a particular function has parameters that shouldn't be changed in the current context or which the notebook author does not wish to expose. The UI Builder has the ability to hide the input for these parameters, simplifying the user interface and allowing users to focus only on the relevant inputs. \n",
    "\n",
    "When the function is called, these hidden parameters will automatically use their default values. This may be combined with overriding the default value for the parameter in question in order to force a particular input.\n",
    "\n",
    "An example is given below in which several parameters are hidden."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-info\">\n",
    "<h3 style=\"margin-top: 0;\"> Instructions <i class=\"fa fa-info-circle\"></i></h3>\n",
    "Run the cell below and then examine the parameters.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "@nbtools.build_ui(parameters={\n",
    "    \"param_2\": { \n",
    "        \"hide\": True, \n",
    "        \"default\": \"Default value\" \n",
    "    }\n",
    "})\n",
    "def hiding_example(param_1, param_2):\n",
    "    \"\"\"Hide parameters\"\"\"\n",
    "    print(param_2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Output Variable\n",
    "\n",
    "The result of a UI Builder function can optionally be assigned to a Python variable. By default, a text field for this variable will appear at the bottom of each UI Builder widget. This field can be overridden just like any other parameter using the `output_var` parameter name. An example is given below."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-info\">\n",
    "<h3 style=\"margin-top: 0;\"> Instructions <i class=\"fa fa-info-circle\"></i></h3>\n",
    "Run the code below and note that the output variable is hidden. View the code and remove the `\"hide\": True,` line. Run the cell again and note that the output variable is shown, but its name and description are overridden.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "@nbtools.build_ui(parameters={\n",
    "    \"output_var\": {\n",
    "        \"name\": \"output\",\n",
    "        \"default\": \"results\",\n",
    "        \"description\": \"The results of the function\",\n",
    "        \"hide\": True,\n",
    "    }\n",
    "})\n",
    "def output_var_example(param_1):\n",
    "    \"\"\"Override and hide the output variable\"\"\"\n",
    "    return param_1"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Parameter Types\n",
    "\n",
    "The UI Builder supports a number of parameter types and implements features to make handling those types easier. Supported types include:\n",
    "\n",
    "* **text:** Supports any text value. Unless referencing an existing Python variable, any input gets cast to a Python string value. Text is also the default\n",
    "  parameter type if no other type information has been specified or can be determined.\n",
    "* **number:** Accepts any numerical value and renders itself in a notebook as an HTML number input.\n",
    "* **password:** Works exactly like a text input, but obfuscates the input value as a password field.\n",
    "* **choice:** When provided with a list of choices, this input will render as a dropdown parameter, with the default value selected. Choice parameters are\n",
    "  described in their own section below.\n",
    "* **bool:** A boolean input representing True and False. Renders as a choice parameter with those two options.\n",
    "* **file:** An input intended to receive a file or file-like object. File parameters are described in their own section below.\n",
    "\n",
    "The UI Builder will infer a parameter's type from its default value, defaulting to a text parameter if no value is available or if the default value's type doesn't match one of the known types above. Alternatively, the developer can specify a parameter's type in the code. An example is provided below. It illustrates how to specify each type, except for choice and file parameters, which are each detailed in their own sections."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-info\">\n",
    "<h3 style=\"margin-top: 0;\"> Instructions <i class=\"fa fa-info-circle\"></i></h3>\n",
    "Run the code below and enter values for each parameter.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "@nbtools.build_ui(parameters={\n",
    "    \"a_text_param\": {\n",
    "        \"type\": \"text\"\n",
    "    },\n",
    "    \"a_number_param\": {\n",
    "        \"type\": \"number\"\n",
    "    },\n",
    "    \"a_password_param\": {\n",
    "        \"type\": \"password\"\n",
    "    },\n",
    "    \"a_bool_param\": {\n",
    "        \"type\": \"bool\"\n",
    "    },\n",
    "})\n",
    "def type_example(a_text_param, a_number_param, a_password_param, a_bool_param=True):\n",
    "    \"\"\"Parameter type example\"\"\"\n",
    "    print([a_text_param, a_number_param, a_password_param, a_bool_param])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Choice Parameters\n",
    "\n",
    "Sometimes a parameter only accepts a limited set of valid input values. This is often represented in a user interface as a dropdown (select) input. The UI Builder has support for this functionality. To change a particular parameter into a dropdown input, simply set the type to \"choice\" and provide the parameter with a dictionary of available choices."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-info\">\n",
    "<h3 style=\"margin-top: 0;\"> Instructions <i class=\"fa fa-info-circle\"></i></h3>\n",
    "Run the code below and examine the resulting UI Builder widget.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "@nbtools.build_ui(parameters={\n",
    "    \"param_1\": {\n",
    "        \"default\": \"some_value\",\n",
    "        \"type\": \"choice\",\n",
    "        \"choices\": {\n",
    "            \"foo label\": \"foo value\",\n",
    "            \"bar label\": \"bar value\",\n",
    "            \"some_label\": \"some_value\"\n",
    "        }\n",
    "    } \n",
    "})\n",
    "def choice_example(param_1):\n",
    "    \"\"\"Select a value from a dropdown\"\"\"\n",
    "    print(param_1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### File Parameters\n",
    "\n",
    "File parameters are intended to handle input representing a file or file-like object. They are also integrated with UI Output widgets (covered later in the tutorial). Files output by those widgets will be displayed as options when a file parameter is selected.\n",
    "\n",
    "Optionally, the developer can specify the kinds of files that a file parameter accepts. This is accomplished by providing a list of file extensions. For example, a parameter that expects a gct, odf or res file would list: `[\"gct\", \"odf\", \"res\"]`.\n",
    "\n",
    "It is worth noting that when a file is selected in the menu, the value provided to the function will actually be a string containing a path or URL to the specified file. This may be used to create a file-like object."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-info\">\n",
    "<h3 style=\"margin-top: 0;\"> Instructions <i class=\"fa fa-info-circle\"></i></h3>\n",
    "Run the code below and examine the resulting UI Builder widget. Try entering a file path or URL then click \"Run.\" Repeat this process, but this time select a file to upload.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "@nbtools.build_ui(parameters={\n",
    "    \"param_1\": {\n",
    "        \"type\": \"file\",\n",
    "        \"kinds\": [\"gct\", \"odf\"]\n",
    "    }\n",
    "})\n",
    "def file_example(param_1):\n",
    "    \"\"\"Create a file parameter\"\"\"\n",
    "    print(param_1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Similar to choice parameters, a file parameter may likewise be given a list of possible options. These options will appear in a dropdown when the parameter it selected."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-info\">\n",
    "<h3 style=\"margin-top: 0;\"> Instructions <i class=\"fa fa-info-circle\"></i></h3>\n",
    "Run the code below and examine the resulting UI Builder widget. Click on the file parameter and then select one of the options in the dropdown that appears.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "@nbtools.build_ui(parameters={\n",
    "    \"param_1\": {\n",
    "        \"type\": \"file\",\n",
    "        \"choices\": {\n",
    "            \"Example Label #1\": \"ftp://fake.example.com/example_1.csv\",\n",
    "            \"Example Label #2\": \"ftp://fake.example.com/example2.csv\",\n",
    "            \"Example Label #3\": \"ftp://fake.example.com/example_3.csv\"\n",
    "        }\n",
    "    }\n",
    "})\n",
    "def file_choice_example(param_1):\n",
    "    \"\"\"Create a file parameter with choices\"\"\"\n",
    "    print(param_1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Client-side Interactivity\n",
    "\n",
    "Notebook authors who wish to integrate the UI Builder with client-side programmatic functionality can make use of the `id` and `events` attribute of a parameter.\n",
    "\n",
    "The `id` attribute allows the author to specify an ID for the parameter's element in the DOM. As with all IDs, it must be both unique and [adhere to the naming rules in the HTML specification](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id).\n",
    "\n",
    "The `events` attribute allows the author to attach Javascript functionality to a parameter. This should be specified in a dict, where the keys are Javascript events and the values are strings containing the Javascript code to be executed."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-info\">\n",
    "<h3 style=\"margin-top: 0;\"> Instructions <i class=\"fa fa-info-circle\"></i></h3>\n",
    "Run the cell below, then click on the `param_1` input. Note how this pops up a Javascript alert. If you are familiar with client-side development, you may also use your browser's dev tools to example the parameter's DOM node and note that it has been given the specified ID attribute. If you're not familiar with Javascript, feel free to skip this step.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "@nbtools.build_ui(parameters={\n",
    "    \"param_1\": {\n",
    "        \"id\": \"example_function_param_1\",\n",
    "        \"events\": {\n",
    "            \"click\": \"alert('You clicked the parameter!');\"\n",
    "        }\n",
    "    }\n",
    "})\n",
    "def interactivity_example(param_1):\n",
    "    \"\"\"Interactive example\"\"\"\n",
    "    print(param_1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### UI Builder Client-Side Events\n",
    "\n",
    "Similar to the client-side functionality above, the top-level `events` attribute is available for handling events associated with the UI Builder widget itself, rather than events associated individual parameters. It accepts a dict pairing event names to strings containing Javscript code to be executed when the event occurs. Supported events are listed below:\n",
    "                \n",
    "* **load:** Executed when the widget is initialized.\n",
    "* **run:** Event fires when the Run button is clicked.\n",
    "* **click:** Executed when the widget is clicked.\n",
    "* **focus:** Event fires when the widget obtains focus."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-info\">\n",
    "<h3 style=\"margin-top: 0;\"> Instructions <i class=\"fa fa-info-circle\"></i></h3>\n",
    "Run the cell below. Note how a Javascript alert pops up when the widget is loaded. Then click the \"Run\" button on the widget and note how another alert pops up when the function is executed.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "@nbtools.build_ui(\n",
    "    events={\n",
    "        \"load\": \"alert('Alert when the widget is loaded.')\",\n",
    "        \"run\": \"alert('Alert when the Run button is clicked.')\"\n",
    "    }\n",
    ")\n",
    "def events_example(param_1=\"Events\"):\n",
    "    print(param_1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Tool Registry\n",
    "\n",
    "By default, UI Builder widgets will register themselves with the Notebook Tool Manager. This allows one to develop a standard library of functions which can be used interchangibly throughout a notebook. If this behavior is not desired, this can be disabled using the `register_tool` parameter."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-info\">\n",
    "<h3 style=\"margin-top: 0;\"> Instructions <i class=\"fa fa-info-circle\"></i></h3>\n",
    "Click on the \"<i class=\"fa-th fa\"></i> Tools\" button in the toolbar at the top of the page. Look through the list of UI Builder widgets that you created earlier in the tutorial. Then run the cell below. It creates a UI Builder widget, but does not register it with the Tool Manager.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "@nbtools.build_ui(register_tool=False)\n",
    "def no_register_example(param_1=''):\n",
    "    \"\"\"Do not register the tool.\"\"\"\n",
    "    print(param_1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Files in Markdown Cells\n",
    "\n",
    "Sometimes it is beneficial to the narrative of a notebook to link an externally-hosted file in a markdown cell and then to use that file as input to a UI Builder function. This can be made easier by annotating the external file link with the `nbtools-markdown-file` class. Doing so will make the file automatically appear as an option in file parameters."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-info\">\n",
    "<h3 style=\"margin-top: 0;\"> Instructions <i class=\"fa fa-info-circle\"></i></h3>\n",
    "<p>Turn the first code cell below into a markdown cell and remove the `%%html` line. Run the cell to create a link annotated with the `nbtools-markdown-file` class. (Normally you would not need to go through all this, but we wanted to display the code to start with.)</p>\n",
    "\n",
    "<p>Once you see the link, run the next code cell to create a UI Builder widget with a file parameter. Click on the file parameter and note how the file automatically appears in the dropdown.</p>\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "%%html\n",
    "\n",
    "<a class=\"nbtools-markdown-file\" href=\"https://datasets.genepattern.org/data/all_aml/all_aml_test.cls\">An annotated link to an external file.</a>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "@nbtools.build_ui(parameters={\n",
    "    \"param_1\": {\n",
    "        \"type\": \"file\",\n",
    "        \"kinds\": [\"cls\"]\n",
    "    }\n",
    "})\n",
    "def markdown_file_example(param_1):\n",
    "    \"\"\"Markdown file example\"\"\"\n",
    "    print(param_1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Send to Text\n",
    "\n",
    "Similar to annotating file links, specific text output can also be annotated for easy use with text parameters. To do this, give the text the `nbtools-text-option` class. Any text annotated in this way will appear in a dropdown whenever a text input parameter is selected."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-info\">\n",
    "<h3 style=\"margin-top: 0;\"> Instructions <i class=\"fa fa-info-circle\"></i></h3>\n",
    "<p>Turn the first code cell below into a markdown cell and remove the `%%html` line. Run the cell to create text annotated with the `nbtools-text-option` class. As with the example above, this step is necessary to prevent Jupyter from rendering the HTML automatically.</p>\n",
    "\n",
    "<p>Once you see the text, run the next code cell to create a UI Builder widget with a text parameter. Click on the parameter and note how the text automatically appears in a dropdown.</p>\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "%%html\n",
    "\n",
    "<span class=\"nbtools-text-option\">Text to send to parameter</span>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "@nbtools.build_ui\n",
    "def send_to_text_example(param_1):\n",
    "    \"\"\"Send to text example\"\"\"\n",
    "    print(param_1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# UI Output\n",
    "\n",
    "The UI Output widget is a companion widget to the UI Builder. It is intended to be used as the output to a UI Builder cell. When displayed, it presents output files, text or other information in a manner consistant with the GenePattern Notebook user interface."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Creating the Widget\n",
    "\n",
    "The simplest way to create a UIOutput widget is to import it and call the constructor directly. An example is given below, passing in an optional name and description. A full list of parameters is detailed in the next section."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-info\">\n",
    "<h3 style=\"margin-top: 0;\"> Instructions <i class=\"fa fa-info-circle\"></i></h3>\n",
    "Run the cell below and examine the widget.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "from nbtools import UIOutput\n",
    "\n",
    "UIOutput(name='Example Output', description='This describes the results of the function.')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Parameters\n",
    "\n",
    "UI Output widgets support several parameters which can be used to provide content. They are:\n",
    "\n",
    "* **name:** Specifies the name of the UI Output widget.\n",
    "* **description:** Used to set the description that is displayed at the top of the widget.\n",
    "* **files:** An array of URLs or file paths. Used to integrate file outputs with the file input parameters found in the UI Builder.\n",
    "* **text:** Display the contents of this parameter as output text.\n",
    "* **status:** A terse indicator of the output status. Can be dynamically updated as an analysis progresses (see below)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-info\">\n",
    "<h3 style=\"margin-top: 0;\"> Instructions <i class=\"fa fa-info-circle\"></i></h3>\n",
    "Run the cell below and note the ways in which is can provide output.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "uio = UIOutput(name='Parameter Output', \n",
    "               description='Show the content that can be provided.',\n",
    "               files=['file_1.txt', './file_2.txt', '/home/path/file_3.txt'],  # Pretend files\n",
    "               text=\"The results of stdout can be directed here.\",\n",
    "               status=\"Running\")\n",
    "display(uio)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Dynamically Updating Status\n",
    "\n",
    "The status of a UI Output widget can be dynamically updated by setting the status property of the widget object. This is useful for long-running analyses and allows a function to alert the user when an analysis is complete, or when a new stage of analysis has been reached."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-info\">\n",
    "<h3 style=\"margin-top: 0;\"> Instructions <i class=\"fa fa-info-circle\"></i></h3>\n",
    "Run the code below and note how the status changes in the UIOutput widget above.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# Perform long-running analysis and then update status\n",
    "uio.status = \"Complete\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Conclusion\n",
    "\n",
    "This concludes the tutorial on how to use GenePattern Notebook's UI Builder functionality. For more information, please see the [GenePattern Notebook documentation](http://www.genepattern-notebook.org/programmatic/)."
   ]
  }
 ],
 "metadata": {
  "genepattern": {
   "repository_url": "http://notebook.genepattern.org/services/sharing/notebooks/294/"
  },
  "kernelspec": {
   "display_name": "Python 3.7",
   "language": "python",
   "name": "python3.7"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}