{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Jupyter-flex allows you to create interactive dashboards based on Jupyter Notebooks by adding tags to notebooks cells and controlling the layout of the dashboard using markdown headers. \n",
    "\n",
    "## Your first dashboard\n",
    "\n",
    "Let's take a very simple Jupyter Notebook with 3 cells and one plot and convert it to a dashboard."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import plotly.express as px"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df = px.data.iris()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "fig = px.scatter(df, x=\"sepal_width\", y=\"sepal_length\")\n",
    "fig.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "All you need to do to convert this to a dashboard is to add tag with the value `chart` to the cell with the plot.\n",
    "\n",
    "<div class=\"admonition tip\">\n",
    "    <p class=\"admonition-title\">How to view and add tags to cells in Jupyter Notebook</p>\n",
    "    <ol>\n",
    "        <li>In the top navigation go to View > Cell Toolbar > Tags</li>\n",
    "        <li>Then type \"chart\" in the target cell and click on \"Add tag\"</li>\n",
    "    </ol>\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": [
     "chart"
    ]
   },
   "outputs": [],
   "source": [
    "fig = px.scatter(df, x=\"sepal_width\", y=\"sepal_length\")\n",
    "fig.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Converting Notebook to a dashboard \n",
    "\n",
    "From here there is a couple of options to convert the notebook to a html dashboard.\n",
    "\n",
    "1. You can execute the notebook as you normaly do in the Jupyter Notebook UI and then select: `File > Download as > Flex Dashboard (.html)`:\n",
    "![Jupyter-flex Download As](/assets/img/getting-started/download-as.png)\n",
    "2. You can go in a terminal and run `nbconvert`:\n",
    "\n",
    "<p class=\"code-header\">Terminal</p>\n",
    "```\n",
    "$ jupyter nbconvert --to flex notebook.ipynb\n",
    "```\n",
    "\n",
    "Optionally add the `--execute` flag to execute the notebook before converting it\n",
    "\n",
    "<p class=\"code-header\">Terminal</p>\n",
    "```\n",
    "$ jupyter nbconvert --to flex notebook.ipynb --execute\n",
    "```\n",
    "\n",
    "Open the resulting `.html` file in a browser and the result will be:\n",
    "\n",
    "[![Jupyter-flex one plot](/assets/img/screenshots/getting-started/one-plot.png)](/examples/one-plot.html)\n",
    "\n",
    "You might notice that the default title of the dashboard is the name of the notebook file, you can customize these using [parameters](#orientation-and-title).\n",
    "\n",
    "This is a very simple example, now let's look at the card concept of Jupyter-flex."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Cards: Multiple outputs\n",
    "\n",
    "A card is an object that holds any output components of the dashboard such as plots, text, widgets and more.\n",
    "\n",
    "In the previous Notebook it holds the one plot. To learn more about cards and its options go to [Layout > Cards](http://localhost:8000/layout/#cards).\n",
    "\n",
    "You define a new Card by adding a level-3 markdown header (`###`).\n",
    "\n",
    "Any output components (plots or text) will be added to the current Card until a new Card, Section or Page is defined.\n",
    "\n",
    "Going back to the notebook example we can add a new plot to the by adding two new cells:\n",
    "\n",
    "1. One markdown cell with a level-3 markdown header (`###`)\n",
    "2. One code cell with the `chart` tag"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "### Second plot"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": [
     "chart"
    ]
   },
   "outputs": [],
   "source": [
    "fig = px.scatter(df, x=\"petal_width\", y=\"petal_length\")\n",
    "fig.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[![Jupyter-flex two plots](/assets/img/screenshots/getting-started/two-plots.png)](/examples/two-plots.html)\n",
    "\n",
    "You will notice that the default layout is a single column with cards stacked vertically and sized to fill available browser height."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Sections: multiple columns\n",
    "\n",
    "To add another column to the dashboard use a level 2 markdown header (`##`).\n",
    "\n",
    "In this case, the value of the header is irrelevant, it's just an indicator to create a new Section."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "## Column"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": [
     "chart"
    ]
   },
   "outputs": [],
   "source": [
    "fig = px.scatter(df, x=\"sepal_length\", y=\"petal_length\")\n",
    "fig.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this case the result would be:\n",
    "\n",
    "[![Jupyter-flex two columns](/assets/img/screenshots/getting-started/two-columns.png)](/examples/two-columns.html)\n",
    "\n",
    "You can see that the default orientation is to have multiple sections as columns."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Parameters: Orientation and title\n",
    "\n",
    "You can control the parameters of the dashboard such as title and orientation to be based of rows instead on columns\n",
    "by tagging a code cell to as `parameters`.\n",
    "\n",
    "It's usually a good idea to have this cell at the beginning of the notebook.\n",
    "\n",
    "Let's change the orientation of the plot to `rows` and add a title of `A Flex dashboard`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": [
     "parameters"
    ]
   },
   "outputs": [],
   "source": [
    "flex_title = \"A flex dashboard\"\n",
    "flex_orientation = \"rows\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[![Jupyter-flex two rows](/assets/img/screenshots/getting-started/two-rows.png)](/examples/two-rows.html)\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Learning more\n",
    "\n",
    "Well done! You have created you first Flex dashboard.\n",
    "\n",
    "The [Layouts](/layouts) page goes in depth about all the options to control the content of Jupyter-flex dashboards.\n",
    "\n",
    "The [Plotting](/plotting) page goes through some considerations around different plotting libraries in Jupyter-flex dashboards.\n",
    "\n",
    "The [Voila and IPywidgets](/voila-ipywidgets/) page describes how to leverage Voila to create dashboards that use a live Jupyter kernel that enable viewers to change underlying parameters and see the results immediately using [ipywidgets](https://ipywidgets.readthedocs.io/)."
   ]
  }
 ],
 "metadata": {
  "celltoolbar": "Tags",
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "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.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}